Aangepaste instrumentatie voor Elixir - AppSignal Documentation

Om erachter te komen welke specifieke stukken code performanceproblemen veroorzaken, is het handig om aangepaste instrumentatie aan uw applicatie toe te voegen. Dit stelt ons in staat om betere uitsplitsingen te maken van welke code het langzaamst draait en op welk type actie de meeste tijd is besteed. Aangepaste instrumentatie is op twee manieren mogelijk: met behulp van function decorators en instrumentatiehulpfuncties. De function decorators zijn het eenvoudigst te gebruiken, maar zijn minder flexibel dan de instrumentatiehulpfuncties. Deze korte handleiding helpt u bij het opzetten van aangepaste instrumentatie. Meer details over het gebruik van bepaalde helpers vindt u in de Hex-docs voor het AppSignal-pakket.

Opmerking: Zorg ervoor dat u AppSignal heeft geïntegreerd voordat u aangepaste instrumentatie aan uw applicatie toevoegt als dit niet automatisch is geïntegreerd door een van onze ondersteunde integraties.

Opmerking: Deze pagina beschrijft alleen hoe u performance-instrumentatie aan uw code toevoegt. Lees onze exception handling-handleiding om fouten te traceren.

`Appsignal.instrument/2-3`

De functie instrument/2 wordt gebruikt om instrumentatie toe te voegen door een stuk code in een span te wikkelen. Een span wordt uiteindelijk een sample, of een event in een andere span’s sample in AppSignal.

Spans toevoegen aan traces

In het volgende voorbeeld hebben we een Phoenix-controller met een index/2- functie die een trage functie aanroept. De functie slow wordt geïnstrumenteerd met de functie Appsignal.instrument/2 die deze als een afzonderlijk event in deze Phoenix-request registreert. Het verschijnt op AppSignal.com in de event timeline van deze sample om meer inzicht te geven in waar de meeste tijd aan is besteed tijdens de request.

defmodule AppsignalPhoenixExampleWeb.PageController do
  use AppsignalPhoenixExampleWeb, :controller

  def index(conn, _params) do
    slow()
    render(conn, "index.html")
  end

  defp slow do
    Appsignal.instrument("slow", fn ->
      :timer.sleep(1000)
    end)
  end
end

Hier wikkelen we de inhoud van onze functie in een aanroep naar Appsignal.instrument3, en we geven "slow" door als de naam voor het event.

Nieuwe traces starten

In het Phoenix-voorbeeld is er al een AppSignal-trace gestart, dankzij de first-party-ondersteuning voor Phoenix in het AppSignal-pakket. Niet alle frameworks en pakketten worden momenteel direct ondersteund en starten automatisch traces. Hetzelfde geldt voor uw eigen pure Elixir-applicaties. Net als bij het toevoegen van spans aan reeds geïnstrumenteerde traces, wordt er een nieuwe rootspan gemaakt met de functie Appsignal.instrument/2:

defmodule AppsignalElixirExample do
  def example_fn do
    Appsignal.instrument("instrument", fn ->
      :timer.sleep(500)
    end)
  end
end

Dit voorbeeld maakt een sample genaamd “instrument” aan in de “background”-namespace in AppSignal. De naam wordt ook gebruikt als categorienaam voor de hoofdspan. Gebruik instrument/3 om een andere categorienaam te gebruiken:

defmodule AppsignalElixirExample do
  def example_fn do
    Appsignal.instrument("instrument", "call.instrument", fn ->
      :timer.sleep(500)
    end)
  end
end

Wanneer u een functie doorgeeft die een argument neemt, roept de functie instrument/2-3 deze aan met de geopende span om verdere aanpassingen mogelijk te maken. Zie de docs op hex.pm voor alle beschikbare Span-functies.

defmodule AppsignalElixirExample do
  def example_fn do
    Appsignal.instrument("Build complicated SQL query", "prepare_query.sql", fn span ->
      # Example of building a complex SQL query in the instrument block and performing it
      query = "SOME complicate SQL query"
      # The body is only set here because it's the value being calculated and instrumented in this function
      Appsignal.Span.set_sql(span, query)
      Database.perform_query(query)
    end)
  end
end

Exception handling

Om fouten te rapporteren met aangepaste instrumentatie, lees meer in onze exception handling-handleiding.

Function decorators

Met behulp van de decoratormodule Appsignal.Instrumentation.Decorators is het mogelijk om aangepaste instrumentatie aan uw Elixir-applicaties toe te voegen zonder de inhoud van de functies te wijzigen.

Transaction events

In het volgende voorbeeld hebben we een Phoenix-controller met een index/2-functie die een trage functie aanroept. De functie slow wordt geïnstrumenteerd met de AppSignal- transaction_event-decorator die deze als een afzonderlijk event in deze Phoenix- request registreert. Het verschijnt op AppSignal.com in de event timeline van deze transactie- sample om meer inzicht te geven in waar de meeste tijd aan is besteed tijdens de request.

# Phoenix controller example
defmodule PhoenixExample.PageController do
  use PhoenixExample.Web, :controller
  # Include this
  use Appsignal.Instrumentation.Decorators

  def index(conn, _params) do
    slow()
    render conn, "index.html"
  end

  # Decorate this function to add custom instrumentation
  @decorate transaction_event()
  defp slow do
    :timer.sleep(1000)
  end
end

Als u bepaalde events wilt groeperen onder dezelfde event-groep (andere groepen zijn phoenix_controller, phoenix_render, ecto, enz.), kunt u ook een groepsnaam aan de transaction_event-decorator meegeven.

@decorate transaction_event("github_api")
defp get_data_from_github do
  # Third-party API call
end

Dit maakt een event get_data_from_github.github_api aan in de event timeline. Voor meer informatie over hoe eventnamen worden gebruikt, lees onze richtlijnen voor eventnamen.

Transactions

In het Phoenix-voorbeeld is er al een AppSignal-transactie gestart, dankzij de first-party-ondersteuning voor Phoenix in het AppSignal-pakket. Niet alle frameworks en pakketten worden momenteel direct ondersteund en starten automatisch transacties. Hetzelfde geldt voor uw eigen pure Elixir-applicaties. Om transaction_event-decorators te kunnen traceren, moeten we vooraf een AppSignal-transactie starten. We kunnen een transactie starten met de transaction-function decorator.

# Pure Elixir example
defmodule FunctionDecoratorsExample do
  # Include this
  use Appsignal.Instrumentation.Decorators

  # No transaction is started beforehand like in Phoenix, so we need to start
  # it ourselves.
  @decorate transaction()
  def call do
    slow()
    # ...
  end

  # Decorate this function to add custom instrumentation
  @decorate transaction_event()
  defp slow do
    :timer.sleep(1000)
  end
end

Opmerking: Bij het gebruik van pure Elixir-applicaties moet u ervoor zorgen dat de AppSignal- applicatie is gestart voordat u een transactie start. Zie voor meer informatie hoe u AppSignal integreert.

Namespaces

Om onderscheid te kunnen maken tussen HTTP-requests en background jobs, kunnen we een namespace doorgeven aan de transactie zodra we deze starten. De volgende twee namespaces zijn officiële door AppSignal ondersteunde namespaces.

http_request - de standaard - wordt de “web”-namespace genoemd
background_job - maakt de “background”-namespace

defmodule FunctionDecoratorsExample do
  # Include this
  use Appsignal.Instrumentation.Decorators

  # No namespace argument defaults to `:http_request`
  @decorate transaction()
  def web_function do
    # do stuff
  end

  # The "background" namespace
  @decorate transaction(:background_job)
  def background_function do
    # do stuff
  end
end

Voor meer informatie over wat namespaces zijn, zie onze documentatie over namespaces.

Aangepaste namespaces

U kunt ook uw eigen namespaces maken om transacties te traceren in een aparte sectie van uw applicatie, zoals een administratiepaneel. Dit groepeert alle transacties met deze namespace in een aparte sectie op AppSignal.com, zodat trage admin-controllers de gemiddelden van de snelheid van uw applicatie niet beïnvloeden.

@decorate transaction(:admin)
def some_function do
  # do stuff
end

Phoenix-channels

Er is een aangepaste function decorator voor Phoenix-channels. Deze decorator is bedoeld om voor de functie handle_in/3 van een Phoenix.Channel-module geplaatst te worden.

defmodule FunctionDecoratorsExample.MyChannel do
  # Include this
  use Appsignal.Instrumentation.Decorators

  # Add this channel function decorator
  @decorate channel_action()
  def handle_in("ping", _payload, socket) do
    # your code here..
  end
end

Channel-events worden weergegeven onder de “background”-namespace en tonen de channel-module en het action-argument waarop deze wordt gebruikt.

Spans handmatig aanmaken en sluiten

In sommige gevallen kan het handig zijn om spans handmatig te beheren. U kunt de span-API gebruiken om bijvoorbeeld taken te instrumenteren:

def index(conn, _params) do
  current = Appsignal.Tracer.current_span()
  fn ->
    span = "http_request"
    |> Appsignal.Tracer.create_span(current)
    |> Appsignal.Span.set_name("name")
    |> Appsignal.Span.set_attribute("appsignal:category", "category")
    :timer.sleep(1000)
    Appsignal.Tracer.close_span(span)
  end
  |> Task.async()
  |> Task.await()
  render(conn, "index.html")
end

​Appsignal.instrument/2-3

​Spans toevoegen aan traces

​Nieuwe traces starten

​Exception handling

​Function decorators

​Transaction events

​Transactions

​Namespaces

​Aangepaste namespaces

​Phoenix-channels

​Spans handmatig aanmaken en sluiten

`Appsignal.instrument/2-3`

Spans toevoegen aan traces

Nieuwe traces starten

Exception handling

Function decorators

Transaction events

Transactions

Namespaces

Aangepaste namespaces

Phoenix-channels

Spans handmatig aanmaken en sluiten