;
};
**Nur im Collector-Modus:** Dies gilt, wenn AppSignal für Ruby im [Collector-Modus](/ruby/configuration/collector) läuft. Andernfalls hat es keine Auswirkung.
Im [Collector-Modus](/ruby/configuration/collector) baut AppSignal seine Traces aus OpenTelemetry-Spans auf. Eine Transaktion wird zum Root-Span eines Trace. Jedes Event, das Sie instrumentieren, wird darin zu einem Child-Span.
Ihre eigene OpenTelemetry-Instrumentierung teilt sich daher diese Traces. Diese Seite beschreibt, was Ihnen das bringt, und wie Sie einen Span detaillierter beschreiben, als AppSignal es von sich aus tut.
## Einen Span in OpenTelemetry-Begriffen beschreiben
Attribute sind Schlüssel-Wert-Paare an einem Span. Die [semantischen Konventionen](https://opentelemetry.io/docs/specs/semconv/) benennen die Attribute für gängige Arbeit, etwa eine Datenbankabfrage oder einen ausgehenden HTTP-Request. Verwenden Sie diese Namen, wo sie zutreffen, damit andere Tools lesen können, was Sie erfassen.
Fügen Sie dem Span, den AppSignal gerade aufzeichnet, mit `add_opentelemetry_attributes` Attribute hinzu:
```ruby Ruby theme={null}
Appsignal.instrument("query.my_database") do
Appsignal::Transaction.current.add_opentelemetry_attributes(
"db.system.name" => "mysql",
"db.namespace" => "orders"
)
run_the_query
end
```
Die Attribute werden dem innersten Event hinzugefügt, das zu diesem Zeitpunkt offen ist, im Beispiel oben das Event `query.my_database`. Ist kein Event offen, werden sie stattdessen dem eigenen Span der Transaktion hinzugefügt.
Ein Wert muss ein String, ein Integer, ein Float oder ein Boolean sein. Jeder andere Wert wird in einen String umgewandelt.
## Span-Arten und Instrumentierungs-Scopes
### Span-Art
Die Art eines Spans gibt an, welche Rolle die Arbeit im Trace gespielt hat. Ein Span, der einen eingehenden Request bedient hat, ist ein `:server`-Span. Ein Span, der einen anderen Dienst aufgerufen hat, ist ein `:client`-Span. Das Senden und Empfangen einer Nachricht auf einer Queue sind `:producer`- und `:consumer`-Spans. Arbeit, die innerhalb Ihrer Anwendung blieb, ist ein `:internal`-Span.
Der Span eines Events kann jede dieser fünf Arten haben. Er ist `:internal`, sofern Sie keine andere festlegen. Die Ausnahme ist `Appsignal.instrument_sql`, das einen `:client`-Span aufzeichnet, weil eine Abfrage ein ausgehender Aufruf an einen Datenspeicher ist.
Der Span einer Transaktion kann `:server`, `:consumer`, `:producer` oder `:internal` sein. Er ist `:server`, sofern Sie keine andere Art festlegen. Eine Art außerhalb dieser Liste fällt auf `:server` zurück.
```ruby Ruby theme={null}
Appsignal.instrument("request.my_api", :opentelemetry_kind => :client) do
call_the_api
end
```
### Instrumentierungs-Scope
Ein Instrumentierungs-Scope benennt die Bibliothek, für die ein Stück Instrumentierung geschrieben wurde, als Name-Version-Paar. Das ist nicht immer die Bibliothek, durch die die Arbeit lief. Instrumentierung für einen Datenbank-Adapter bezieht sich auf die Datenbankbibliothek, mit der er spricht, nicht auf den Adapter.
AppSignal schlüsselt die Zeit, die Events benötigt haben, und die Allocations, die sie vorgenommen haben, nach Instrumentierungs-Scope auf. Der Scope entscheidet daher, welcher Bibliothek die Kosten eines Spans zugerechnet werden.
Spans werden unter dem Standard-Scope von AppSignal aufgezeichnet, wenn Sie keinen eigenen festlegen. Legen Sie einen eigenen Scope fest, wenn Sie eine Bibliothek in deren Auftrag instrumentieren, damit deren Kosten dieser Bibliothek zugerechnet werden.
```ruby Ruby theme={null}
Appsignal.instrument(
"query.my_database",
:opentelemetry_scope => ["my_database", "2.1.0"]
) do
run_the_query
end
```
### Welche Methoden eine Art oder einen Scope akzeptieren
Übergeben Sie `opentelemetry_kind` und `opentelemetry_scope` an jede Methode, die eine Transaktion startet oder ein Event aufzeichnet:
* `Appsignal.monitor`
* `Appsignal.monitor_and_stop`
* `Appsignal.send_error`
* `Appsignal.report_error`
* `Appsignal.instrument`
* `Appsignal.instrument_sql`
Setzen Sie `opentelemetry_kind` bei `Appsignal.instrument_sql` auf `:internal`, um dessen Standard `:client` zu überschreiben.
## Einen Trace von anderswo fortsetzen
Arbeit kann Ihre Anwendung von einer Stelle aus erreichen, die AppSignal nicht instrumentiert, und dabei einen eigenen OpenTelemetry-Context mitbringen. Dieser Context benennt den Trace, zu dem die Arbeit gehört. Wird er übergeben, lassen sich beide Seiten als ein Trace statt als zwei lesen.
Übergeben Sie den Context als `opentelemetry_context`. Legen Sie mit `opentelemetry_relationship` fest, was der Span der Transaktion damit tun soll:
* `:parent` macht den Span der Transaktion zu einem Child des eingehenden Spans. Die Arbeit setzt denselben Trace fort. Das passiert, wenn Sie einen Context übergeben und sonst nichts angeben.
* `:link` startet einen neuen Trace und zeichnet einen Link zurück zum eingehenden Span auf. Verwenden Sie dies, wenn die Arbeit eine eigenständige Einheit ist statt einer Fortsetzung, was bei einem Hintergrundjob meist der Fall ist.
* `:both` macht den Span zu einem Child und zeichnet zusätzlich den Link auf.
* `:none` ignoriert den eingehenden Context.
```ruby Ruby theme={null}
context = OpenTelemetry.propagation.extract(message.headers)
Appsignal.monitor(
:action => "MessageConsumer#perform",
:namespace => "background_job",
:opentelemetry_kind => :consumer,
:opentelemetry_relationship => :link,
:opentelemetry_context => context
) do
handle(message)
end
```
### Welche Methoden einen Context und eine Relationship akzeptieren
Übergeben Sie `opentelemetry_context` und `opentelemetry_relationship` an jede Methode, die eine Transaktion startet:
* `Appsignal.monitor`
* `Appsignal.monitor_and_stop`
* `Appsignal.send_error`
* `Appsignal.report_error`
`Appsignal.report_error` ist die Ausnahme. Es startet eine Transaktion nur, wenn keine offen ist. Beide Argumente gelten, wenn es eine startet, und werden ignoriert, wenn es den Fehler zu einer bereits offenen Transaktion hinzufügt.
Sie brauchen das nur für Arbeit, die AppSignal nicht instrumentiert. Die unter [distributed tracing](/ruby/distributed-tracing) aufgeführten Bibliotheken sind bereits für Sie verbunden.
## Das OpenTelemetry SDK direkt verwenden
Sie können mit dem OpenTelemetry SDK Spans innerhalb von Code erzeugen, den AppSignal verfolgt. AppSignal macht seinen eigenen Span während der Aufzeichnung aktuell, sodass ein von Ihnen erzeugter Span zu einem Child des AppSignal-Events wird, in dem Sie sich befinden.
```ruby Ruby theme={null}
tracer = OpenTelemetry.tracer_provider.tracer("my-app")
Appsignal.instrument("checkout") do
# This span is recorded as a child of the "checkout" event.
tracer.in_span("charge_card") do |span|
span.set_attribute("payment.provider", "stripe")
charge_the_card
end
end
```
Verwenden Sie `in_span`, statt Spans selbst zu starten und zu beenden. Es macht den Span für die Dauer des Blocks aktuell, beendet ihn danach und tut beides auch dann korrekt, wenn Ihr Code einen Fehler auslöst.
Daten, die Sie über AppSignal melden, werden immer auf einem von AppSignal erzeugten Span aufgezeichnet, nie auf einem von Ihnen erzeugten Span. Ein Fehler, der innerhalb Ihres eigenen Spans an AppSignal gemeldet wird, wird auf dem umgebenden AppSignal-Event aufgezeichnet, oder auf dem Span der Transaktion, wenn kein Event offen ist. Ihre Spans tragen nur das, was Sie selbst auf ihnen erfassen.
## Instrumentierung von Drittanbietern für OpenTelemetry verwenden
Sie können Instrumentierungspakete installieren, die andere Personen geschrieben haben, etwa die, die das OpenTelemetry-Projekt für gängige Bibliotheken veröffentlicht. Installieren und konfigurieren Sie sie so, wie es deren eigene Dokumentation beschreibt. AppSignal benötigt dafür keine Einrichtung, und deren Spans erscheinen neben den eigenen von AppSignal in Ihren Traces.
Das funktioniert, weil diese Pakete ihre Arbeit unter dem jeweils gerade offenen Span aufzeichnen und AppSignal seinen eigenen Span während der Aufzeichnung offen hält. Ihre Spans landen daher innerhalb des Requests oder Jobs, den AppSignal verfolgt, genau dort, wo Sie es erwarten würden.
Andersherum funktioniert es nicht. AppSignal startet eine Transaktion immer als Beginn eines neuen Trace und schaut nicht nach, was OpenTelemetry gerade offen hat. Öffnet ein Paket einen eigenen Span und beginnt darin ein Request oder Job von AppSignal, schließt sich dieser Request nicht dem Trace des Pakets an. Sie erhalten zwei Traces statt eines, ohne Verbindung dazwischen.
Das wirkt sich aus, wenn ein Paket den Einstiegspunkt in Ihre Anwendung instrumentiert, denn AppSignal instrumentiert diese Einstiegspunkte ebenfalls. Instrumentiert ein Paket dagegen Arbeit, die mitten in einem Request stattfindet, den AppSignal bereits verfolgt, was der übliche Fall ist, fügen sich beide zusammen, ohne dass Sie etwas tun müssen.
Wenn Sie tatsächlich einem Trace beitreten müssen, den AppSignal nicht gestartet hat, übergeben Sie dessen Context selbst. Siehe [Einen Trace von anderswo fortsetzen](#einen-trace-von-anderswo-fortsetzen).