Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Migration von Röntgeninstrumenten zur OpenTelemetry Instrumentierung
**Anmerkung**
SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md)
X-Ray stellt auf OpenTelemetry (OTel) als primären Instrumentierungsstandard für Anwendungsverfolgung und Beobachtbarkeit um. Dieser strategische Wandel orientiert sich an den AWS Best Practices der Branche und bietet Kunden eine umfassendere, flexiblere und zukunftsfähigere Lösung für ihre Observability-Anforderungen. OpenTelemetryDie breite Akzeptanz in der Branche ermöglicht die Rückverfolgung von Anfragen über verschiedene Systeme hinweg, auch über Systeme außerhalb, AWS die möglicherweise nicht direkt in X-Ray integriert sind.
Dieses Kapitel enthält Empfehlungen für einen reibungslosen Übergang und betont, wie wichtig die Migration zu OpenTelemetry basierten Lösungen ist, um weiterhin Support und Zugriff auf die neuesten Funktionen in den Bereichen Anwendungsinstrumentierung und Beobachtbarkeit zu gewährleisten.
Es wird empfohlen, die Lösung OpenTelemetry als Observability-Lösung für die Instrumentierung Ihrer Anwendung zu verwenden.
**Topics**
+ [Verstehen OpenTelemetry](#migration-to-opentelemetry)
+ [OpenTelemetry Konzepte für Migration verstehen](#opentelemetry-concepts)
+ [Überblick über die Migration](#migration-overview)
+ [Migration von X-Ray Daemon zu AWS CloudWatch Agent oder Collector OpenTelemetry](#xray-Daemon-migration)
+ [Zu Java migrieren OpenTelemetry](xray-migration-opentelemetry.md)
+ [Zu OpenTelemetry Go migrieren](manual-instrumentation-go.md)
+ [Migrieren Sie zu Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md)
+ [Migrieren Sie zu .NET OpenTelemetry](introduction-dotnet.md)
+ [Zu OpenTelemetry Python migrieren](migrate-xray-to-opentelemetry-python.md)
+ [Migrieren Sie zu Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md)
## Verstehen OpenTelemetry
OpenTelemetry ist ein branchenübliches Observability-Framework, das standardisierte Protokolle und Tools für die Erfassung von Telemetriedaten bereitstellt. Es bietet einen einheitlichen Ansatz für die Instrumentierung, Generierung, Erfassung und den Export von Telemetriedaten wie Metriken, Protokollen und Traces.
Wenn Sie von X-Ray SDKs zu migrieren OpenTelemetry, erhalten Sie die folgenden Vorteile:
+ Verbesserte Unterstützung für Framework- und Bibliotheksinstrumentierung
+ Support für zusätzliche Programmiersprachen
+ Automatische Instrumentierungsfunktionen
+ Flexible Konfigurationsoptionen für die Probenahme
+ Einheitliche Erfassung von Metriken, Protokollen und Traces
Der OpenTelemetry Collector bietet mehr Optionen für Datenerfassungsformate und Exportziele als der X-Ray-Daemon.
### OpenTelemetry Unterstützung in AWS
AWS bietet mehrere Lösungen für die Arbeit mit OpenTelemetry:
+ AWS Distribution für OpenTelemetry
Exportieren Sie OpenTelemetry Spuren als Segmente nach X-Ray.
Weitere Informationen finden Sie unter [AWS Distro for OpenTelemetry](https://aws-otel.github.io/).
+ CloudWatch Signale der Anwendung
Exportieren Sie benutzerdefinierte OpenTelemetry Traces und Metriken, um den Zustand der Anwendung zu überwachen.
Weitere Informationen finden Sie unter [Mit Anwendungssignalen arbeiten](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
+ CloudWatch OTel Endpunkt
Exportieren Sie OpenTelemetry Traces mithilfe des OTel HTTP-Endpunkts mit nativer OpenTelemetry Instrumentierung nach X-Ray.
Weitere Informationen finden Sie unter [ OTel Endpunkte verwenden](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html).
#### Verwenden mit OpenTelemetry AWS CloudWatch
AWS CloudWatch unterstützt OpenTelemetry Traces durch clientseitige Anwendungsinstrumentierung und native AWS CloudWatch Dienste wie Application Signals, Trace, Map, Metrics und Logs. Weitere Informationen finden Sie unter [OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html).
## OpenTelemetry Konzepte für Migration verstehen
In der folgenden Tabelle werden die X-Ray-Konzepte ihren OpenTelemetry Entsprechungen zugeordnet. Wenn Sie diese Mappings verstehen, können Sie Ihre vorhandenen Röntgeninstrumente wie folgt übersetzen: OpenTelemetry
| X-Ray-Konzept | OpenTelemetry Konzept |
| --- | --- |
| Röntgenrekorder | Tracer-Anbieter und Tracer |
| Service-Plugins | Ressourcendetektor |
| Segment | (Server-) Span |
| Untersegment | (Nicht-Server-) Span |
| Regeln für die Röntgenprobenahme | OpenTelemetry Probenahme (anpassbar) |
| Röntgenstrahler | Span Exporter (anpassbar) |
| Anmerkungen/Metadaten | Attribute |
| Instrumentierung der Bibliothek | Instrumentierung der Bibliothek |
| Kontext von X-Ray Trace | Kontext überspannen |
| Übertragung des Kontextes von Röntgenspuren | Weitergabe des W3C-Trace-Kontextes |
| Röntgenspurenprobenahme | OpenTelemetry Spurenprobenahme |
| – | Verarbeitung im Span |
| – | Baggage |
| X-Ray-Daemon | OpenTelemetry Sammler |
**Anmerkung**
Weitere Informationen zu OpenTelemetry Konzepten finden Sie in der [OpenTelemetry Dokumentation](https://opentelemetry.io/docs).
### Funktionen vergleichen
Die folgende Tabelle zeigt, welche Funktionen in beiden Diensten unterstützt werden. Verwenden Sie diese Informationen, um etwaige Lücken zu identifizieren, die Sie während der Migration beheben müssen:
| Feature | Röntgeninstrumentierung | OpenTelemetry Instrumentierung |
| --- | --- | --- |
| Instrumentierung der Bibliothek | Unterstützt | Unterstützt |
| Röntgenprobenentnahme | Unterstützt | Wird in OTel Java/.net/GO unterstützt Wird in ADOT Java/ unterstützt. NET/Python/Node.js |
| Übertragung des Kontextes von Röntgenspuren | Unterstützt | Unterstützt |
| Erkennung von Ressourcen | Unterstützt | Unterstützt |
| Anmerkungen segmentieren | Unterstützt | Unterstützt |
| Metadaten segmentieren | Unterstützt | Unterstützt |
| Automatische Null-Code-Instrumentierung | Wird in Java unterstützt | Wird in OTel Java/ unterstützt. NET/Python/Node.js Wird in ADOT Java/ unterstützt. NET/Python/Node.js |
| Manuelles Verfolgen der Erstellung | Unterstützt | Unterstützt |
### Tracing einrichten und konfigurieren
Um Traces in zu erstellen OpenTelemetry, benötigen Sie einen Tracer. Sie erhalten einen Tracer, indem Sie einen *Tracer-Anbieter in Ihrer Anwendung* initialisieren. Dies ähnelt der Verwendung des X-Recorders zur Konfiguration von X-Ray und zum Erstellen von Segmenten und Untersegmenten in einer Röntgenspur.
**Anmerkung**
Der OpenTelemetry *Tracer Provider* bietet mehr Konfigurationsoptionen als der X-Ray Recorder.
#### Die Struktur von Trace-Daten verstehen
Nachdem Sie sich mit den grundlegenden Konzepten und Feature-Mappings vertraut gemacht haben, können Sie sich mit spezifischen Implementierungsdetails wie der Struktur von Trace-Daten und der Probenahme vertraut machen.
OpenTelemetry verwendet *Spans* anstelle von Segmenten und Untersegmenten zur Strukturierung von Trace-Daten. Jeder Bereich umfasst die folgenden Komponenten:
+ Name
+ Eindeutige ID
+ Start- und Endzeitstempel
+ Spanischer Typ
+ Spanischer Kontext
+ Attribute (Schlüssel-Wert-Metadaten)
+ Ereignisse (Protokolle mit Zeitstempel)
+ Links zu anderen Bereichen
+ Informationen zum Status
+ Referenzen aus dem Elternbereich
Wenn Sie zu migrieren OpenTelemetry, werden Ihre Bereiche automatisch in X-Ray-Segmente oder Untersegmente konvertiert. Dadurch wird sichergestellt, dass Ihr vorhandenes CloudWatch Konsolenerlebnis unverändert bleibt.
##### Mit Span-Attributen arbeiten
Das X-Ray SDK bietet zwei Möglichkeiten, Daten zu Segmenten und Untersegmenten hinzuzufügen:
Anmerkungen
Schlüssel-Wert-Paare, die für Filterung und Suche indexiert werden
Metadaten
Schlüssel-Wert-Paare, die komplexe Daten enthalten, die nicht für die Suche indexiert sind
Standardmäßig werden OpenTelemetry Span-Attribute in X-Rohdaten in Metadaten umgewandelt. Um stattdessen bestimmte Attribute in Anmerkungen umzuwandeln, fügen Sie deren Schlüssel zur `aws.xray.annotations` Attributliste hinzu.
+ [Weitere Informationen zu OpenTelemetry Konzepten finden Sie unter Traces OpenTelemetry ](https://opentelemetry.io/docs/concepts/signals/traces/)
+ Einzelheiten zur Zuordnung von OpenTelemetry Daten zu Röntgendaten finden Sie unter [OpenTelemetry Konvertierung von Röntgendatenmodellen](https://aws-otel.github.io/docs/getting-started/X-Ray#otel-to-X-Ray-data-model-translation-behavior-of-aws-X-Ray-exporter)
### Erkennen von Ressourcen in Ihrer Umgebung
OpenTelemetry verwendet *Resource Detectors*, um Metadaten über die Ressourcen zu sammeln, die Telemetriedaten generieren. Diese Metadaten werden als *Ressourcenattribute* gespeichert. Eine Entität, die Telemetrie produziert, könnte beispielsweise ein Amazon ECS-Cluster oder eine Amazon EC2 EC2-Instance sein, und die Ressourcenattribute, die von diesen Entitäten aufgezeichnet werden können, können den Amazon ECS-Cluster-ARN oder die Amazon EC2 EC2-Instance-ID beinhalten.
+ [Informationen zu den unterstützten Ressourcentypen finden Sie OpenTelemetry unter Semantic Conventions für Ressourcen](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/)
+ Informationen zu X-Ray-Dienst-Plug-ins finden Sie unter [Konfiguration des X-Ray-SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html)
### Verwaltung von Probenahmestrategien
Trace Sampling hilft Ihnen dabei, Ihre Kosten im Griff zu behalten, indem Daten aus einer repräsentativen Teilmenge von Anfragen statt aus allen Anfragen gesammelt werden. OpenTelemetry Sowohl X-Ray als auch X-Ray unterstützen Sampling, implementieren es jedoch unterschiedlich.
**Anmerkung**
Die Probenahme von weniger als 100% der Spuren reduziert Ihre Kosten für die Beobachtbarkeit und bietet gleichzeitig aussagekräftige Einblicke in die Leistung Ihrer Anwendung.
OpenTelemetry bietet mehrere integrierte Sampling-Strategien und ermöglicht es Ihnen, benutzerdefinierte Strategien zu erstellen. Sie können in einigen SDK-Sprachen auch einen X-Ray *Remote Sampler* für die Verwendung von X-Ray Sampling-Regeln konfigurieren. OpenTelemetry
Die zusätzlichen Sampling-Strategien von OpenTelemetry sind:
+ Stichprobenerhebung durch die Eltern — Respektiert die Entscheidung des Elternteils, bevor zusätzliche Stichprobenstrategien angewendet werden
+ Stichprobennahme auf Basis des Spurkennungsverhältnisses — >Stichprobenahme nach dem Zufallsprinzip anhand eines bestimmten Prozentsatzes von Mess
+ Stichprobenentnahme — Wendet Stichprobenregeln auf vollständige Spuren im Collector an OpenTelemetry
+ Benutzerdefinierte Sampler — Implementieren Sie mithilfe der Sampling-Schnittstelle Ihre eigene Sampling-Logik
Informationen zu den Regeln für die Röntgenabtastung finden Sie unter [Sampling-Regeln in der X-Ray-Konsole](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)
Informationen zu OpenTelemetry Tail Sampling finden Sie unter [Tail Sampling Processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor)
### Den Trace-Kontext verwalten
X-Ray SDKs verwaltet den Segmentkontext, um übergeordnete und untergeordnete Beziehungen zwischen Segmenten und Untersegmenten in einer Spur korrekt zu behandeln. OpenTelemetry verwendet einen ähnlichen Mechanismus, um sicherzustellen, dass Bereiche den richtigen übergeordneten Bereich haben. Es speichert und verbreitet Ablaufverfolgungsdaten im gesamten Anforderungskontext. Wenn Ihre Anwendung beispielsweise eine Anfrage verarbeitet und einen Server-Span erstellt, der diese Anforderung repräsentiert, OpenTelemetry wird der Server-Span im OpenTelemetry Kontext gespeichert, sodass bei der Erstellung eines untergeordneten Bereichs dieser untergeordnete Bereich den Span im Kontext als übergeordnetes Element referenzieren kann.
### Der Trace-Kontext wird weitergegeben
Sowohl X-Ray als auch HTTP-Header OpenTelemetry verwenden, um den Trace-Kontext dienstübergreifend zu verbreiten. Auf diese Weise können Sie Trace-Daten, die von verschiedenen Diensten generiert wurden, miteinander verknüpfen und Stichprobenentscheidungen treffen.
Das X-Ray SDK verbreitet automatisch den Trace-Kontext mithilfe des X-Ray-Trace-Headers. Wenn ein Dienst einen anderen aufruft, enthält der Trace-Header den Kontext, der benötigt wird, um die Beziehungen zwischen übergeordneten und untergeordneten Traces aufrechtzuerhalten.
OpenTelemetry unterstützt mehrere Trace-Header-Formate für die Kontextweiterleitung, darunter:
+ W3C Trace Context (Standard)
+ Röntgen-Trace-Header
+ Andere benutzerdefinierte Formate
**Anmerkung**
Sie können OpenTelemetry die Verwendung eines oder mehrerer Header-Formate konfigurieren. Verwenden Sie beispielsweise den X-Ray Propagator, um Trace-Kontext an AWS Dienste zu senden, die X-Ray Tracing unterstützen.
Konfigurieren und verwenden Sie den X-Ray Propagator, um die dienstübergreifende AWS Ablaufverfolgung zu ermöglichen. Auf diese Weise können Sie den Trace-Kontext an API-Gateway-Endpunkte und andere Dienste weitergeben, die X-Ray unterstützen.
+ Informationen zu X-Ray-Trace-Headern finden Sie unter [Tracing-Header](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) im X-Ray Developer Guide
+ Informationen zur OpenTelemetry Kontextweiterleitung finden Sie in der Dokumentation unter [Kontext und Kontextweiterleitung](https://opentelemetry.io/docs/concepts/context-propagation/) OpenTelemetry
### Verwendung von Bibliotheksinstrumentierung
Sowohl X-Ray als auch OpenTelemetry bieten Bibliotheksinstrumente, die nur minimale Codeänderungen erfordern, um Ihren Anwendungen Tracing hinzuzufügen.
X-Ray bietet Funktionen zur Bibliotheksinstrumentierung. Auf diese Weise können Sie vorgefertigte X-Ray-Instrumente mit minimalen Änderungen am Anwendungscode hinzufügen. Diese Instrumentierungen unterstützen spezifische Bibliotheken wie das AWS SDK und die HTTP-Clients sowie Web-Frameworks wie Spring Boot oder Express.js.
OpenTelemetryDie Instrumentierungsbibliotheken generieren durch Bibliotheks-Hooks oder automatische Codeänderungen detaillierte Bereiche für Ihre Bibliotheken, sodass nur minimale Codeänderungen erforderlich sind.
[Um festzustellen, ob OpenTelemetry's Library Instrumentations Ihre Bibliothek unterstützt, suchen Sie in der OpenTelemetry Registry unter OpenTelemetry Registry danach.](https://opentelemetry.io/ecosystem/registry/)
### Spuren exportieren
X-Ray und OpenTelemetry verwenden Sie verschiedene Methoden, um Trace-Daten zu exportieren.
#### Export von Röntgenspuren
Das X-Ray SDKs verwendet einen Sender, um Trace-Daten zu senden:
+ Sendet Segmente und Untersegmente an den X-Ray Daemon
+ Verwendet UDP für nicht blockierende I/O
+ Standardmäßig im SDK konfiguriert
#### OpenTelemetry Trace-Export
OpenTelemetry verwendet konfigurierbare *Span Exporter* zum Senden von Trace-Daten:
+ *Verwendet die Protokolle *http/protobuf oder grpc**
+ Exportiert Spans zu Endpunkten, die vom Collector oder Agent überwacht werden OpenTelemetry CloudWatch
+ Ermöglicht benutzerdefinierte Exportkonfigurationen
### Bearbeitung und Weiterleitung von Spuren
Sowohl X-Ray als auch OpenTelemetry bieten Komponenten zum Empfangen, Verarbeiten und Weiterleiten von Trace-Daten.
#### Verarbeitung von Röntgenspuren
Der X-Ray-Daemon kümmert sich um die Trace-Verarbeitung:
+ Hört auf UDP-Verkehr von X-Ray SDKs
+ Stapelt Segmente und Untersegmente
+ Lädt Stapel in den X-Ray-Dienst hoch
#### OpenTelemetry Verarbeitung von Rückverfolgungen
Der OpenTelemetry Collector kümmert sich um die Trace-Verarbeitung:
+ Empfängt Traces von instrumentierten Diensten
+ Verarbeitet und ändert optional Trace-Daten
+ Sendet verarbeitete Traces an verschiedene Backends, einschließlich X-Ray
**Anmerkung**
Der AWS CloudWatch Agent kann auch OpenTelemetry Spuren empfangen und an X-Ray senden. Weitere Informationen finden Sie unter [Metriken und Traces sammeln mit OpenTelemetry](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html).
### Span Processing (OpenTelemetry-spezifisches Konzept)
OpenTelemetry verwendet Span-Prozessoren, um Spans bei ihrer Erstellung zu ändern:
+ Ermöglicht das Lesen und Ändern von Spans bei der Erstellung oder Fertigstellung
+ Aktiviert benutzerdefinierte Logik für die Verarbeitung von Spannen
### Gepäck (OpenTelemetry-spezifisches Konzept)
OpenTelemetryDie Gepäckfunktion ermöglicht die Weitergabe von Schlüsselwertdaten:
+ Ermöglicht die Übergabe beliebiger Daten zusammen mit dem Trace-Kontext
+ Nützlich für die Weitergabe anwendungsspezifischer Informationen über Dienstgrenzen hinweg
[Informationen zum Collector finden Sie unter OpenTelemetry Collector OpenTelemetry ](https://opentelemetry.io/docs/collector/)
Informationen zu X-Ray-Konzepten finden Sie unter [X-Ray-Konzepte](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html) im X-Ray-Entwicklerhandbuch
## Überblick über die Migration
Dieser Abschnitt bietet einen Überblick über die Codeänderungen, die für die Migration erforderlich sind. Die folgende Liste enthält sprachspezifische Anleitungen und Schritte zur Migration von X-Ray Daemon.
**Wichtig**
Für eine vollständige Migration von Röntgeninstrumenten zur OpenTelemetry Instrumentierung müssen Sie:
Ersetzen Sie die Verwendung des X-Ray-SDK durch eine OpenTelemetry Lösung
Ersetzen Sie den X-Ray-Daemon durch den CloudWatch Agenten oder OpenTelemetry Collector (mit X-Ray Exporter)
+ [Zu Java migrieren OpenTelemetry](xray-migration-opentelemetry.md)
+ [Zu OpenTelemetry Go migrieren](manual-instrumentation-go.md)
+ [Migrieren Sie zu Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md)
+ [Migrieren Sie zu .NET OpenTelemetry](introduction-dotnet.md)
+ [Zu OpenTelemetry Python migrieren](migrate-xray-to-opentelemetry-python.md)
+ [Migrieren Sie zu Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md)
### Empfehlungen für neue und bestehende Anwendungen
Für neue und bestehende Anwendungen wird empfohlen, die folgenden Lösungen zu verwenden, um die Ablaufverfolgung in Ihren Anwendungen zu aktivieren:
Instrumentierung
+ OpenTelemetry SDKs
+ AWS Distribution für Instrumentierung OpenTelemetry
Datenerfassung
+ OpenTelemetry Sammler
+ CloudWatch Agentin
Nach der Migration zu OpenTelemetry basierten Lösungen bleibt Ihre CloudWatch Erfahrung unverändert. Sie können Ihre Traces weiterhin im gleichen Format auf den Seiten Traces und Trace Map der CloudWatch Konsole anzeigen oder Ihre Trace-Daten über [X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-api.html) abrufen APIs.
### Änderungen am Setup nachverfolgen
Sie müssen das X-Ray-Setup durch ein OpenTelemetry Setup ersetzen.
**Vergleich von X-Ray und OpenTelemetry Setup**
| Feature | X-Ray SDK | OpenTelemetry |
| --- | --- | --- |
| Standardkonfigurationen | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/xray-sdk-migration.html) |
| Manuelle Konfigurationen | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/xray-sdk-migration.html) |
### Änderungen der Instrumentierung der Bibliothek
Aktualisieren Sie Ihren Code so, dass er OpenTelemetry Library Instrumentation anstelle von X-Ray Library Instrumentation für AWS SDK, HTTP-Clients, Web Frameworks und andere Bibliotheken verwendet. Dadurch werden OpenTelemetry Traces statt X-Ray Traces generiert.
**Anmerkung**
Codeänderungen variieren je nach Sprache und Bibliothek. Ausführliche Anweisungen finden Sie in den sprachspezifischen Migrationsleitfäden.
### Änderungen an der Instrumentierung der Lambda-Umgebung
Um sie OpenTelemetry in Ihren Lambda-Funktionen zu verwenden, wählen Sie eine der folgenden Einrichtungsoptionen:
1. Verwenden Sie einen Lambda-Layer mit automatischer Instrumentierung:
+ (Empfohlen) [AWS Lambda Layer](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html) für OpenTelemetry
**Anmerkung**
Um nur die Ablaufverfolgung zu verwenden, legen Sie die Lambda-Umgebungsvariable fest. `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`
+ [AWS verwalteter Lambda-Layer für ADOT](https://aws-otel.github.io/docs/getting-started/lambda)
1. Manuell OpenTelemetry für Ihre Lambda-Funktion einrichten:
+ Konfiguration eines einfachen Span-Prozessors mit einem X-Ray-UDP-Span-Exporter
+ Richten Sie einen X-Ray Lambda Propagator ein
### Manuelles Erstellen von Trace-Daten
Ersetzen Sie Röntgensegmente und Untersegmente durch OpenTelemetry Spans:
+ Verwenden Sie einen OpenTelemetry Tracer, um Spans zu erstellen
+ Hinzufügen von Attributen zu Spans (entspricht X-Ray-Metadaten und Anmerkungen)
**Wichtig**
Wenn es an X-Ray gesendet wird:
Serverbereiche werden in X-Ray-Segmente umgewandelt
Andere Bereiche werden in X-Ray-Untersegmente umgewandelt
Attribute werden standardmäßig in Metadaten konvertiert
Um ein Attribut in eine Anmerkung zu konvertieren, fügen Sie seinen Schlüssel zur `aws.xray.annotations` Attributliste hinzu. Weitere Informationen finden Sie unter [Benutzerdefinierte X-Ray-Anmerkungen aktivieren](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations).
## Migration von X-Ray Daemon zu AWS CloudWatch Agent oder Collector OpenTelemetry
Sie können entweder den CloudWatch Agenten oder den OpenTelemetry Collector verwenden, um Traces von Ihren instrumentierten Anwendungen zu empfangen und an X-Ray zu senden.
**Anmerkung**
Die CloudWatch Agentenversion 1.300025.0 und höher kann Traces sammeln. OpenTelemetry Wenn Sie den CloudWatch Agenten anstelle des X-Ray-Daemons verwenden, reduzieren Sie die Anzahl der Agenten, die Sie verwalten müssen. Weitere Informationen finden Sie unter [Erfassung von Metriken, Protokollen und Traces mit dem CloudWatch Agenten](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html).
**Topics**
+ [Migration auf Amazon EC2- oder lokalen Servern](#ec2-onprem-migration)
+ [Migration auf Amazon ECS](#ecs-migration)
+ [Migration auf Elastic Beanstalk](#beanstalk-migration)
### Migration auf Amazon EC2- oder lokalen Servern
**Wichtig**
Stoppen Sie den X-Ray-Daemon-Prozess, bevor Sie den CloudWatch Agenten oder OpenTelemetry Collector verwenden, um Portkonflikte zu vermeiden.
#### Bestehendes X-Ray-Daemon-Setup
##### Den Daemon installieren
Ihre bestehende X-Ray-Daemon-Nutzung wurde mit einer der folgenden Methoden installiert:
Manuelle Installation
Laden Sie die ausführbare Datei vom X-Ray-Daemon Amazon S3 S3-Bucket herunter und führen Sie sie aus.
Automatische Installation
Verwenden Sie dieses Skript, um den Daemon zu installieren, wenn Sie eine Instanz starten:
```
#!/bin/bash
curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \
-o /home/ec2-user/xray.rpm
yum install -y /home/ec2-user/xray.rpm
```
##### Konfigurieren des -Daemons
Ihre bestehende X-Ray-Daemon-Nutzung wurde wie folgt konfiguriert:
+ Befehlszeilenargumente
+ Konfigurationsdatei (`xray-daemon.yaml`)
**Example Verwendung einer Konfigurationsdatei**
```
./xray -c ~/xray-daemon.yaml
```
##### Ausführen des Daemons
Ihre bestehende X-Ray-Daemon-Nutzung wurde mit dem folgenden Befehl gestartet:
```
~/xray-daemon$ ./xray -o -n us-east-1
```
##### Den Daemon entfernen
Um den X-Ray Daemon von Ihrer Amazon EC2 EC2-Instance zu entfernen:
1. Beenden Sie den Daemon-Dienst:
```
systemctl stop xray
```
1. Löschen Sie die Konfigurationsdatei:
```
rm ~/path/to/xray-daemon.yaml
```
1. Falls konfiguriert, entfernen Sie die Protokolldatei:
**Anmerkung**
Der Speicherort der Protokolldatei hängt von Ihrer Konfiguration ab:
Konfiguration über die Befehlszeile: `/var/log/xray-daemon.log`
Konfigurationsdatei: Überprüfen Sie die `LogPath` Einstellung
#### Den CloudWatch Agenten einrichten
##### Den Agenten installieren
Anweisungen zur Installation finden Sie unter [Installation des CloudWatch Agenten auf einem lokalen Server](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_user-first).
##### Den Agenten konfigurieren
1. Erstellen Sie eine Konfigurationsdatei, um die Trace-Erfassung zu aktivieren. Weitere Informationen finden Sie unter [ CloudWatch Agent-Konfigurationsdatei erstellen](AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html).
1. Richten Sie IAM-Berechtigungen ein:
+ Fügen Sie eine IAM-Rolle hinzu oder geben Sie Anmeldeinformationen für den Agenten an. Weitere Informationen finden Sie unter [IAM-Rollen einrichten](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_permissions-first).
+ Stellen Sie sicher, dass die Rolle oder die Anmeldeinformationen die `xray:PutTraceSegments` Berechtigung enthalten.
##### Starten des -Agenten
Anweisungen zum Starten des Agenten finden Sie unter [Den CloudWatch Agenten über die Befehlszeile](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#start-CloudWatch-Agent-EC2-commands-fleet) starten.
#### Den OpenTelemetry Collector einrichten
##### Den Collector installieren
Laden Sie den OpenTelemetry Collector für Ihr Betriebssystem herunter und installieren Sie ihn. Anweisungen finden Sie unter [Installation des Collectors](https://opentelemetry.io/docs/collector/installation/).
##### Den Collector konfigurieren
Konfigurieren Sie die folgenden Komponenten in Ihrem Collector:
+ aws-proxy-Erweiterung
Für Röntgenprobenentnahmen erforderlich
+ OTel Empfänger
Sammelt Spuren aus Ihrer Anwendung
+ Xray-Exporter
Sendet Spuren an X-Ray
**Example Beispiel für die Collector-Konfiguration — otel-collector-config .yaml**
```
extensions:
awsproxy:
endpoint: 127.0.0.1:2000
health_check:
receivers:
otlp:
protocols:
grpc:
endpoint: 127.0.0.1:4317
http:
endpoint: 127.0.0.1:4318
processors:
batch:
exporters:
awsxray:
region: 'us-east-1'
service:
pipelines:
traces:
receivers: [otlp]
exporters: [awsxray]
extensions: [awsproxy, health_check]
```
**Wichtig**
Konfigurieren Sie die AWS Anmeldeinformationen mit der entsprechenden Genehmigung`xray:PutTraceSegments`. Weitere Informationen finden Sie unter [Anmeldeinformationen angeben](sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).
##### Den Collector starten
Führen Sie den Collector mit Ihrer Konfigurationsdatei aus:
```
otelcol --config=otel-collector-config.yaml
```
### Migration auf Amazon ECS
**Wichtig**
Ihre Aufgabenrolle muss über die entsprechenden `xray:PutTraceSegments` Berechtigungen für jeden Collector verfügen, den Sie verwenden.
Stoppen Sie alle vorhandenen X-Ray-Daemon-Container, bevor Sie den CloudWatch Agenten- oder OpenTelemetry Collector-Container auf demselben Host ausführen, um Portkonflikte zu vermeiden.
#### Den Agenten verwenden CloudWatch
1. Holen Sie sich das Docker-Image aus der [Amazon ECR Public Gallery](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent).
1. Erstellen Sie eine Konfigurationsdatei mit dem Namen: `cw-agent-otel.json`
```
{
"traces": {
"traces_collected": {
"xray": {
"tcp_proxy": {
"bind_address": "0.0.0.0:2000"
}
},
"otlp": {
"grpc_endpoint": "0.0.0.0:4317",
"http_endpoint": "0.0.0.0:4318"
}
}
}
}
```
1. Speichern Sie die Konfiguration im Systems Manager Parameter Store:
1. Öffnen Sie [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)
1. Wählen Sie **Parameter erstellen**
1. Geben Sie die folgenden Werte ein:
+ Name: `/ecs/cwagent/otel-config`
+ Stufe: Standard
+ Typ: Zeichenfolge
+ Datentyp: Text
+ Wert: [Fügen Sie die cw-agent-otel .json-Konfiguration hier ein]
1. Erstellen Sie eine Aufgabendefinition im Bridge-Netzwerkmodus:
In Ihrer Aufgabendefinition hängt die Konfiguration von dem Netzwerkmodus ab, den Sie tatsächlich nutzen. Brückennetzwerke sind die Standardeinstellung und können in Ihrer Standard-VPC verwendet werden. Stellen Sie in einem Bridge-Netzwerk die `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` Umgebungsvariable so ein, dass dem OpenTelemetry SDK der Endpunkt und der Port für den CloudWatch Agenten mitgeteilt werden. Sie sollten auch einen Link von Ihrem Anwendungscontainer zum Collector-Container erstellen, damit Traces vom OpenTelemetry SDK in Ihrer Anwendung an den Collector-Container gesendet werden können.
**Example CloudWatch Definition der Agentenaufgabe**
```
{
"containerDefinitions": [
{
"name": "cwagent",
"image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
"portMappings": [
{
"containerPort": 4318,
"hostPort": 4318,
"protocol": "tcp"
},
{
"containerPort": 4317,
"hostPort": 4317,
"protocol": "tcp"
},
{
"containerPort": 2000,
"hostPort": 2000,
"protocol": "tcp"
}
],
"secrets": [
{
"name": "CW_CONFIG_CONTENT",
"valueFrom": "/ecs/cwagent/otel-config"
}
]
},
{
"name": "application",
"image": "APPLICATION_IMAGE",
"links": ["cwagent"],
"environment": [
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://cwagent:4318/v1/traces"
}
]
}
]
}
```
Weitere Informationen finden Sie unter [Bereitstellen des CloudWatch Agenten zur Erfassung von Amazon EC2-Metriken auf Instanzebene auf](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html) Amazon ECS.
#### Den Collector verwenden OpenTelemetry
1. Holen Sie sich das Docker-Image `otel/opentelemetry-collector-contrib` von [Docker Hub](https://hub.docker.com/r/otel/opentelemetry-collector-contrib).
1. Erstellen Sie eine Konfigurationsdatei, die `otel-collector-config.yaml` denselben Inhalt wie im Abschnitt **Amazon EC2 EC2-Konfiguration des Collectors** verwendet, aber aktualisieren Sie die Endpoints, die `0.0.0.0` anstelle von verwendet werden sollen. `127.0.0.1`
1. Um diese Konfiguration in Amazon ECS zu verwenden, können Sie die Konfiguration im Systems Manager Parameter Store speichern. Rufen Sie zunächst die Systems Manager Parameter Store-Konsole auf und wählen Sie **Neuen Parameter erstellen** aus. Erstellen Sie einen neuen Parameter mit den folgenden Informationen:
+ Name:/ecs/otel/config(auf diesen Namen wird in der Aufgabendefinition für den Collector verwiesen)
+ Stufe: Standard
+ Typ: Zeichenfolge
+ Datentyp: Text
+ Wert: [Fügen Sie die otel-collector-config .yaml-Konfiguration hier ein]
1. Erstellen Sie eine Aufgabendefinition für die Bereitstellung des OpenTelemetry Collectors, indem Sie als Beispiel den Bridge-Netzwerkmodus verwenden.
In der Aufgabendefinition hängt die Konfiguration vom verwendeten Netzwerkmodus ab. Brückennetzwerke sind die Standardeinstellung und können in Ihrer Standard-VPC verwendet werden. Stellen Sie in einem Bridge-Netzwerk die `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` Umgebungsvariable so ein, dass dem OpenTelemetry SDK der Endpunkt und der Port für den OpenTelemetry Collector mitgeteilt werden. Sie sollten auch einen Link von Ihrem Anwendungscontainer zum Collector-Container erstellen, damit Traces vom OpenTelemetry SDK in Ihrer Anwendung an den Collector-Container gesendet werden können.
**Example OpenTelemetry Definition der Collector-Aufgabe**
```
{
"containerDefinitions": [
{
"name": "otel-collector",
"image": "otel/opentelemetry-collector-contrib",
"portMappings": [
{
"containerPort": 2000,
"hostPort": 2000
},
{
"containerPort": 4317,
"hostPort": 4317
},
{
"containerPort": 4318,
"hostPort": 4318
}
],
"command": [
"--config",
"env:SSM_CONFIG"
],
"secrets": [
{
"name": "SSM_CONFIG",
"valueFrom": "/ecs/otel/config"
}
]
},
{
"name": "application",
"image": "APPLICATION_IMAGE",
"links": ["otel-collector"],
"environment": [
{
"name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
"value": "http://otel-collector:4318/v1/traces"
}
]
}
]
}
```
### Migration auf Elastic Beanstalk
**Wichtig**
Stoppen Sie den X-Ray-Daemon-Prozess, bevor Sie den CloudWatch Agenten verwenden, um Portkonflikte zu vermeiden.
Ihre bestehende X-Ray Daemon-Integration wurde mithilfe der Elastic Beanstalk Beanstalk-Konsole oder durch die Konfiguration von X-Ray Daemon in Ihrem Anwendungsquellcode mit einer Konfigurationsdatei aktiviert.
#### Den Agenten verwenden CloudWatch
Konfigurieren Sie den CloudWatch Agenten auf der Amazon Linux 2-Plattform mithilfe einer `.ebextensions` Konfigurationsdatei:
1. Erstellen Sie ein Verzeichnis mit dem Namen `.ebextensions` in Ihrem Projektstamm
1. Erstellen Sie eine `cloudwatch.config` innerhalb des `.ebextensions` Verzeichnisses benannte Datei mit dem folgenden Inhalt:
```
files:
"/opt/aws/amazon-cloudwatch-agent/etc/config.json":
mode: "0644"
owner: root
group: root
content: |
{
"traces": {
"traces_collected": {
"otlp": {
"grpc_endpoint": "12.0.0.1:4317",
"http_endpoint": "12.0.0.1:4318"
}
}
}
}
container_commands:
start_agent:
command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s
```
1. Nehmen Sie das `.ebextensions` Verzeichnis bei der Bereitstellung in Ihr Anwendungsquellpaket auf
Weitere Informationen zu Elastic Beanstalk Beanstalk-Konfigurationsdateien finden Sie unter [Erweiterte Umgebungsanpassung mit Konfigurationsdateien](elasticbeanstalk/latest/dg/ebextensions.html).
# Zu Java migrieren OpenTelemetry
Dieser Abschnitt enthält Anleitungen zur Migration vom X-Ray SDK zum OpenTelemetry SDK for Java Java-Anwendungen.
**Topics**
+ [Automatische Instrumentierungslösung ohne Code](#xray-migration-zero-code)
+ [Lösungen für die manuelle Instrumentierung mit dem SDK](#xray-migration-sdk)
+ [Nachverfolgung eingehender Anfragen (Spring Framework-Instrumentierung)](#xray-migration-tracing-setup-otel)
+ [AWS SDK v2-Instrumentierung](#xray-migration-sdkv2)
+ [Instrumentieren von ausgehenden HTTP-Aufrufen](#xray-migration-http)
+ [Instrumentierungsunterstützung für andere Bibliotheken](#xray-migration-libraries)
+ [Manuelles Erstellen von Trace-Daten](#xray-migration-tracedata)
+ [Lambda-Instrumentierung](#xray-migration-lambda)
## Automatische Instrumentierungslösung ohne Code
------
#### [ With X-Ray Java agent ]
Um den X-Ray-Java-Agenten zu aktivieren, mussten die JVM-Argumente Ihrer Anwendung geändert werden.
```
-javaagent:/path-to-disco/disco-java-agent.jar=pluginPath=/path-to-disco/disco-plugins
```
------
#### [ With OpenTelemetry-based Java agent ]
Um OpenTelemetry basierte Java-Agenten zu verwenden.
+ Verwenden Sie den Java-Agenten AWS Distro for OpenTelemetry (ADOT) Auto-Instrumentation für die automatische Instrumentierung mit dem ADOT-Java-Agenten. Weitere Informationen finden Sie unter [Automatische Instrumentierung für Traces und Metriken](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr) mit dem Java-Agenten. Wenn Sie nur die Ablaufverfolgung verwenden möchten, deaktivieren Sie die `OTEL_METRICS_EXPORTER=none ` Umgebungsvariable, um Metriken aus dem Java-Agenten zu exportieren.
(Optional) Sie können CloudWatch Application Signals auch aktivieren, wenn Sie Ihre Anwendungen AWS mit der automatischen ADOT-Java-Instrumentierung automatisch instrumentieren, um den aktuellen Zustand der Anwendung zu überwachen und die langfristige Anwendungsleistung zu verfolgen. Application Signals bietet eine einheitliche, anwendungsorientierte Ansicht Ihrer Anwendungen, Dienste und Abhängigkeiten und hilft bei der Überwachung und Bewertung des Anwendungszustands. Weitere Informationen finden Sie unter [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
+ Verwenden Sie den OpenTelemetry Java-Agenten für die automatische Instrumentierung. Weitere Informationen finden Sie unter [Zero-Code-Instrumentierung mit dem Java-Agenten](https://opentelemetry.io/docs/zero-code/java/agent/).
------
## Lösungen für die manuelle Instrumentierung mit dem SDK
------
#### [ Tracing setup with X-Ray SDK ]
Um Ihren Code mit dem X-Ray SDK for Java zu instrumentieren, musste die `AWSXRay` Klasse zunächst mit Service-Plug-ins und lokalen Sampling-Regeln konfiguriert werden. Anschließend wurde ein mitgelieferter Rekorder verwendet.
```
static { AWS XRayRecorderBuilder builder = AWS XRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ECSPlugin()); AWS XRay.setGlobalRecorder(builder.build());
}
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
Die folgenden Abhängigkeiten sind erforderlich.
```
io.opentelemetry
opentelemetry-bom
1.49.0
pom
import
io.opentelemetry.instrumentation
opentelemetry-instrumentation-bom
2.15.0
pom
import
io.opentelemetry
opentelemetry-sdk
io.opentelemetry
opentelemetry-api
io.opentelemetry.semconv
opentelemetry-semconv
io.opentelemetry
opentelemetry-exporter-otlp
io.opentelemetry.contrib
opentelemetry-aws-xray
1.46.0
io.opentelemetry.contrib
opentelemetry-aws-xray-propagator
1.46.0-alpha
io.opentelemetry.contrib
opentelemetry-aws-resources
1.46.0-alpha
```
Konfigurieren Sie das OpenTelemetry SDK, indem Sie ein Objekt instanziieren `TracerProvider` und global registrieren. `OpenTelemetrySdk` Konfigurieren Sie diese Komponenten:
+ Ein OTLP Span Exporter (z. B. OtlpGrpcSpanExporter) — Erforderlich für den Export von Traces an den CloudWatch Agenten oder Collector OpenTelemetry
+ Ein AWS X-Ray Propagator — Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind
+ Ein AWS X-Ray Remote Sampler — Erforderlich, wenn Sie Anfragen anhand von Röntgenprobenregeln abtasten müssen
+ Resource Detectors (zum Beispiel EcsResource oder Ec2Resource) — Erkennt Metadaten des Hosts, auf dem Ihre Anwendung ausgeführt wird
```
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.contrib.aws.resource.Ec2Resource;
import io.opentelemetry.contrib.aws.resource.EcsResource;
import io.opentelemetry.contrib.awsxray.AwsXrayRemoteSampler;
import io.opentelemetry.contrib.awsxray.propagator.AwsXrayPropagator;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import static io.opentelemetry.semconv.ServiceAttributes.SERVICE_NAME;
// ...
private static final Resource otelResource =
Resource.create(Attributes.of(SERVICE_NAME, "YOUR_SERVICE_NAME"))
.merge(EcsResource.get())
.merge(Ec2Resource.get());
private static final SdkTracerProvider sdkTracerProvider =
SdkTracerProvider.builder()
.addSpanProcessor(BatchSpanProcessor.create(
OtlpGrpcSpanExporter.getDefault()
))
.addResource(otelResource)
.setSampler(Sampler.parentBased(
AwsXrayRemoteSampler.newBuilder(otelResource).build()
))
.build();
// Globally registering a TracerProvider makes it available throughout the application to create as many Tracers as needed.
private static final OpenTelemetrySdk openTelemetry =
OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(AwsXrayPropagator.getInstance()))
.buildAndRegisterGlobal();
```
------
## Nachverfolgung eingehender Anfragen (Spring Framework-Instrumentierung)
------
#### [ With X-Ray SDK ]
Informationen zur Verwendung des X-Ray-SDK mit dem Spring-Framework zur Instrumentierung Ihrer Anwendung finden Sie unter [AOP mit Spring und dem X-Ray-SDK SDK for Java](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html). Gehen Sie wie folgt vor, um AOP in Spring zu aktivieren.
1. [Konfigurieren von Spring](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-spring-configuration)
1. [Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-filters-spring)
1. [Kommentieren Sie Ihren Code oder implementieren Sie eine Schnittstelle](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-annotate-or-implement)
1. [Aktivieren von X-Ray in Ihrer Anwendung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-activate-xray)
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry bietet Instrumentierungsbibliotheken zum Sammeln von Traces für eingehende Anfragen für Spring Boot-Anwendungen. Um die Spring Boot-Instrumentierung mit minimaler Konfiguration zu aktivieren, schließen Sie die folgende Abhängigkeit ein.
```
io.opentelemetry.instrumentation
opentelemetry-spring-boot-starter
```
Weitere Informationen zur Aktivierung und Konfiguration der Spring Boot-Instrumentation für Ihr OpenTelemetry Setup finden Sie unter OpenTelemetry [Erste Schritte](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/getting-started/).
------
#### [ Using OpenTelemetry-based Java agents ]
Die empfohlene Standardmethode für die Instrumentierung von Spring Boot-Anwendungen ist die Verwendung des [OpenTelemetry Java-Agenten](https://opentelemetry.io/docs/zero-code/java/agent/) mit *Bytecode-Instrumentierung*, der im Vergleich zur direkten Verwendung des SDK auch mehr out-of-the-box Instrumentierungen und Konfigurationen bietet. Informationen zu den ersten Schritten finden Sie unter. [Automatische Instrumentierungslösung ohne Code](#xray-migration-zero-code)
------
## AWS SDK v2-Instrumentierung
------
#### [ With X-Ray SDK ]
Das X-Ray SDK for Java kann automatisch alle AWS SDK v2-Clients instrumentieren, wenn Sie das `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` Untermodul zu Ihrem Build hinzugefügt haben.
Um die Downstream-Client-Aufrufe einzelner Clients an AWS Dienste mit AWS SDK for Java 2.2 und höher zu instrumentieren, wurde das `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor ` Modul aus Ihrer Build-Konfiguration ausgeschlossen und das `aws-xray-recorder-sdk-aws-sdk-v2` Modul wurde aufgenommen. Einzelne Clients wurden instrumentiert, indem sie mit einem `TracingInterceptor` konfiguriert wurden.
```
import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...
public class MyModel {
private DynamoDbClient client = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(new TracingInterceptor())
.build()
)
.build();
//...
```
------
#### [ With OpenTelemetry SDK ]
Um alle AWS SDK-Clients automatisch zu instrumentieren, fügen Sie das `opentelemetry-aws-sdk-2.2-autoconfigure` Untermodul hinzu.
```
io.opentelemetry.instrumentation
opentelemetry-aws-sdk-2.2-autoconfigure
2.15.0-alpha
runtime
```
Um einzelne AWS SDK-Clients zu instrumentieren, fügen Sie das `opentelemetry-aws-sdk-2.2` Untermodul hinzu.
```
io.opentelemetry.instrumentation
opentelemetry-aws-sdk-2.2
2.15.0-alpha
compile
```
Registrieren Sie dann einen Interceptor, wenn Sie einen AWS SDK-Client erstellen.
```
import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;
// ...
AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
private final S3Client S3_CLIENT = S3Client.builder()
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(telemetry.newExecutionInterceptor())
.build())
.build();
```
------
## Instrumentieren von ausgehenden HTTP-Aufrufen
------
#### [ With X-Ray SDK ]
Um ausgehende HTTP-Anfragen mit X-Ray zu instrumentieren, HttpClient war das X-Ray SDK für Javas Version des Apache erforderlich.
```
import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
...
public String randomName() throws IOException {
CloseableHttpClient httpclient = HttpClientBuilder.create().build();
```
------
#### [ With OpenTelemetry SDK ]
Ähnlich wie das X-Ray Java SDK OpenTelemetry stellt es eine `ApacheHttpClientTelemetry` Klasse bereit, die über eine Builder-Methode verfügt, die die Erstellung einer Instanz ermöglicht, `HttpClientBuilder` um OpenTelemetry basierte Spans und Kontextpropagierung für Apache HttpClient bereitzustellen.
```
io.opentelemetry.instrumentation
opentelemetry-apache-httpclient-5.2
2.15.0-alpha
compile
```
Im Folgenden finden Sie ein Codebeispiel aus dem [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/apache-httpclient/apache-httpclient-5.2/library). Der von newHttpClient () bereitgestellte HTTP-Client generiert Traces für ausgeführte Anfragen.
```
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.apachehttpclient.v5_2.ApacheHttpClientTelemetry;
import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
public class ApacheHttpClientConfiguration {
private OpenTelemetry openTelemetry;
public ApacheHttpClientConfiguration(OpenTelemetry openTelemetry) {
this.openTelemetry = openTelemetry;
}
// creates a new http client builder for constructing http clients with open telemetry instrumentation
public HttpClientBuilder createBuilder() {
return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClientBuilder();
}
// creates a new http client with open telemetry instrumentation
public HttpClient newHttpClient() {
return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClient();
}
}
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Die vollständige Liste der unterstützten Bibliotheksinstrumentierungen für OpenTelemetry Java finden Sie im entsprechenden GitHub Instrumentierungs-Repository unter [Unterstützte Bibliotheken, Frameworks, Anwendungsserver und JVMs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).
Alternativ können Sie in der OpenTelemetry Registry nachsehen, ob Instrumentierung OpenTelemetry unterstützt wird. Informationen zum Starten der Suche finden Sie unter [Registrierung](https://opentelemetry.io/ecosystem/registry/).
## Manuelles Erstellen von Trace-Daten
------
#### [ With X-Ray SDK ]
Mit dem X-Ray-SDK sind die `beginSubsegment` Methoden `beginSegment` und erforderlich, um X-Ray-Segmente und -Untersegmente manuell zu erstellen.
```
Segment segment = xrayRecorder.beginSegment("ManualSegment");
segment.putAnnotation("annotationKey", "annotationValue");
segment.putMetadata("metadataKey", "metadataValue");
try {
Subsegment subsegment = xrayRecorder.beginSubsegment("ManualSubsegment");
subsegment.putAnnotation("key", "value");
// Do something here
} catch (Exception e) {
subsegment.addException(e);
} finally {
xrayRecorder.endSegment();
}
```
------
#### [ With OpenTelemetry SDK ]
Sie können benutzerdefinierte Zeitspannen verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Span-Kind-Server in X-Ray-Segmente konvertiert werden, alle anderen Spans werden in X-Ray-Untersegmente umgewandelt.
Zunächst müssen Sie einen *Tracer* erstellen, um Spans zu generieren, die Sie mit dieser Methode abrufen können. `openTelemetry.getTracer` Dadurch wird eine Tracer-Instanz aus dem bereitgestellt`TracerProvider`, der im Beispiel global registriert wurde. [Lösungen für die manuelle Instrumentierung mit dem SDK](#xray-migration-sdk) Sie können so viele Tracer-Instanzen wie nötig erstellen, aber es ist üblich, einen Tracer für eine gesamte Anwendung zu haben.
```
Tracer tracer = openTelemetry.getTracer("my-app");
```
Sie können den Tracer verwenden, um Spans zu erstellen.
```
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
...
// SERVER span will become an X-Ray segment
Span span = tracer.spanBuilder("get-token")
.setKind(SpanKind.SERVER)
.setAttribute("key", "value")
.startSpan();
try (Scope ignored = span.makeCurrent()) {
span.setAttribute("metadataKey", "metadataValue");
span.setAttribute("annotationKey", "annotationValue");
// The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
span.setAttribute(AttributeKey.stringArrayKey("aws.xray.annotations"), List.of("annotationKey"));
// Do something here
}
span.end();
```
*Spans haben den Standardtyp INTERNAL.*
```
// Default span of type INTERNAL will become an X-Ray subsegment
Span span = tracer.spanBuilder("process-header")
.startSpan();
try (Scope ignored = span.makeCurrent()) {
doProcessHeader();
}
```
**Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry **
Im obigen Beispiel wird die `setAttribute` Methode verwendet, um jedem Bereich Attribute hinzuzufügen. Standardmäßig werden alle Span-Attribute in Metadaten in X-Rohdaten umgewandelt. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, fügt das obige Beispiel den Schlüssel dieses Attributs zur Liste des `aws.xray.annotations` Attributs hinzu. Weitere Informationen finden Sie unter [Aktivieren der benutzerdefinierten X-Ray-Anmerkungen](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations) und [Anmerkungen und Metadaten](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations).
**Mit OpenTelemetry basierten Java-Agenten**
Wenn Sie den Java-Agenten zur automatischen Instrumentierung Ihrer Anwendung verwenden, müssen Sie in Ihrer Anwendung eine manuelle Instrumentierung durchführen. Zum Beispiel, um Code innerhalb der Anwendung für Abschnitte zu instrumentieren, die von keiner Bibliothek für automatische Instrumentierung abgedeckt werden.
Um eine manuelle Instrumentierung mit dem Agenten durchzuführen, müssen Sie das `opentelemetry-api ` Artefakt verwenden. Die Artefaktversion darf nicht neuer als die Agentenversion sein.
```
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;
// ...
Span parentSpan = Span.current();
Tracer tracer = GlobalOpenTelemetry.getTracer("my-app");
Span span = tracer.spanBuilder("my-span-name")
.setParent(io.opentelemetry.context.Context.current().with(parentSpan))
.startSpan();
span.end();
```
------
## Lambda-Instrumentierung
------
#### [ With X-Ray SDK ]
Wenn Sie das X-Ray-SDK verwenden, ist nach der Aktivierung von *Active Tracing* auf Ihrem Lambda keine zusätzliche Konfiguration erforderlich, um das X-Ray-SDK zu verwenden. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie können Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellen.
------
#### [ With OpenTelemetry-based solutions ]
Lambda-Schichten mit automatischer Instrumentierung — Mithilfe der folgenden Lösungen können Sie Ihr Lambda automatisch mit AWS Lambda-Schichten von Drittanbietern instrumentieren:
+ AWS Lambda Layer für OpenTelemetry (empfohlen)
**Anmerkung**
Auf dieser Lambda-Schicht sind CloudWatch Application Signals standardmäßig aktiviert, wodurch die Leistungs- und Zustandsüberwachung für Ihre Lambda-Anwendung ermöglicht wird, indem sowohl Metriken als auch Traces erfasst werden. Um nur die Ablaufverfolgung zu ermöglichen, legen Sie die Umgebungsvariable Lambda fest. ` OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`
+ Ermöglicht die Leistungs- und Zustandsüberwachung für Ihre Lambda-Anwendung
+ Sammelt standardmäßig sowohl Metriken als auch Traces
+ AWS verwaltete Lambda-Schicht für ADOT Java. Weitere Informationen finden Sie unter [AWS Distro for OpenTelemetry Lambda Support for Java](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java).
Informationen zur Verwendung der manuellen Instrumentierung zusammen mit der Ebene für automatische Instrumentierung finden Sie unter[Lösungen für die manuelle Instrumentierung mit dem SDK](#xray-migration-sdk). Um weniger Kaltstarts zu erzielen, sollten Sie erwägen, OpenTelemetry manuelle Instrumente zu verwenden, um OpenTelemetry Traces für Ihre Lambda-Funktion zu generieren.
------
**OpenTelemetry manuelle Instrumentierung für AWS Lambda**
Betrachten Sie den folgenden Lambda-Funktionscode, der einen Amazon S3 ListBuckets S3-Aufruf durchführt.
```
package example;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
public class ListBucketsLambda implements RequestHandler {
private final S3Client S3_CLIENT = S3Client.builder()
.build();
@Override
public String handleRequest(String input, Context context) {
try {
ListBucketsResponse response = makeListBucketsCall();
context.getLogger().log("response: " + response.toString());
return "Success";
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private ListBucketsResponse makeListBucketsCall() {
try {
ListBucketsRequest listBucketsRequest = ListBucketsRequest.builder()
.build();
ListBucketsResponse response = S3_CLIENT.listBuckets(listBucketsRequest);
return response;
} catch (S3Exception e) {
throw new RuntimeException("Failed to call S3 listBuckets" + e.awsErrorDetails().errorMessage(), e);
}
}
}
```
Hier sind die Abhängigkeiten.
```
dependencies {
implementation('com.amazonaws:aws-lambda-java-core:1.2.3')
implementation('software.amazon.awssdk:s3:2.28.29')
implementation('org.slf4j:slf4j-nop:2.0.16')
}
```
Gehen Sie wie folgt vor, um Ihren Lambda-Handler und den Amazon S3 S3-Client manuell zu instrumentieren.
1. Ersetzen Sie Ihre Funktionsklassen, die `RequestHandler` (oder RequestStreamHandler) implementieren, durch solche, die `TracingRequestHandler` (oder TracingRequestStreamHandler) erweitern.
1. Instanziieren Sie ein Objekt TracerProvider und registrieren Sie es global. OpenTelemetrySdk TracerProvider Es wird empfohlen, das zu konfigurieren mit:
1. Ein einfacher Span-Prozessor mit einem X-Ray-UDP-Span-Exporter zum Senden von Traces an den UDP-X-Ray-Endpunkt von Lambda
1. Ein ParentBased Always-On-Sampler (Standard, falls nicht konfiguriert)
1. Eine Ressource, bei der service.name auf den Lambda-Funktionsnamen gesetzt ist
1. Ein Röntgen-Lambda-Propagator
1. Ändern Sie die `handleRequest` Methode in `doHandleRequest` und übergeben Sie das `OpenTelemetrySdk` Objekt an die Basisklasse.
1. Instrumentieren Sie den Amazon S3 S3-Client mit der OpenTemetry AWS SDK-Instrumentierung, indem Sie den Interceptor bei der Erstellung des Clients registrieren.
Sie benötigen die folgenden zugehörigen Abhängigkeiten OpenTelemetry.
```
dependencies {
...
implementation("software.amazon.distro.opentelemetry:aws-distro-opentelemetry-xray-udp-span-exporter:0.1.0")
implementation(platform('io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.14.0'))
implementation(platform('io.opentelemetry:opentelemetry-bom:1.48.0'))
implementation('io.opentelemetry:opentelemetry-sdk')
implementation('io.opentelemetry:opentelemetry-api')
implementation('io.opentelemetry.contrib:opentelemetry-aws-xray-propagator:1.45.0-alpha')
implementation('io.opentelemetry.contrib:opentelemetry-aws-resources:1.45.0-alpha')
implementation('io.opentelemetry.instrumentation:opentelemetry-aws-lambda-core-1.0:2.14.0-alpha')
implementation('io.opentelemetry.instrumentation:opentelemetry-aws-sdk-2.2:2.14.0-alpha')
}
```
Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen.
```
package example;
import java.time.Duration;
import com.amazonaws.services.lambda.runtime.Context;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.contrib.aws.resource.LambdaResource;
import io.opentelemetry.contrib.awsxray.propagator.AwsXrayLambdaPropagator;
import io.opentelemetry.instrumentation.awslambdacore.v1_0.TracingRequestHandler;
import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import static io.opentelemetry.semconv.ServiceAttributes.SERVICE_NAME;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.distro.opentelemetry.exporter.xray.udp.trace.AwsXrayUdpSpanExporterBuilder;
public class ListBucketsLambda extends TracingRequestHandler {
private static final Resource lambdaResource = LambdaResource.get();
private static final SdkTracerProvider sdkTracerProvider =
SdkTracerProvider.builder()
.addSpanProcessor(SimpleSpanProcessor.create(
new AwsXrayUdpSpanExporterBuilder().build()
))
.addResource(
lambdaResource
.merge(Resource.create(Attributes.of(SERVICE_NAME, System.getenv("AWS_LAMBDA_FUNCTION_NAME"))))
)
.setSampler(Sampler.parentBased(Sampler.alwaysOn()))
.build();
private static final OpenTelemetrySdk openTelemetry =
OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(AwsXrayLambdaPropagator.getInstance()))
.buildAndRegisterGlobal();
private static final AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
private final S3Client S3_CLIENT = S3Client.builder()
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(telemetry.newExecutionInterceptor())
.build())
.build();
public ListBucketsLambda() {
super(openTelemetry, Duration.ofMillis(0));
}
@Override
public String doHandleRequest(String input, Context context) {
try {
ListBucketsResponse response = makeListBucketsCall();
context.getLogger().log("response: " + response.toString());
return "Success";
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private ListBucketsResponse makeListBucketsCall() {
try {
ListBucketsRequest listBucketsRequest = ListBucketsRequest.builder()
.build();
ListBucketsResponse response = S3_CLIENT.listBuckets(listBucketsRequest);
return response;
} catch (S3Exception e) {
throw new RuntimeException("Failed to call S3 listBuckets" + e.awsErrorDetails().errorMessage(), e);
}
}
}
```
Wenn Sie die Lambda-Funktion aufrufen, sehen Sie in der Konsole unter *Trace Map* den CloudWatch folgenden Trace.
![\[Trace-Map in der Konsole CloudWatch .\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/SDKDeprecation_Java.png)
# Zu OpenTelemetry Go migrieren
Verwenden Sie die folgenden Codebeispiele, um Ihre Go-Anwendungen bei der Migration von X-Ray manuell mit dem OpenTelemetry SDK zu instrumentieren.
## Manuelle Instrumentierung mit dem SDK
------
#### [ Tracing setup with X-Ray SDK ]
Bei der Verwendung des X-Ray-SDK SDK for Go mussten Service-Plugins oder lokale Sampling-Regeln konfiguriert werden, bevor Ihr Code instrumentiert wurde.
```
func init() {
if os.Getenv("ENVIRONMENT") == "production" {
ec2.Init()
}
xray.Configure(xray.Config{
DaemonAddr: "127.0.0.1:2000",
ServiceVersion: "1.2.3",
})
}
```
------
#### [ Set up tracing with OpenTelemetry SDK ]
Konfigurieren Sie das OpenTelemetry SDK, indem Sie a instanziieren TracerProvider und es als globalen Tracer-Anbieter registrieren. Wir empfehlen die Konfiguration der folgenden Komponenten:
+ OTLP Trace Exporter — Erforderlich für den Export von Traces an den CloudWatch Agent oder Collector OpenTelemetry
+ X-Ray Propagator — Erforderlich für die Weitergabe des Trace-Kontextes an in X-Ray integrierte AWS Dienste
+ X-Ray Remote Sampler — Erforderlich für Probenentnahmeanfragen unter Verwendung von Röntgenprobenregeln
+ Ressourcendetektoren — Um Metadaten des Hosts zu erkennen, auf dem Ihre Anwendung ausgeführt wird
```
import (
"go.opentelemetry.io/contrib/detectors/aws/ec2"
"go.opentelemetry.io/contrib/propagators/aws/xray"
"go.opentelemetry.io/contrib/samplers/aws/xray"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
"go.opentelemetry.io/otel/sdk/trace"
)
func setupTracing() error {
ctx := context.Background()
exporterEndpoint := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
if exporterEndpoint == "" {
exporterEndpoint = "localhost:4317"
}
traceExporter, err := otlptracegrpc.New(ctx,
otlptracegrpc.WithInsecure(),
otlptracegrpc.WithEndpoint(exporterEndpoint))
if err != nil {
return fmt.Errorf("failed to create OTLP trace exporter: %v", err)
}
remoteSampler, err := xray.NewRemoteSampler(ctx, "my-service-name", "ec2")
if err != nil {
return fmt.Errorf("failed to create X-Ray Remote Sampler: %v", err)
}
ec2Resource, err := ec2.NewResourceDetector().Detect(ctx)
if err != nil {
return fmt.Errorf("failed to detect EC2 resource: %v", err)
}
tp := trace.NewTracerProvider(
trace.WithSampler(remoteSampler),
trace.WithBatcher(traceExporter),
trace.WithResource(ec2Resource),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(xray.Propagator{})
return nil
}
```
------
## Nachverfolgung eingehender Anfragen (HTTP-Handler-Instrumentierung)
------
#### [ With X-Ray SDK ]
Um einen HTTP-Handler mit X-Ray zu instrumentieren, wurde die X-Ray-Handler-Methode verwendet, um Segmente zu generieren mit NewFixedSegmentNamer.
```
func main() {
http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("myApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello!"))
})))
http.ListenAndServe(":8000", nil)
}
```
------
#### [ With OpenTelemetry SDK ]
Um einen HTTP-Handler zu instrumentieren OpenTelemetry, verwenden Sie die NewHandler-Methode OpenTelemetry von, um Ihren ursprünglichen Handler-Code zu umschließen.
```
import (
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
helloHandler := func(w http.ResponseWriter, req *http.Request) {
ctx := req.Context()
span := trace.SpanFromContext(ctx)
span.SetAttributes(attribute.Bool("isHelloHandlerSpan", true), attribute.String("attrKey", "attrValue"))
_, _ = io.WriteString(w, "Hello World!\n")
}
otelHandler := otelhttp.NewHandler(http.HandlerFunc(helloHandler), "Hello")
http.Handle("/hello", otelHandler)
err = http.ListenAndServe(":8080", nil)
if err != nil {
log.Fatal(err)
}
```
------
## AWS SDK for Go v2-Instrumentierung
------
#### [ With X-Ray SDK ]
Um ausgehende AWS Anfragen vom AWS SDK zu instrumentieren, wurden Ihre Kunden wie folgt instrumentiert:
```
// Create a segment
ctx, root := xray.BeginSegment(context.TODO(), "AWSSDKV2_Dynamodb")
defer root.Close(nil)
cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-west-2"))
if err != nil {
log.Fatalf("unable to load SDK config, %v", err)
}
// Instrumenting AWS SDK v2
awsv2.AWSV2Instrumentor(&cfg.APIOptions)
// Using the Config value, create the DynamoDB client
svc := dynamodb.NewFromConfig(cfg)
// Build the request with its input parameters
_, err = svc.ListTables(ctx, &dynamodb.ListTablesInput{
Limit: aws.Int32(5),
})
if err != nil {
log.Fatalf("failed to list tables, %v", err)
}
```
------
#### [ With OpenTelemetry SDK ]
Die Ablaufverfolgungsunterstützung für AWS Downstream-SDK-Aufrufe wird vom OpenTelemetry AWS SDK for Go v2 Instrumentation bereitgestellt. Hier ist ein Beispiel für die Nachverfolgung eines S3-Client-Anrufs:
```
import (
...
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
"go.opentelemetry.io/otel"
oteltrace "go.opentelemetry.io/otel/trace"
awsConfig "github.com/aws/aws-sdk-go-v2/config"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
)
...
// init aws config
cfg, err := awsConfig.LoadDefaultConfig(ctx)
if err != nil {
panic("configuration error, " + err.Error())
}
// instrument all aws clients
otelaws.AppendMiddlewares(&.APIOptions)
// Call to S3
s3Client := s3.NewFromConfig(cfg)
input := &s3.ListBucketsInput{}
result, err := s3Client.ListBuckets(ctx, input)
if err != nil {
fmt.Printf("Got an error retrieving buckets, %v", err)
return
}
```
------
## Instrumentieren von ausgehenden HTTP-Aufrufen
------
#### [ With X-Ray SDK ]
Um ausgehende HTTP-Aufrufe mit X-Ray zu instrumentieren, wurde der Xray.Client verwendet, um eine Kopie eines bereitgestellten HTTP-Clients zu erstellen.
```
myClient := xray.Client(http-client)
resp, err := ctxhttp.Get(ctx, xray.Client(nil), url)
```
------
#### [ With OpenTelemetry SDK ]
Um HTTP-Clients mit zu instrumentieren OpenTelemetry, verwenden Sie OpenTelemetry otelhttp. NewTransport Methode, um das HTTP zu umschließen. DefaultTransport.
```
import (
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
// Create an instrumented HTTP client.
httpClient := &http.Client{
Transport: otelhttp.NewTransport(
http.DefaultTransport,
),
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
fmt.Printf("failed to make http request, %v\n", err)
}
// Request body must be closed
defer func(Body io.ReadCloser) {
err := Body.Close()
if err != nil {
fmt.Printf("failed to close http response body, %v\n", err)
}
}(res.Body)
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Die vollständige Liste der unterstützten Bibliotheksinstrumentierungen für OpenTelemetry Go finden Sie unter [Instrumentierungspakete](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation#instrumentation-packages).
Alternativ können Sie in der OpenTelemetry [Registry](https://opentelemetry.io/ecosystem/registry/) unter Registrierung herausfinden, ob Instrumentierung für Ihre Bibliothek OpenTelemetry unterstützt wird.
## Manuelles Erstellen von Trace-Daten
------
#### [ With X-Ray SDK ]
Mit dem X-Ray-SDK waren die BeginSubsegment Methoden BeginSegment und erforderlich, um X-Ray-Segmente und Untersegmente manuell zu erstellen.
```
// Start a segment
ctx, seg := xray.BeginSegment(context.Background(), "service-name")
// Start a subsegment
subCtx, subSeg := xray.BeginSubsegment(ctx, "subsegment-name")
// Add metadata or annotation here if necessary
xray.AddAnnotation(subCtx, "annotationKey", "annotationValue")
xray.AddMetadata(subCtx, "metadataKey", "metadataValue")
subSeg.Close(nil)
// Close the segment
seg.Close(nil)
```
------
#### [ With OpenTelemetry SDK ]
Verwenden Sie benutzerdefinierte Zeitspannen, um die Leistung interner Aktivitäten zu überwachen, die nicht in den Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Untersegmente umgewandelt.
Zunächst müssen Sie einen Tracer erstellen, um Spannen zu generieren, die Sie mit der Methode abrufen können. `otel.Tracer` Dadurch wird eine Tracer-Instanz aus dem bereitgestellt TracerProvider , der im Tracing-Setup-Beispiel global registriert wurde. Sie können so viele Tracer-Instanzen wie nötig erstellen, es ist jedoch üblich, einen Tracer für eine gesamte Anwendung zu verwenden.
```
tracer := otel.Tracer("application-tracer")
```
```
import (
...
oteltrace "go.opentelemetry.io/otel/trace"
)
...
var attributes = []attribute.KeyValue{
attribute.KeyValue{Key: "metadataKey", Value: attribute.StringValue("metadataValue")},
attribute.KeyValue{Key: "annotationKey", Value: attribute.StringValue("annotationValue")},
attribute.KeyValue{Key: "aws.xray.annotations", Value: attribute.StringSliceValue([]string{"annotationKey"})},
}
ctx := context.Background()
parentSpanContext, parentSpan := tracer.Start(ctx, "ParentSpan", oteltrace.WithSpanKind(oteltrace.SpanKindServer), oteltrace.WithAttributes(attributes...))
_, childSpan := tracer.Start(parentSpanContext, "ChildSpan", oteltrace.WithSpanKind(oteltrace.SpanKindInternal))
// ...
childSpan.End()
parentSpan.End()
```
**Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry **
Im obigen Beispiel wird die `WithAttributes` Methode verwendet, um jedem Bereich Attribute hinzuzufügen. Beachten Sie, dass standardmäßig alle Span-Attribute in X-Rohdaten in Metadaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, fügen Sie den Schlüssel des Attributs zur Liste des `aws.xray.annotations` Attributs hinzu. Weitere Informationen finden Sie unter [Aktivieren der benutzerdefinierten X-Ray-Anmerkungen.](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)
------
## Manuelle Lambda-Instrumentierung
------
#### [ With X-Ray SDK ]
Mit dem X-Ray-SDK waren nach der Aktivierung von *Active Tracing* auf Ihrem Lambda keine zusätzlichen Konfigurationen erforderlich, um das X-Ray-SDK zu verwenden. Lambda hat ein Segment erstellt, das den Lambda-Handler-Aufruf darstellt, und Sie haben Untersegmente mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellt.
------
#### [ With OpenTelemetry SDK ]
Der folgende Lambda-Funktionscode (ohne Instrumentierung) führt einen Amazon S3 ListBuckets S3-Aufruf und eine ausgehende HTTP-Anfrage aus.
```
package main
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
awsconfig "github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
)
func lambdaHandler(ctx context.Context) (interface{}, error) {
// Initialize AWS config.
cfg, err := awsconfig.LoadDefaultConfig(ctx)
if err != nil {
panic("configuration error, " + err.Error())
}
s3Client := s3.NewFromConfig(cfg)
// Create an HTTP client.
httpClient := &http.Client{
Transport: http.DefaultTransport,
}
input := &s3.ListBucketsInput{}
result, err := s3Client.ListBuckets(ctx, input)
if err != nil {
fmt.Printf("Got an error retrieving buckets, %v", err)
}
fmt.Println("Buckets:")
for _, bucket := range result.Buckets {
fmt.Println(*bucket.Name + ": " + bucket.CreationDate.Format("2006-01-02 15:04:05 Monday"))
}
fmt.Println("End Buckets.")
req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
fmt.Printf("failed to make http request, %v\n", err)
}
defer func(Body io.ReadCloser) {
err := Body.Close()
if err != nil {
fmt.Printf("failed to close http response body, %v\n", err)
}
}(res.Body)
var data map[string]interface{}
err = json.NewDecoder(res.Body).Decode(&data)
if err != nil {
fmt.Printf("failed to read http response body, %v\n", err)
}
fmt.Printf("Latest ADOT Go Release is '%s'\n", data["name"])
return events.APIGatewayProxyResponse{
StatusCode: http.StatusOK,
Body: os.Getenv("_X_AMZN_TRACE_ID"),
}, nil
}
func main() {
lambda.Start(lambdaHandler)
}
```
Gehen Sie wie folgt vor, um Ihren Lambda-Handler und den Amazon S3 S3-Client manuell zu instrumentieren:
1. Instanziieren Sie in *main ()* a TracerProvider (tp) und registrieren Sie es als globalen Tracer-Anbieter. TracerProvider Es wird empfohlen, den zu konfigurieren mit:
1. Einfacher Span-Prozessor mit einem X-Ray-UDP-Span-Exporter zum Senden von Traces an den UDP-X-Ray-Endpunkt von Lambda
1. Ressource, bei der *service.name auf den Lambda-Funktionsnamen* gesetzt ist
1. Ändern Sie die Verwendung von to. `lambda.Start(lambdaHandler)` `lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))`
1. Instrumentieren Sie den Amazon S3 S3-Client mit der OpenTemetry AWS SDK-Instrumentierung, indem Sie OpenTelemetry Middleware für an `aws-sdk-go-v2` die Amazon S3 S3-Client-Konfiguration anhängen.
1. Instrumentieren Sie den HTTP-Client, indem Sie die `otelhttp.NewTransport` Methode verwenden, um OpenTelemetry den zu umschließen. `http.DefaultTransport`
Der folgende Code ist ein Beispiel dafür, wie die Lambda-Funktion nach den Änderungen aussehen wird. Sie können zusätzlich zu den automatisch bereitgestellten Bereichen manuell weitere benutzerdefinierte Bereiche erstellen.
```
package main
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"github.com/aws-observability/aws-otel-go/exporters/xrayudp"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
awsconfig "github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
lambdadetector "go.opentelemetry.io/contrib/detectors/aws/lambda"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda/xrayconfig"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
"go.opentelemetry.io/contrib/propagators/aws/xray"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/sdk/resource"
"go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)
func lambdaHandler(ctx context.Context) (interface{}, error) {
// Initialize AWS config.
cfg, err := awsconfig.LoadDefaultConfig(ctx)
if err != nil {
panic("configuration error, " + err.Error())
}
// Instrument all AWS clients.
otelaws.AppendMiddlewares(&cfg.APIOptions)
// Create an instrumented S3 client from the config.
s3Client := s3.NewFromConfig(cfg)
// Create an instrumented HTTP client.
httpClient := &http.Client{
Transport: otelhttp.NewTransport(
http.DefaultTransport,
),
}
// return func(ctx context.Context) (interface{}, error) {
input := &s3.ListBucketsInput{}
result, err := s3Client.ListBuckets(ctx, input)
if err != nil {
fmt.Printf("Got an error retrieving buckets, %v", err)
}
fmt.Println("Buckets:")
for _, bucket := range result.Buckets {
fmt.Println(*bucket.Name + ": " + bucket.CreationDate.Format("2006-01-02 15:04:05 Monday"))
}
fmt.Println("End Buckets.")
req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
fmt.Printf("failed to make http request, %v\n", err)
}
defer func(Body io.ReadCloser) {
err := Body.Close()
if err != nil {
fmt.Printf("failed to close http response body, %v\n", err)
}
}(res.Body)
var data map[string]interface{}
err = json.NewDecoder(res.Body).Decode(&data)
if err != nil {
fmt.Printf("failed to read http response body, %v\n", err)
}
fmt.Printf("Latest ADOT Go Release is '%s'\n", data["name"])
return events.APIGatewayProxyResponse{
StatusCode: http.StatusOK,
Body: os.Getenv("_X_AMZN_TRACE_ID"),
}, nil
}
func main() {
ctx := context.Background()
detector := lambdadetector.NewResourceDetector()
lambdaResource, err := detector.Detect(context.Background())
if err != nil {
fmt.Printf("failed to detect lambda resources: %v\n", err)
}
var attributes = []attribute.KeyValue{
attribute.KeyValue{Key: semconv.ServiceNameKey, Value: attribute.StringValue(os.Getenv("AWS_LAMBDA_FUNCTION_NAME"))},
}
customResource := resource.NewWithAttributes(semconv.SchemaURL, attributes...)
mergedResource, _ := resource.Merge(lambdaResource, customResource)
xrayUdpExporter, _ := xrayudp.NewSpanExporter(ctx)
tp := trace.NewTracerProvider(
trace.WithSpanProcessor(trace.NewSimpleSpanProcessor(xrayUdpExporter)),
trace.WithResource(mergedResource),
)
defer func(ctx context.Context) {
err := tp.Shutdown(ctx)
if err != nil {
fmt.Printf("error shutting down tracer provider: %v", err)
}
}(ctx)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(xray.Propagator{})
lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))
}
```
------
Wenn Sie Lambda aufrufen, sehen Sie in der Konsole den folgenden Trace: `Trace Map` CloudWatch
![\[Trace-Map in der CloudWatch Konsole für Golang.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/deprecation_golang.png)
# Migrieren Sie zu Node.js OpenTelemetry
In diesem Abschnitt wird erklärt, wie Sie Ihre Node.js -Anwendungen vom X-Ray SDK auf migrieren OpenTelemetry. Er behandelt sowohl automatische als auch manuelle Instrumentierungsansätze und bietet konkrete Beispiele für gängige Anwendungsfälle.
Das X-Ray Node.js SDK hilft Ihnen, Ihre Node.js -Anwendungen manuell für die Ablaufverfolgung zu instrumentieren. Dieser Abschnitt enthält Codebeispiele für die Migration von X-Ray zu OpenTelemetry Instrumentation.
**Topics**
+ [Automatische Instrumentierungslösungen ohne Code](#zero-code-instrumentation)
+ [Lösungen für die manuelle Instrumentierung](#manual-instrumentation)
+ [Nachverfolgung eingehender Anfragen](#tracing-incoming-requests)
+ [AWS SDK V3-Instrumentierung JavaScript](#aws-sdk-instrumentation)
+ [Instrumentieren von ausgehenden HTTP-Aufrufen](#http-instrumentation)
+ [Instrumentierungsunterstützung für andere Bibliotheken](#other-libraries)
+ [Manuelles Erstellen von Trace-Daten](#manual-trace-creation)
+ [Lambda-Instrumentierung](#lambda-instrumentation)
## Automatische Instrumentierungslösungen ohne Code
Um Anfragen mit dem X-Ray SDK für Node.js nachzuverfolgen, müssen Sie Ihren Anwendungscode ändern. Mit OpenTelemetry können Sie Zero-Code-Lösungen zur automatischen Instrumentierung verwenden, um Anfragen zu verfolgen.
**Automatische Null-Code-Instrumentierung mit OpenTelemetry basierten automatischen Instrumentierungen.**
1. Verwenden der automatischen Instrumentierung von AWS Distro for OpenTelemetry (ADOT) für Node.js — Informationen zur automatischen Instrumentierung für die Anwendung Node.js finden Sie unter [Tracing and Metrics with the AWS](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) Distro for Auto-Instrumentation. OpenTelemetry JavaScript
(Optional) Sie können CloudWatch Application Signals auch bei der automatischen Instrumentierung Ihrer Anwendungen AWS mit der JavaScript automatischen ADOT-Instrumentierung aktivieren, um den aktuellen Anwendungsstatus zu überwachen und die langfristige Anwendungsleistung anhand Ihrer Geschäftsziele zu verfolgen. Application Signals bietet Ihnen einen einheitlichen, anwendungsorientierten Überblick über Ihre Anwendungen, Services und Abhängigkeiten und unterstützt Sie bei der Überwachung und Diagnose des Zustands Ihrer Anwendungen. Weitere Informationen finden Sie unter [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
1. [Verwendung der automatischen OpenTelemetry JavaScript Null-Code-Instrumentierung — Informationen zur automatischen Instrumentierung mit der finden Sie unter Zero-Code-Instrumentierung. OpenTelemetry JavaScript JavaScript ](https://opentelemetry.io/docs/zero-code/js/)
## Lösungen für die manuelle Instrumentierung
------
#### [ Tracing setup with X-Ray SDK ]
Wenn das X-Ray-SDK für Node.js verwendet wurde, musste das `aws-xray-sdk` Paket das X-Ray-SDK mit Service-Plug-ins oder lokalen Sampling-Regeln konfigurieren, bevor das SDK zur Instrumentierung Ihres Codes verwendet werden konnte.
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
AWSXRay.middleware.setSamplingRules();
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
**Anmerkung**
AWS X-Ray Remote Sampling kann derzeit nicht für OpenTelemetry JS konfiguriert werden. Unterstützung für X-Ray Remote Sampling ist derzeit jedoch über die ADOT Auto-Instrumentation for Node.js verfügbar.
Für das folgende Codebeispiel benötigen Sie die folgenden Abhängigkeiten:
```
npm install --save \
@opentelemetry/api \
@opentelemetry/sdk-node \
@opentelemetry/exporter-trace-otlp-proto \
@opentelemetry/propagator-aws-xray \
@opentelemetry/resource-detector-aws
```
Sie müssen das OpenTelemetry SDK einrichten und konfigurieren, bevor Sie Ihren Anwendungscode ausführen können. Dies kann mit dem Flag [—-require](https://nodejs.org/api/cli.html#-r---require-module) geschehen. Erstellen Sie eine Datei mit dem Namen *instrumentation.js*, die Ihre OpenTelemetry Instrumentierungskonfiguration und Ihr Setup enthält.
Es wird empfohlen, die folgenden Komponenten zu konfigurieren:
+ OTLPTraceExporter — Erforderlich für den Export von Traces zum CloudWatch OpenTelemetry Agent/Collector
+ AWSXRayPropagator — Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind
+ Ressourcendetektoren (z. B. Amazon EC2 Resource Detector) — Um Metadaten des Hosts zu erkennen, auf dem Ihre Anwendung ausgeführt wird
```
/*instrumentation.js*/
// Require dependencies
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { AWSXRayPropagator } = require("@opentelemetry/propagator-aws-xray");
const { detectResources } = require('@opentelemetry/resources');
const { awsEc2Detector } = require('@opentelemetry/resource-detector-aws');
const resource = detectResources({
detectors: [awsEc2Detector],
});
const _traceExporter = new OTLPTraceExporter({
url: 'http://localhost:4318/v1/traces'
});
const sdk = new NodeSDK({
resource: resource,
textMapPropagator: new AWSXRayPropagator(),
traceExporter: _traceExporter
});
sdk.start();
```
Anschließend können Sie Ihre Anwendung mit Ihrem OpenTelemetry Setup wie folgt ausführen:
```
node --require ./instrumentation.js app.js
```
Sie können die Instrumentierung der OpenTelemetry SDK-Bibliothek verwenden, um automatisch Spans für Bibliotheken wie das AWS SDK zu erstellen. Wenn Sie diese aktivieren, werden automatisch Spans für Module wie das AWS SDK für Version 3 erstellt. JavaScript OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen.
Um alle Instrumentierungen zu aktivieren, installieren Sie das Paket: `@opentelemetry/auto-instrumentations-node`
```
npm install @opentelemetry/auto-instrumentations-node
```
Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen zu aktivieren, wie unten gezeigt.
```
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
...
const sdk = new NodeSDK({
resource: resource,
instrumentations: [getNodeAutoInstrumentations()],
textMapPropagator: new AWSXRayPropagator(),
traceExporter: _traceExporter
});
```
------
#### [ Tracing setup with ADOT auto-instrumentation for Node.js ]
Sie können die automatische ADOT-Instrumentierung für Node.js verwenden, um Ihre Node.js -Anwendungen automatisch zu konfigurieren OpenTelemetry . Durch die Verwendung von ADOT Auto-Instrumentation müssen Sie keine manuellen Codeänderungen vornehmen, um eingehende Anfragen oder Bibliotheken wie AWS SDK- oder HTTP-Clients nachzuverfolgen. Weitere Informationen finden Sie unter [Tracing und Metriken mit der AWS Distro](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) for Auto-Instrumentation. OpenTelemetry JavaScript
Die automatische ADOT-Instrumentierung für Node.js unterstützt:
+ Röntgenfernprobenentnahme durch Umgebungsvariable — `export OTEL_TRACES_SAMPLER=xray`
+ Übertragung des X-Ray-Trace-Kontextes (standardmäßig aktiviert)
+ Ressourcenerkennung (Ressourcenerkennung für Amazon EC2-, Amazon ECS- und Amazon EKS-Umgebungen ist standardmäßig aktiviert)
+ Automatische Bibliotheksinstrumentierung für alle unterstützten OpenTelemetry Instrumentierungen, die disabled/enabled selektiv durch Umgebungsvariablen und Umgebungsvariablen gesteuert werden können `OTEL_NODE_ENABLED_INSTRUMENTATIONS` `OTEL_NODE_DISABLED_INSTRUMENTATIONS`
+ Manuelles Erstellen von Spans
------
## Nachverfolgung eingehender Anfragen
------
#### [ With X-Ray SDK ]
**Express.js**
Mit dem X-Ray-SDK zur Verfolgung eingehender HTTP-Anfragen, die von den Anwendungen *Express.js* empfangen `AWSXRay.express.closeSegment()` wurden, mussten die beiden Middlewares `AWSXRay.express.openSegment()` und die beiden Middlewares alle Ihre definierten Routen umschließen, um sie zu verfolgen.
```
app.use(xrayExpress.openSegment('defaultName'));
...
app.use(xrayExpress.closeSegment());
```
**Erneut stifizieren**
Um eingehende HTTP-Anfragen zu verfolgen, die von `Restify` Anwendungen empfangen wurden, wurde die Middleware aus dem X-Ray SDK verwendet, indem enable über das `aws-xray-sdk-restify ` Modul auf dem Restify-Server ausgeführt wurde:
```
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');
var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));
```
------
#### [ With OpenTelemetry SDK ]
**Express.js**
Die Ablaufverfolgungsunterstützung für eingehende Anfragen für `Express.js` wird durch die [OpenTelemetry HTTP-Instrumentierung und die [OpenTelemetry Express-Instrumentierung](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express)](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http) bereitgestellt. Installieren Sie die folgenden Abhängigkeiten mit`npm`:
```
npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
```
Aktualisieren Sie die OpenTelemetry SDK-Konfiguration, um die Instrumentierung für das Express-Modul zu aktivieren:
```
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
...
const sdk = new NodeSDK({
...
instrumentations: [
...
// Express instrumentation requires HTTP instrumentation
new HttpInstrumentation(),
new ExpressInstrumentation(),
],
});
```
**Erneut stifizieren**
[Für Restify-Anwendungen benötigen Sie die Restify-Instrumentierung. OpenTelemetry ](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify) Installieren Sie die folgende Abhängigkeit:
```
npm install --save @opentelemetry/instrumentation-restify
```
Aktualisieren Sie die OpenTelemetry SDK-Konfiguration, um die Instrumentierung für das Restify-Modul zu aktivieren:
```
const { RestifyInstrumentation } = require('@opentelemetry/instrumentation-restify');
...
const sdk = new NodeSDK({
...
instrumentations: [
...
new RestifyInstrumentation(),
],
});
```
------
## AWS SDK V3-Instrumentierung JavaScript
------
#### [ With X-Ray SDK ]
Um ausgehende AWS Anfragen vom AWS SDK zu instrumentieren, haben Sie Clients wie im folgenden Beispiel instrumentiert:
```
import { S3, PutObjectCommand } from '@aws-sdk/client-s3';
const s3 = AWSXRay.captureAWSv3Client(new S3({}));
await s3.send(new PutObjectCommand({
Bucket: bucketName,
Key: keyName,
Body: 'Hello!',
}));
```
------
#### [ With OpenTelemetry SDK ]
Die Unterstützung der Ablaufverfolgung für AWS Downstream-SDK-Aufrufe an DynamoDB, Amazon S3 und andere wird durch die OpenTelemetry AWS SDK-Instrumentierung bereitgestellt. Installieren Sie die folgende Abhängigkeit mit: `npm`
```
npm install --save @opentelemetry/instrumentation-aws-sdk
```
Aktualisieren Sie die OpenTelemetry SDK-Konfiguration mit der AWS SDK-Instrumentierung.
```
import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
...
const sdk = new NodeSDK({
...
instrumentations: [
...
new AwsInstrumentation()
],
});
```
------
## Instrumentieren von ausgehenden HTTP-Aufrufen
------
#### [ With X-Ray SDK ]
Um ausgehende HTTP-Anfragen mit X-Ray zu instrumentieren, war es erforderlich, Clients zu instrumentieren. Siehe zum Beispiel unten.
Einzelne HTTP-Clients
```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```
Alle HTTP-Clients (global)
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```
------
#### [ With OpenTelemetry SDK ]
Die Ablaufverfolgungsunterstützung für die HTTP-Clients von Node.js wird von der OpenTelemetry HTTP Instrumentation bereitgestellt. Installieren Sie die folgende Abhängigkeit mit`npm`:
```
npm install --save @opentelemetry/instrumentation-http
```
Aktualisieren Sie die OpenTelemetry SDK-Konfiguration wie folgt:
```
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
...
const sdk = new NodeSDK({
...
instrumentations: [
...
new HttpInstrumentation(),
],
});
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Die vollständige Liste der unterstützten Bibliotheksinstrumentationen finden Sie OpenTelemetry JavaScript unter [Unterstützte Instrumentationen](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations).
[Alternativ können Sie in der OpenTelemetry Registry unter Registrierung herausfinden, ob Instrumentierung für Ihre Bibliothek OpenTelemetry unterstützt wird.](https://opentelemetry.io/ecosystem/registry/)
## Manuelles Erstellen von Trace-Daten
------
#### [ With X-Ray SDK ]
Bei Verwendung von X-Ray war der `aws-xray-sdk` Paketcode erforderlich, um Segmente und ihre untergeordneten Untersegmente manuell zu erstellen, um Ihre Anwendung zu verfolgen.
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.enableManualMode();
var segment = new AWSXRay.Segment('myApplication');
captureFunc('1', function(subsegment1) {
captureFunc('2', function(subsegment2) {
}, subsegment1);
}, segment);
segment.close();
segment.flush();
```
------
#### [ With OpenTelemetry SDK ]
Sie können benutzerdefinierte Zeitspannen erstellen und verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentierungsbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Untersegmente umgewandelt. Weitere Informationen hierzu finden Sie unter [Segmente](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments).
Nachdem Sie das OpenTelemetry SDK im Tracing-Setup konfiguriert haben, benötigen Sie eine Tracer-Instanz, um Spans zu erstellen. Sie können so viele Tracer-Instanzen wie nötig erstellen, es ist jedoch üblich, einen Tracer für eine gesamte Anwendung zu verwenden.
```
const { trace, SpanKind } = require('@opentelemetry/api');
// Get a tracer instance
const tracer = trace.getTracer('your-tracer-name');
...
// This span will appear as a segment in X-Ray
tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
// Do work here
// This span will appear as a subsegment in X-Ray
tracer.startActiveSpan('operation2', { kind: SpanKind.INTERNAL }, innerSpan => {
// Do more work here
innerSpan.end();
});
span.end();
});
```
**Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry **
Sie können Ihren Spans auch benutzerdefinierte Schlüssel-Wert-Paare als Attribute hinzufügen. Beachten Sie, dass alle diese Span-Attribute standardmäßig in Metadaten in X-Rohdaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, fügen Sie den Schlüssel des Attributs zur Liste des `aws.xray.annotations` Attributs hinzu. Weitere Informationen finden Sie unter [Aktivieren der benutzerdefinierten X-Ray-Anmerkungen.](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)
```
tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
span.setAttribute('metadataKey', 'metadataValue');
span.setAttribute('annotationKey', 'annotationValue');
// The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
span.setAttribute('aws.xray.annotations', ['annotationKey']);
// Do work here
span.end();
});
```
------
## Lambda-Instrumentierung
------
#### [ With X-Ray SDK ]
Nachdem Sie *Active Tracing* für Ihre Lambda-Funktion aktiviert hatten, war das X-Ray SDK ohne zusätzliche Konfiguration erforderlich. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie haben Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellt.
------
#### [ With OpenTelemetry SDK ]
Sie können Ihr Lambda automatisch mit verkauften AWS Lambda-Layern instrumentieren. Es gibt zwei Lösungen:
+ (Empfohlen) AWS Lambda Layer für OpenTelemetry
**Anmerkung**
Auf dieser Lambda-Schicht sind CloudWatch Application Signals standardmäßig aktiviert, wodurch die Leistungs- und Zustandsüberwachung für Ihre Lambda-Anwendung ermöglicht wird, indem sowohl Metriken als auch Traces erfasst werden. Wenn Sie nur die Ablaufverfolgung wünschen, sollten Sie die Umgebungsvariable Lambda festlegen. `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` Weitere Informationen finden Sie unter [Aktivieren Ihrer Anwendungen auf Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ AWS verwaltete Lambda-Schicht für ADOT JS. Weitere Informationen finden Sie unter [AWS Distro for OpenTelemetry Lambda Support For](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js). JavaScript
**Manuelles Erstellen von Spans mit Lambda-Instrumentierung**
Der ADOT JavaScript Lambda Layer bietet zwar automatische Instrumentierung für Ihre Lambda-Funktion, Sie müssen jedoch möglicherweise eine manuelle Instrumentierung in Ihrem Lambda durchführen, um beispielsweise benutzerdefinierte Daten bereitzustellen oder Code innerhalb der Lambda-Funktion selbst zu instrumentieren, der nicht durch Bibliotheksinstrumentierungen abgedeckt wird.
Um neben der automatischen Instrumentierung auch eine manuelle Instrumentierung durchzuführen, müssen Sie eine Abhängigkeit hinzufügen. `@opentelemetry/api` Es wird empfohlen, dass es sich bei der Version dieser Abhängigkeit um dieselbe Version derselben Abhängigkeit handelt, die vom ADOT JavaScript SDK verwendet wird. Sie können die OpenTelemetry API verwenden, um manuell Spans in Ihrer Lambda-Funktion zu erstellen.
Um die `@opentelemetry/api` Abhängigkeit mit NPM hinzuzufügen:
```
npm install @opentelemetry/api
```
------
# Migrieren Sie zu .NET OpenTelemetry
Wenn Sie X-Ray Tracing in Ihren .NET-Anwendungen verwenden, wird das X-Ray-.NET-SDK mit manuellem Aufwand für die Instrumentierung verwendet.
Dieser Abschnitt enthält Codebeispiele im [Lösungen für die manuelle Instrumentierung mit dem SDK](#manual-instrumentation-dotnet) Abschnitt für die Migration von der manuellen X-Ray-Instrumentierungslösung zu OpenTelemetry manuellen Instrumentierungslösungen für.NET. Alternativ können Sie von manueller X-Ray-Instrumentierung zu OpenTelemetry automatischen Instrumentierungslösungen für Instrumenten-.NET-Anwendungen migrieren, ohne den Quellcode der Anwendung in [Automatische Instrumentierungslösungen ohne Code](#zero-code-instrumentation-dotnet) diesem Abschnitt ändern zu müssen.
**Topics**
+ [Automatische Instrumentierungslösungen ohne Code](#zero-code-instrumentation-dotnet)
+ [Lösungen für die manuelle Instrumentierung mit dem SDK](#manual-instrumentation-dotnet)
+ [Manuelles Erstellen von Trace-Daten](#manual-trace-creation-dotnet)
+ [Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)](#tracing-incoming-requests-dotnet)
+ [AWS SDK-Instrumentierung](#aws-sdk-instrumentation-dotnet)
+ [Instrumentieren von ausgehenden HTTP-Aufrufen](#http-instrumentation-dotnet)
+ [Instrumentierungsunterstützung für andere Bibliotheken](#other-libraries-dotnet)
+ [Lambda-Instrumentierung](#lambda-instrumentation)
## Automatische Instrumentierungslösungen ohne Code
OpenTelemetry bietet automatische Instrumentierungslösungen ohne Code. Diese Lösungen verfolgen Anfragen, ohne dass Änderungen an Ihrem Anwendungscode erforderlich sind.
**OpenTelemetrybasierte Optionen für automatische Instrumentierung**
1. Verwenden der AWS Distro for OpenTelemetry (ADOT) Auto-Instrumentation für .NET — Informationen zur automatischen Instrumentierung von.NET-Anwendungen finden Sie unter [Tracing and Metrics with the AWS Distro](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) for .NET Auto-Instrumentation. OpenTelemetry
(Optional) Aktivieren Sie CloudWatch Application Signals, wenn Sie Ihre Anwendungen AWS mit der automatischen ADOT.NET-Instrumentierung automatisch instrumentieren, um:
+ Überwachen Sie den aktuellen Zustand der Anwendung
+ Verfolgen Sie die langfristige Anwendungsleistung anhand der Geschäftsziele
+ Verschaffen Sie sich einen einheitlichen, anwendungsorientierten Überblick über Ihre Anwendungen, Services und Abhängigkeiten
+ Überwachen und prüfen Sie den Zustand Ihrer Anwendungen
Weitere Informationen finden Sie unter [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
1. Verwenden der automatischen Null-Code-Instrumentierung OpenTelemetry von.Net — Informationen zur automatischen Instrumentierung OpenTelemetry mit.Net finden Sie unter [Tracing and Metrics with the AWS Distro](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) for .NET Auto-Instrumentation. OpenTelemetry
## Lösungen für die manuelle Instrumentierung mit dem SDK
------
#### [ Tracing configuration with X-Ray SDK ]
Für .NET-Webanwendungen wird das X-Ray-SDK im Abschnitt AppSettings der `Web.config` Datei konfiguriert.
Beispiel Web.config
```
```
Für .NET Core wird eine Datei `appsettings.json` mit einem Schlüssel der obersten Ebene namens verwendet, und dann `XRay` wird ein Konfigurationsobjekt erstellt, um den X-Ray-Recorder zu initialisieren.
Beispiel für.NET `appsettings.json`
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin"
}
}
```
Beispiel für.NET Core Program.cs — Recorder-Konfiguration
```
using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);
```
------
#### [ Tracing configuration with OpenTelemetry SDK ]
****
Fügen Sie diese Abhängigkeiten hinzu:
```
dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Contrib.Extensions.AWSXRay
dotnet add package OpenTelemetry.Sampler.AWS --prerelease
dotnet add package OpenTelemetry.Resources.AWS
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
```
Konfigurieren Sie das OpenTelemetry SDK für Ihre .NET-Anwendung, indem Sie Global einrichten TracerProvider. Die folgende Beispielkonfiguration ermöglicht auch die Instrumentierung für`ASP.NET Core`. Informationen zur `ASP.NET` Instrumentierung finden Sie unter[Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)](#tracing-incoming-requests-dotnet). Informationen zur Verwendung OpenTelemetry mit anderen Frameworks finden Sie unter [Registry](https://opentelemetry.io/ecosystem/registry/) für weitere Bibliotheken für unterstützte Frameworks.
Es wird empfohlen, die folgenden Komponenten zu konfigurieren:
+ `An OTLP Exporter`— Erforderlich für den Export von Traces zum CloudWatch Agent/Collector OpenTelemetry
+ Ein AWS X-Ray Propagator — Erforderlich für die Weitergabe des Trace-Kontextes an [AWS Dienste, die in X-Ray integriert sind](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html)
+ Ein AWS Röntgen-Remote-Sampler — Erforderlich, wenn Sie [Anfragen anhand von Röntgenprobenahmeregeln beproben](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) müssen
+ `Resource Detectors`(zum Beispiel Amazon EC2 Resource Detector) — Um Metadaten des Hosts zu erkennen, auf dem Ihre Anwendung ausgeführt wird
```
using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Sampler.AWS;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
var builder = WebApplication.CreateBuilder(args);
var serviceName = "MyServiceName";
var serviceVersion = "1.0.0";
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService(serviceName: serviceName)
.AddAWSEC2Detector();
builder.Services.AddOpenTelemetry()
.ConfigureResource(resource => resource
.AddAWSEC2Detector()
.AddService(
serviceName: serviceName,
serviceVersion: serviceVersion))
.WithTracing(tracing => tracing
.AddSource(serviceName)
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()
.SetSampler(AWSXRayRemoteSampler.Builder(resourceBuilder.Build())
.SetEndpoint("http://localhost:2000")
.Build()));
Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure X-Ray propagator
```
Um sie OpenTelemetry für eine Konsolen-App zu verwenden, fügen Sie beim Start Ihres Programms die folgende OpenTelemetry Konfiguration hinzu.
```
using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
var serviceName = "MyServiceName";
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService(serviceName: serviceName)
.AddAWSEC2Detector();
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(serviceName)
.ConfigureResource(resource =>
resource
.AddAWSEC2Detector()
.AddService(
serviceName: serviceName,
serviceVersion: serviceVersion
)
)
.AddOtlpExporter() // default address localhost:4317
.SetSampler(new TraceIdRatioBasedSampler(1.00))
.Build();
Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure X-Ray propagator
```
------
## Manuelles Erstellen von Trace-Daten
------
#### [ With X-Ray SDK ]
Mit dem X-Ray-SDK waren die `BeginSubsegment` Methoden `BeginSegment` und erforderlich, um X-Ray-Segmente und -Untersegmente manuell zu erstellen.
```
using Amazon.XRay.Recorder.Core;
AWSXRayRecorder.Instance.BeginSegment("segment name"); // generates `TraceId` for you
try
{
// Do something here
// can create custom subsegments
AWSXRayRecorder.Instance.BeginSubsegment("subsegment name");
try
{
DoSometing();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSegment();
}
```
------
#### [ With OpenTelemetry SDK ]
In.NET können Sie die Aktivitäts-API verwenden, um benutzerdefinierte Spans zu erstellen, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Subsegmente umgewandelt.
Sie können so viele `ActivitySource` Instanzen wie nötig erstellen, es wird jedoch empfohlen, nur eine für eine gesamte Anwendung/einen Dienst zu verwenden.
```
using System.Diagnostics;
ActivitySource activitySource = new ActivitySource("ActivitySourceName", "ActivitySourceVersion");
...
using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment
{
// Do something here
using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment
{
// Do something here
}
}
```
**Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry **
Sie können Ihren Spans auch benutzerdefinierte Schlüssel-Wert-Paare als Attribute hinzufügen, indem Sie die `SetTag` Methode für eine Aktivität verwenden. Beachten Sie, dass standardmäßig alle Span-Attribute in X-Rohdaten in Metadaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, können Sie den Schlüssel dieses Attributs zur `aws.xray.annotations` Attributliste hinzufügen.
```
using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment
{
activity.SetTag("metadataKey", "metadataValue");
activity.SetTag("annotationKey", "annotationValue");
string[] annotationKeys = {"annotationKey"};
activity.SetTag("aws.xray.annotations", annotationKeys);
// Do something here
using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment
{
// Do something here
}
}
```
**Mit OpenTelemetry automatischer Instrumentierung**
Wenn Sie eine OpenTelemetry automatische Instrumentierungslösung für .NET verwenden und in Ihrer Anwendung eine manuelle Instrumentierung durchführen müssen, um beispielsweise Code innerhalb der Anwendung selbst für Abschnitte zu instrumentieren, die von keiner Bibliothek für automatische Instrumentierung abgedeckt werden.
Da es nur eine globale Instrumentierung geben kann`TracerProvider`, sollte die manuelle Instrumentierung nicht ihre eigene instanziieren, `TracerProvider` wenn sie zusammen mit der automatischen Instrumentierung verwendet wird. Wenn diese `TracerProvider` Option verwendet wird, funktioniert die benutzerdefinierte manuelle Ablaufverfolgung genauso, wenn automatische Instrumentierung oder manuelle Instrumentierung über das SDK verwendet wird. OpenTelemetry
------
## Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)
------
#### [ With X-Ray SDK ]
Informationen zum Instrumentieren von Anfragen, die von der ASP.NET-Anwendung bedient werden, finden Sie unter[https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html), wie Sie die `Init` Methode Ihrer Datei aufrufen`RegisterXRay`. `global.asax`
```
AWSXRayASPNET.RegisterXRay(this, "MyApp");
```
Um Anfragen zu instrumentieren, die von Ihrer ASP.NET-Kernanwendung bedient werden, wird die `UseXRay` Methode vor jeder anderen Middleware in der `Configure` Methode Ihrer Startup-Klasse aufgerufen.
```
app.UseXRay("MyApp");
```
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry stellt außerdem Instrumentierungsbibliotheken zur Erfassung von Traces für eingehende Webanfragen für ASP.NET und ASP.NET Core bereit. Im folgenden Abschnitt werden die Schritte aufgeführt, die erforderlich sind, um diese Bibliotheksinstrumentierungen für Ihre OpenTelemetry Konfiguration hinzuzufügen und zu aktivieren. Dazu gehört auch, wie Sie beim Erstellen des Tracer-Anbieters [ASP.NET](https://learn.microsoft.com/en-us/aspnet/overview) - oder [ASP.NET-Kerninstrumentierung](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0) hinzufügen.
Für Informationen zur Aktivierung von .Instrumentation. OpenTelemetry AspNet, siehe [Schritte zur Aktivierung von OpenTelemetry .Instrumentation. AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)und für Informationen zur Aktivierung von OpenTelemetry .Instrumentation. AspNetCore, siehe [Schritte zur Aktivierung von OpenTelemetry .Instrumentation. AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore).
------
## AWS SDK-Instrumentierung
------
#### [ With X-Ray SDK ]
Installieren Sie alle AWS SDK-Clients, indem Sie anrufen`RegisterXRayForAllServices()`.
```
using Amazon.XRay.Recorder.Handlers.AwsSdk;
AWSSDKHandler.RegisterXRayForAllServices(); //place this before any instantiation of AmazonServiceClient
AmazonDynamoDBClient client = new AmazonDynamoDBClient(RegionEndpoint.USWest2); // AmazonDynamoDBClient is automatically registered with X-Ray
```
Verwenden Sie eine der folgenden Methoden für eine spezifische AWS Service-Client-Instrumentierung.
```
AWSSDKHandler.RegisterXRay(); // Registers specific type of AmazonServiceClient : All instances of IAmazonDynamoDB created after this line are registered
AWSSDKHandler.RegisterXRayManifest(String path); // To configure custom AWS Service Manifest file. This is optional, if you have followed "Configuration" section
```
------
#### [ With OpenTelemetry SDK ]
Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit:
```
dotnet add package OpenTelemetry.Instrumentation.AWS
```
Um das AWS SDK zu instrumentieren, aktualisieren Sie die OpenTelemetry SDK-Konfiguration, in der Global eingerichtet TracerProvider ist.
```
builder.Services.AddOpenTelemetry()
...
.WithTracing(tracing => tracing
.AddAWSInstrumentation()
...
```
------
## Instrumentieren von ausgehenden HTTP-Aufrufen
------
#### [ With X-Ray SDK ]
Das X-Ray.NET-SDK verfolgt ausgehende HTTP-Aufrufe über die Erweiterungsmethoden `GetResponseTraced()` oder `GetAsyncResponseTraced()` bei der Verwendung `System.Net.HttpWebRequest` oder mithilfe des `HttpClientXRayTracingHandler` Handlers bei der Verwendung`System.Net.Http.HttpClient`.
------
#### [ With OpenTelemetry SDK ]
Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit:
```
dotnet add package OpenTelemetry.Instrumentation.Http
```
Um die OpenTelemetry SDK-Konfiguration zu instrumentieren `System.Net.Http.HttpClient` und `System.Net.HttpWebRequest` zu aktualisieren, in der Global eingerichtet TracerProvider ist.
```
builder.Services.AddOpenTelemetry()
...
.WithTracing(tracing => tracing
.AddHttpClientInstrumentation()
...
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Sie können die OpenTelemetry Registry nach .NET-Instrumentierungsbibliotheken durchsuchen und filtern, um herauszufinden, ob OpenTelemetry die Instrumentierung für Ihre Bibliothek unterstützt wird. Suchen Sie in der [Registry](https://opentelemetry.io/ecosystem/registry/) nach, um mit der Suche zu beginnen.
## Lambda-Instrumentierung
------
#### [ With X-Ray SDK ]
Das folgende Verfahren war erforderlich, um das X-Ray SDK mit Lambda zu verwenden:
1. Aktivieren Sie *Active Tracing für* Ihre Lambda-Funktion
1. Der Lambda-Dienst erstellt ein Segment, das den Aufruf Ihres Handlers darstellt.
1. Erstellen Sie Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK
------
#### [ With OpenTelemetry-based solutions ]
Sie können Ihr Lambda automatisch mit verkauften AWS Lambda-Layern instrumentieren. Es gibt zwei Lösungen:
+ (Empfohlen) [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) für OpenTelemetry
+ Um eine bessere Leistung zu erzielen, sollten Sie die Verwendung `OpenTelemetry Manual Instrumentation` zur Generierung von OpenTelemetry Traces für Ihre Lambda-Funktion in Betracht ziehen.
------
**OpenTelemetry manuelle Instrumentierung für AWS Lambda**
Im Folgenden finden Sie ein Beispiel für einen Lambda-Funktionscode (ohne Instrumentierung).
```
using System;
using System.Text;
using System.Threading.Tasks;
using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;
// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace ExampleLambda;
public class ListBucketsHandler
{
private static readonly AmazonS3Client s3Client = new();
// new Lambda function handler passed in
public async Task HandleRequest(object input, ILambdaContext context)
{
try
{
var DoListBucketsAsyncResponse = await DoListBucketsAsync();
context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}");
context.Logger.LogInformation($"Successfully called ListBucketsAsync");
return "Success!";
}
catch (Exception ex)
{
context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}");
throw;
}
}
private async Task DoListBucketsAsync()
{
try
{
var putRequest = new ListBucketsRequest
{
};
var response = await s3Client.ListBucketsAsync(putRequest);
return response;
}
catch (AmazonS3Exception ex)
{
throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex);
}
}
}
```
Gehen Sie wie folgt vor, um Ihren Lambda-Handler und den Amazon S3 S3-Client manuell zu instrumentieren.
1. Instanziieren Sie a TracerProvider — TracerProvider Es wird empfohlen, das mit einem`XrayUdpSpanExporter`, einem ParentBased Always On Sampler und a `Resource` zu konfigurieren, das auf den Namen der `service.name` Lambda-Funktion gesetzt ist.
1. Instrumentieren Sie den Amazon S3 S3-Client mit der OpenTemetry AWS SDK-Instrumentierung, indem Sie aufrufen`AddAWSInstrumentation()`, um die AWS SDK-Client-Instrumentierung hinzuzufügen `TracerProvider`
1. Erstellen Sie eine Wrapper-Funktion mit derselben Signatur wie die ursprüngliche Lambda-Funktion. Rufen Sie `AWSLambdaWrapper.Trace()` API auf und übergeben `TracerProvider` Sie die ursprüngliche Lambda-Funktion und ihre Eingaben als Parameter. Stellen Sie die Wrapper-Funktion als Lambda-Handler-Eingabe ein.
Für das folgende Codebeispiel benötigen Sie die folgenden Abhängigkeiten:
```
dotnet add package OpenTelemetry.Instrumentation.AWSLambda
dotnet add package OpenTelemetry.Instrumentation.AWS
dotnet add package OpenTelemetry.Resources.AWS
dotnet add package AWS.Distro.OpenTelemetry.Exporter.Xray.Udp
```
Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen.
```
using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;
using OpenTelemetry;
using OpenTelemetry.Instrumentation.AWSLambda;
using OpenTelemetry.Trace;
using AWS.Distro.OpenTelemetry.Exporter.Xray.Udp;
using OpenTelemetry.Resources;
// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace ExampleLambda;
public class ListBucketsHandler
{
private static readonly AmazonS3Client s3Client = new();
TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddAWSLambdaConfigurations()
.AddProcessor(
new SimpleActivityExportProcessor(
// AWS_LAMBDA_FUNCTION_NAME Environment Variable will be defined in AWS Lambda Environment
new XrayUdpExporter(ResourceBuilder.CreateDefault().AddService(Environment.GetEnvironmentVariable("AWS_LAMBDA_FUNCTION_NAME")).Build())
)
)
.AddAWSInstrumentation()
.SetSampler(new ParentBasedSampler(new AlwaysOnSampler()))
.Build();
// new Lambda function handler passed in
public async Task HandleRequest(object input, ILambdaContext context)
=> await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context);
public async Task OriginalHandleRequest(object input, ILambdaContext context)
{
try
{
var DoListBucketsAsyncResponse = await DoListBucketsAsync();
context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}");
context.Logger.LogInformation($"Successfully called ListBucketsAsync");
return "Success!";
}
catch (Exception ex)
{
context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}");
throw;
}
}
private async Task DoListBucketsAsync()
{
try
{
var putRequest = new ListBucketsRequest
{
};
var response = await s3Client.ListBucketsAsync(putRequest);
return response;
}
catch (AmazonS3Exception ex)
{
throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex);
}
}
}
```
Wenn Sie dieses Lambda aufrufen, sehen Sie den folgenden Trace in der Trace Map in der CloudWatch Konsole:
![\[Trace-Map in der CloudWatch Konsole für .Net\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/deprecation_dotnet.png)
# Zu OpenTelemetry Python migrieren
Dieses Handbuch hilft Ihnen bei der Migration von Python-Anwendungen vom X-Ray SDK zur OpenTelemetry Instrumentierung. Es behandelt sowohl automatische als auch manuelle Instrumentierungsansätze mit Codebeispielen für gängige Szenarien.
**Topics**
+ [Automatische Instrumentierungslösungen ohne Code](#zero-code-python)
+ [Instrumentieren Sie Ihre Anwendungen manuell](#manual-instrumentation-python)
+ [Initialisierung des Tracing-Setups](#manual-instrumentation-python-tracing)
+ [Nachverfolgung eingehender Anfragen](#tracing-incoming-requests-python)
+ [AWS SDK-Instrumentierung](#aws-sdk-instrumentation-python)
+ [Instrumentierung ausgehender HTTP-Aufrufe über Anfragen](#http-instrumentation-python)
+ [Instrumentierungsunterstützung für andere Bibliotheken](#xray-migration-libraries-python)
+ [Manuelles Erstellen von Trace-Daten](#manual-trace-creation-python)
+ [Lambda-Instrumentierung](#lambda-instrumentation-python)
## Automatische Instrumentierungslösungen ohne Code
Mit X-Ray SDK mussten Sie Ihren Anwendungscode ändern, um Anfragen zu verfolgen. OpenTelemetry bietet automatische Instrumentierungslösungen ohne Code zur Rückverfolgung von Anfragen. Mit haben Sie die Möglichkeit OpenTelemetry, automatische Instrumentierungslösungen ohne Code zu verwenden, um Anfragen zu verfolgen.
**Nullcode mit basierten automatischen Instrumentierungen OpenTelemetry**
1. Verwenden der automatischen Instrumentierung von AWS Distro for OpenTelemetry (ADOT) für Python — Informationen zur automatischen Instrumentierung für Python-Anwendungen finden Sie unter [Tracing and Metrics with the AWS Distro](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) for Python Auto-Instrumentation. OpenTelemetry
(Optional) Sie können CloudWatch Application Signals auch bei der automatischen Instrumentierung Ihrer Anwendungen AWS mit der automatischen ADOT-Python-Instrumentierung aktivieren, um den aktuellen Anwendungsstatus zu überwachen und die langfristige Anwendungsleistung anhand Ihrer Geschäftsziele zu verfolgen. Application Signals bietet Ihnen einen einheitlichen, anwendungsorientierten Überblick über Ihre Anwendungen, Services und Abhängigkeiten und unterstützt Sie bei der Überwachung und Diagnose des Zustands Ihrer Anwendungen.
1. Verwendung der automatischen OpenTelemetry Python-Zero-Code-Instrumentierung — Informationen zur automatischen Instrumentierung mit OpenTelemetry [Python finden Sie unter Python-Zero-Code-Instrumentierung](https://opentelemetry.io/docs/zero-code/python/).
## Instrumentieren Sie Ihre Anwendungen manuell
Sie können Ihre Anwendungen mithilfe des `pip` Befehls manuell instrumentieren.
------
#### [ With X-Ray SDK ]
```
pip install aws-xray-sdk
```
------
#### [ With OpenTelemetry SDK ]
```
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-aws-xray
```
------
## Initialisierung des Tracing-Setups
------
#### [ With X-Ray SDK ]
In X-Ray `xray_recorder` wird das Global initialisiert und zur Generierung von Segmenten und Untersegmenten verwendet.
------
#### [ With OpenTelemetry SDK ]
**Anmerkung**
X-Ray Remote Sampling kann derzeit nicht für OpenTelemetry Python konfiguriert werden. Unterstützung für X-Ray Remote Sampling ist derzeit jedoch über die ADOT Auto-Instrumentation for Python verfügbar.
In OpenTelemetry müssen Sie eine globale initialisieren. `TracerProvider` Auf diese Weise können Sie einen [Tracer](https://opentelemetry.io/docs/concepts/signals/traces/#tracer) erwerben`TracerProvider`, mit dem Sie Spans an einer beliebigen Stelle in Ihrer Anwendung generieren können. Es wird empfohlen, die folgenden Komponenten zu konfigurieren:
+ `OTLPSpanExporter`— Erforderlich für den Export von Traces zum CloudWatch Agent/Collector OpenTelemetry
+ Ein AWS X-Ray Propagator — Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind
```
from opentelemetry import (
trace,
propagate
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.propagators.aws import AwsXRayPropagator
# Sends generated traces in the OTLP format to an OTel Collector running on port 4318
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
# Processes traces in batches as opposed to immediately one after the other
span_processor = BatchSpanProcessor(otlp_exporter)
# More configurations can be done here. We will visit them later.
# Sets the global default tracer provider
provider = TracerProvider(active_span_processor=span_processor)
trace.set_tracer_provider(provider)
# Configures the global propagator to use the X-Ray Propagator
propagate.set_global_textmap(AwsXRayPropagator())
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Use this tracer to create Spans
```
------
**Mit ADOT Auto-Instrumentation für Python**
Sie können die automatische ADOT-Instrumentierung für Python verwenden, um Ihre Python-Anwendungen automatisch zu konfigurieren OpenTelemetry . Durch die automatische ADOT-Instrumentierung müssen Sie keine manuellen Codeänderungen vornehmen, um eingehende Anfragen zu verfolgen oder Bibliotheken wie das AWS SDK oder die HTTP-Clients zu verfolgen. Weitere Informationen finden Sie unter [Tracing and Metrics with the AWS Distro for OpenTelemetry Python](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) Auto-Instrumentation.
Die automatische ADOT-Instrumentierung für Python unterstützt:
+ Röntgenfernabtastung durch die Umgebungsvariable `export OTEL_TRACES_SAMPLER=xray`
+ Übertragung des X-Ray-Trace-Kontextes (standardmäßig aktiviert)
+ Ressourcenerkennung (Ressourcenerkennung für Amazon EC2-, Amazon ECS- und Amazon EKS-Umgebungen ist standardmäßig aktiviert)
+ Automatische Bibliotheksinstrumentierungen für alle unterstützten OpenTelemetry Instrumentierungen sind standardmäßig aktiviert. Sie können sie selektiv über die `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS ` Umgebungsvariable deaktivieren. (alle sind standardmäßig aktiviert)
+ Manuelles Erstellen von Spans
**Von X-Ray-Service-Plug-ins bis hin zu OpenTelemetry AWS Ressourcenanbietern**
Das X-Ray-SDK bietet Plug-ins, die Sie hinzufügen können`xray_recorder`, um plattformspezifische Informationen aus dem gehosteten Service wie Amazon EC2, Amazon ECS und Elastic Beanstalk zu erfassen. Es ist den Resource Providers insofern ähnlich, als es OpenTelemetry die Informationen als Ressourcenattribute erfasst. Es sind mehrere Ressourcenanbieter für verschiedene AWS Plattformen verfügbar.
+ Beginnen Sie mit der Installation des AWS Erweiterungspakets, `pip install opentelemetry-sdk-extension-aws`
+ Konfigurieren Sie den gewünschten Ressourcendetektor. Das folgende Beispiel zeigt, wie der Amazon EC2 EC2-Ressourcenanbieter im OpenTelemetry SDK konfiguriert wird
```
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.extension.aws.resource.ec2 import (
AwsEc2ResourceDetector,
)
from opentelemetry.sdk.resources import get_aggregated_resources
provider = TracerProvider(
active_span_processor=span_processor,
resource=get_aggregated_resources([
AwsEc2ResourceDetector(),
]))
trace.set_tracer_provider(provider)
```
## Nachverfolgung eingehender Anfragen
------
#### [ With X-Ray SDK ]
Das X-Ray-Python-SDK unterstützt Anwendungsframeworks wie Django, Flask und Bottle bei der Verfolgung der eingehenden Anfragen für Python-Anwendungen, die auf ihnen ausgeführt werden. Dies erfolgt, indem der Anwendung für `XRayMiddleware` jedes Framework etwas hinzugefügt wird.
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry stellt Instrumentierungen für [Django](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html) und [Flask](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html) über die spezifischen Instrumentierungsbibliotheken bereit. [In ist keine Instrumentierung für Bottle verfügbar OpenTelemetry, Anwendungen können dennoch mithilfe der WSGI-Instrumentation verfolgt werden. OpenTelemetry ](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/wsgi/wsgi.html)
Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit:
```
pip install opentelemetry-instrumentation-flask
```
Sie müssen das SDK initialisieren und das globale OpenTelemetry SDK registrieren, TracerProvider bevor Sie Instrumentierungen für Ihr Anwendungsframework hinzufügen können. Ohne sie werden die Trace-Operationen funktionieren. `no-ops` Sobald Sie den Global konfiguriert haben`TracerProvider`, können Sie den Instrumentor für Ihr Anwendungsframework verwenden. Das folgende Beispiel demonstriert eine Flask-Anwendung.
```
from flask import Flask
from opentelemetry import trace
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.sdk.extension.aws.resource import AwsEc2ResourceDetector
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
provider = TracerProvider(resource=get_aggregated_resources(
[
AwsEc2ResourceDetector(),
]))
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
app = Flask(__name__)
# Instrument the Flask app
FlaskInstrumentor().instrument_app(app)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
app.run()
```
------
## AWS SDK-Instrumentierung
------
#### [ With X-Ray SDK ]
Das X-Ray-Python-SDK verfolgt die AWS SDK-Client-Anfrage, indem es die `botocore` Bibliothek patcht. Weitere Informationen finden Sie unter [Nachverfolgen von AWS SDK-Aufrufen mit dem X-Ray-SDK für Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-awssdkclients.html). In Ihrer Anwendung wird die `patch_all()` Methode verwendet, um alle Bibliotheken zu instrumentieren oder selektiv mithilfe von `boto3` Bibliotheken zu patchen. `botocore` `patch((['botocore']))` Jede der ausgewählten Methoden instrumentiert alle Boto3-Clients in Ihrer Anwendung und generiert ein Untersegment für jeden Aufruf, der mit diesen Clients getätigt wird.
------
#### [ With OpenTelemetry SDK ]
Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit:
```
pip install opentelemetry-instrumentation-botocore
```
Verwenden Sie die [OpenTelemetry Botocore-Instrumentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/botocore/botocore.html) programmgesteuert, um alle Boto3-Clients in Ihrer Anwendung zu instrumentieren. Das folgende Beispiel demonstriert die Instrumentierung. `botocore`
```
import boto3
import opentelemetry.trace as trace
from botocore.exceptions import ClientError
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace.export import (
BatchSpanProcessor,
ConsoleSpanExporter,
)
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Instrument BotoCore
BotocoreInstrumentor().instrument()
# Initialize S3 client
s3 = boto3.client("s3", region_name="us-east-1")
# Your bucket name
bucket_name = "my-example-bucket"
# Get bucket location (as an example of describing it)
try:
response = s3.get_bucket_location(Bucket=bucket_name)
region = response.get("LocationConstraint") or "us-east-1"
print(f"Bucket '{bucket_name}' is in region: {region}")
# Optionally, get bucket's creation date via list_buckets
buckets = s3.list_buckets()
for bucket in buckets["Buckets"]:
if bucket["Name"] == bucket_name:
print(f"Bucket created on: {bucket['CreationDate']}")
break
except ClientError as e:
print(f"Failed to describe bucket: {e}")
```
------
## Instrumentierung ausgehender HTTP-Aufrufe über Anfragen
------
#### [ With X-Ray SDK ]
Das X-Ray-Python-SDK verfolgt ausgehende HTTP-Aufrufe anhand von Anfragen, indem es die Anforderungsbibliothek patcht. Weitere Informationen finden Sie unter Verfolgen [von Aufrufen von Downstream-HTTP-Webdiensten mithilfe des X-Ray-SDK für Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-httpclients.html). In Ihrer Anwendung können Sie die `patch_all()` Methode verwenden, um alle Bibliotheken zu instrumentieren, oder indem Sie die Anforderungsbibliotheken selektiv patchen, indem Sie `patch((['requests']))` Jede der Optionen instrumentiert die `requests` Bibliothek und generiert ein Untersegment für jeden Aufruf, der über sie erfolgt. `requests`
------
#### [ With OpenTelemetry SDK ]
Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit:
```
pip install opentelemetry-instrumentation-requests
```
Verwenden Sie die OpenTelemetry Requests Instrumentation programmgesteuert, um die Anforderungsbibliothek so zu instrumentieren, dass sie Traces für HTTP-Anfragen generiert, die von ihr in Ihrer Anwendung gestellt werden. Weitere Informationen finden Sie unter Instrumentation von [OpenTelemetry Anfragen](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html). Das folgende Beispiel zeigt die Instrumentierung der `requests` Bibliothek.
```
from opentelemetry.instrumentation.requests import RequestsInstrumentor
# Instrument Requests
RequestsInstrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
Alternativ können Sie die zugrunde liegende `urllib3` Bibliothek auch instrumentieren, um HTTP-Anfragen zu verfolgen:
```
# pip install opentelemetry-instrumentation-urllib3
from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
# Instrument urllib3
URLLib3Instrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Die vollständige Liste der unterstützten Bibliotheksinstrumentationen für OpenTelemetry Python finden Sie unter [Unterstützte Bibliotheken, Frameworks, Anwendungsserver und JVMs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).
Alternativ können Sie in der OpenTelemetry Registry suchen, um herauszufinden, ob Instrumentierung OpenTelemetry unterstützt wird. Suchen Sie in der [Registry](https://opentelemetry.io/ecosystem/registry/) nach, um mit der Suche zu beginnen.
## Manuelles Erstellen von Trace-Daten
Sie können Segmente und Untersegmente mithilfe von `xray_recorder` in Ihrer Python-Anwendung erstellen. Weitere Informationen finden Sie unter [Manuelles Instrumentieren von Python-Code](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-middleware.html#xray-sdk-python-middleware-manual). Sie können den Trace-Daten auch manuell Anmerkungen und Metadaten hinzufügen.
**Spans mit SDK erstellen OpenTelemetry **
Verwenden Sie die `start_as_current_span` API, um einen Bereich zu starten und ihn für die Erstellung von Spans festzulegen. Beispiele zum Erstellen von Spans finden Sie unter Spans [erstellen](https://opentelemetry.io/docs/languages/python/instrumentation/#creating-spans). Sobald ein Bereich gestartet wurde und sich im aktuellen Bereich befindet, können Sie ihm weitere Informationen hinzufügen, indem Sie Attribute, Ereignisse, Ausnahmen, Links usw. hinzufügen. So wie wir in X-Ray Segmente und Untersegmente haben, gibt es verschiedene Arten von Spannweiten. OpenTelemetry Nur die `SERVER` Typbereiche werden in Röntgensegmente umgewandelt, während andere in Röntgenuntersegmente umgewandelt werden.
```
from opentelemetry import trace
from opentelemetry.trace import SpanKind
import time
tracer = trace.get_tracer("my.tracer.name")
# Create a new span to track some work
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
time.sleep(1)
# Create a nested span to track nested work
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
time.sleep(2)
# the nested span is closed when it's out of scope
# Now the parent span is the current span again
time.sleep(1)
# This span is also closed when it goes out of scope
```
**Hinzufügen von Anmerkungen und Metadaten zu Traces mit SDK OpenTelemetry **
Das X-Ray-Python-SDK bietet separate APIs `put_metadata` Funktionen zum Hinzufügen von Anmerkungen und Metadaten zu einem Trace. `put_annotation` Im OpenTelemetry SDK sind die Anmerkungen und Metadaten einfach Attribute in einem Bereich, die über die `set_attribute` API hinzugefügt werden.
Span-Attribute, bei denen es sich um Anmerkungen zu einem Trace handeln soll, werden unter dem reservierten Schlüssel hinzugefügt, `aws.xray.annotations` dessen Wert eine Liste von Schlüssel-Wert-Annotationspaaren ist. Alle anderen Span-Attribute werden zu Metadaten für das konvertierte Segment oder Untersegment.
Wenn Sie den ADOT-Collector verwenden, können Sie außerdem konfigurieren, welche Span-Attribute in X-Ray-Anmerkungen konvertiert werden sollen, indem Sie das `indexed_attributes` in der Collector-Konfiguration angeben.
Das folgende Beispiel zeigt, wie Sie mithilfe des SDK Anmerkungen und Metadaten zu einer Ablaufverfolgung hinzufügen. OpenTelemetry
```
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
parent_span.set_attribute("TransactionId", "qwerty12345")
parent_span.set_attribute("AccountId", "1234567890")
# This will convert the TransactionId and AccountId to be searchable X-Ray annotations
parent_span.set_attribute("aws.xray.annotations", ["TransactionId", "AccountId"])
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
# The MicroTransactionId will be converted to X-Ray metadata for the child subsegment
child_span.set_attribute("MicroTransactionId", "micro12345")
```
## Lambda-Instrumentierung
Um Ihre Lambda-Funktionen auf X-Ray zu überwachen, aktivieren Sie X-Ray und fügen der Funktionsaufrufrolle entsprechende Berechtigungen hinzu. Wenn Sie Downstream-Anfragen von Ihrer Funktion verfolgen, würden Sie den Code außerdem mit dem X-Ray-Python-SDK instrumentieren.
OpenTelemetry Für X-Ray wird empfohlen, den AWS Lambda-Layer OpenTelemetry bei ausgeschalteten [Anwendungssignalen](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) zu verwenden. Dadurch wird Ihre Funktion automatisch instrumentiert und Spans für den Funktionsaufruf und alle nachgelagerten Anfragen Ihrer Funktion generiert. Wenn Sie neben der Ablaufverfolgung auch Anwendungssignale verwenden möchten, um den Zustand Ihrer Funktion zu überwachen, finden Sie weitere Informationen unter [Aktivieren Ihrer Anwendungen auf Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ Suchen Sie den erforderlichen Lambda-Layer-ARN für Ihre Funktion aus [AWS Lambda Layer for OpenTelemetry ARNs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html#Enable-Lambda-Layers) und fügen Sie ihn hinzu.
+ Stellen Sie die folgenden Umgebungsvariablen für Ihre Funktion ein.
+ `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`— Dadurch wird die automatische Instrumentierung für die Funktion geladen
+ `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`— Dadurch wird die Überwachung von Anwendungssignalen deaktiviert
**Manuelles Erstellen von Spans mit Lambda-Instrumentierung**
Darüber hinaus können Sie innerhalb Ihrer Funktion benutzerdefinierte Zeitspannen generieren, um die Arbeit zu verfolgen. Sie können dies tun, indem Sie nur das `opentelemetry-api` Paket in Verbindung mit dem AWS Lambda-Layer für die OpenTelemetry automatische Instrumentierung verwenden.
1. Fügen Sie das `opentelemetry-api` als Abhängigkeit in Ihre Funktion ein
1. Der folgende Codeausschnitt ist ein Beispiel für die Generierung benutzerdefinierter Spans
```
from opentelemetry import trace
# Get the tracer (auto‑configured by the AWS Lambda Layer for OpenTelemetry)
tracer = trace.get_tracer(__name__)
def handler(event, context):
# This span is a child of the layer's root span
with tracer.start_as_current_span("my-custom-span") as span:
span.set_attribute("key1", "value1")
span.add_event("custom-event", {"detail": "something happened"})
# Any logic you want to trace
result = some_internal_logic()
return {
"statusCode": 200,
"body": result
}
```
# Migrieren Sie zu Ruby OpenTelemetry
Verwenden Sie die folgenden Codebeispiele und Anleitungen für die manuelle OpenTelemetry Instrumentierung, um Ihre Ruby-Anwendungen vom X-Ray SDK zur Instrumentierung zu migrieren.
**Topics**
+ [Instrumentieren Sie Ihre Lösungen manuell mit dem SDK](#manual-instrumentation-ruby)
+ [Nachverfolgung eingehender Anfragen (Rails-Instrumentierung)](#tracing-incoming-requests-ruby)
+ [AWS SDK-Instrumentierung](#aws-sdk-instrumentation-ruby)
+ [Instrumentieren von ausgehenden HTTP-Aufrufen](#http-instrumentation-ruby)
+ [Instrumentierungsunterstützung für andere Bibliotheken](#xray-migration-libraries-ruby)
+ [Manuelles Erstellen von Trace-Daten](#manual-trace-creation-ruby)
+ [Manuelle Lambda-Instrumentierung](#lambda-instrumentation-ruby)
## Instrumentieren Sie Ihre Lösungen manuell mit dem SDK
------
#### [ Tracing setup with X-Ray SDK ]
X-Ray X-Ray-SDK SDK for Ruby mussten Sie Ihren Code mit Service-Plug-ins konfigurieren.
```
require 'aws-xray-sdk'
XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk])
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
**Anmerkung**
X-Ray Remote Sampling kann derzeit nicht für OpenTelemetry Ruby konfiguriert werden.
Platzieren Sie für eine Ruby on Rails-Anwendung Ihren Konfigurationscode in einem Rails-Initialisierer. Weitere Informationen finden Sie unter [Erste Schritte mit ](https://opentelemetry.io/docs/languages/ruby/getting-started/#initialization). Für alle manuell instrumentierten Ruby-Programme müssen Sie die `OpenTelemetry::SDK.configure` Methode verwenden, um das Ruby-SDK zu konfigurieren. OpenTelemetry
Installieren Sie zunächst die folgenden Pakete:
```
bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray
```
Als Nächstes konfigurieren Sie das OpenTelemetry SDK mithilfe des Konfigurationscodes, der bei der Initialisierung Ihres Programms ausgeführt wird. Es wird empfohlen, die folgenden Komponenten zu konfigurieren:
+ `OTLP Exporter`— Erforderlich für den Export von Traces an den CloudWatch Agent und den OpenTelemetry Collector
+ `An AWS X-Ray Propagator`— Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind
```
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'
# Import the gem containing the AWS X-Ray for OTel Ruby ID Generator and propagator
require 'opentelemetry-propagator-xray'
OpenTelemetry::SDK.configure do |c|
c.service_name = 'my-service-name'
c.add_span_processor(
# Use the BatchSpanProcessor to send traces in groups instead of one at a time
OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
# Use the default OLTP Exporter to send traces to the ADOT Collector
OpenTelemetry::Exporter::OTLP::Exporter.new(
# The OpenTelemetry Collector is running as a sidecar and listening on port 4318
endpoint:"http://127.0.0.1:4318/v1/traces"
)
)
)
# The X-Ray Propagator injects the X-Ray Tracing Header into downstream calls
c.propagators = [OpenTelemetry::Propagator::XRay::TextMapPropagator.new]
end
```
OpenTelemetry SDKs haben auch das Konzept der Bibliotheksinstrumentierung. Wenn Sie diese aktivieren, werden automatisch Bereiche für Bibliotheken wie das AWS SDK erstellt. OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen.
Um alle Instrumentierungen zu aktivieren, installieren Sie zuerst das Paket: `opentelemetry-instrumentation-all`
```
bundle add opentelemetry-instrumentation-all
```
Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen wie unten gezeigt zu aktivieren:
```
require 'opentelemetry/instrumentation/all'
...
OpenTelemetry::SDK.configure do |c|
...
c.use_all() # Enable all instrumentations
end
```
OpenTelemetry SDKs haben auch das Konzept der Bibliotheksinstrumentierung. Wenn Sie diese aktivieren, werden automatisch Bereiche für Bibliotheken wie das AWS SDK erstellt. OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen.
Um alle Instrumentierungen zu aktivieren, installieren Sie zuerst das Paket: `opentelemetry-instrumentation-all`
```
bundle add opentelemetry-instrumentation-all
```
Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen wie unten gezeigt zu aktivieren:
```
require 'opentelemetry/instrumentation/all'
...
OpenTelemetry::SDK.configure do |c|
...
c.use_all() # Enable all instrumentations
end
```
------
## Nachverfolgung eingehender Anfragen (Rails-Instrumentierung)
------
#### [ With X-Ray SDK ]
Mit dem X-Ray SDK wird das X-Ray-Tracing bei der Initialisierung für das Rails-Framework konfiguriert.
**Beispiel** — \$1xray.rb config/initializers/aws
```
Rails.application.config.xray = {
name: 'my app',
patch: %I[net_http aws_sdk],
active_record: true
}
```
------
#### [ With OpenTelemetry SDK ]
Installieren Sie zunächst die folgenden Pakete:
```
bundle add opentelemetry-instrumentation-rack opentelemetry-instrumentation-rails opentelemetry-instrumentation-action_pack opentelemetry-instrumentation-active_record opentelemetry-instrumentation-action_view
```
Aktualisieren Sie als Nächstes die Konfiguration, um die Instrumentierung für Ihre Rails-Anwendung zu aktivieren, wie unten gezeigt:
```
# During SDK configuration
OpenTelemetry::SDK.configure do |c|
...
c.use 'OpenTelemetry::Instrumentation::Rails'
c.use 'OpenTelemetry::Instrumentation::Rack'
c.use 'OpenTelemetry::Instrumentation::ActionPack'
c.use 'OpenTelemetry::Instrumentation::ActiveSupport'
c.use 'OpenTelemetry::Instrumentation::ActionView'
...
end
```
------
## AWS SDK-Instrumentierung
------
#### [ With X-Ray SDK ]
Um ausgehende AWS Anfragen vom AWS SDK zu instrumentieren, werden die AWS SDK-Clients wie im folgenden Beispiel mit X-Ray gepatcht:
```
require 'aws-xray-sdk'
require 'aws-sdk-s3'
# Patch AWS SDK clients
XRay.recorder.configure(plugins: [:aws_sdk])
# Use the instrumented client
s3 = Aws::S3::Client.new
s3.list_buckets
```
------
#### [ With OpenTelemetry SDK ]
AWS Das SDK for Ruby V3 bietet Unterstützung für das Aufzeichnen und Ausgeben OpenTelemetry von Spuren. Informationen zur Konfiguration OpenTelemetry für einen Service-Client finden Sie unter [Konfiguration von Observability-Funktionen im AWS SDK for Ruby](sdk-for-ruby/v3/developer-guide/observability.html).
------
## Instrumentieren von ausgehenden HTTP-Aufrufen
Wenn Sie HTTP-Aufrufe an externe Dienste tätigen, müssen Sie die Aufrufe möglicherweise manuell instrumentieren, wenn die automatische Instrumentierung nicht verfügbar ist oder nicht genügend Details liefert.
------
#### [ With X-Ray SDK ]
Um Downstream-Aufrufe zu instrumentieren, wurde das X-Ray-SDK SDK for Ruby verwendet, um die `net/http` Bibliothek zu patchen, die Ihre Anwendung verwendet:
```
require 'aws-xray-sdk'
config = {
name: 'my app',
patch: %I[net_http]
}
XRay.recorder.configure(config)
```
------
#### [ With OpenTelemetry SDK ]
Um die `net/http` Instrumentierung zu aktivieren OpenTelemetry, installieren Sie zunächst das `opentelemetry-instrumentation-net_http` Paket:
```
bundle add opentelemetry-instrumentation-net_http
```
Aktualisieren Sie als Nächstes die Konfiguration, um die `net/http` Instrumentierung wie folgt zu aktivieren:
```
OpenTelemetry::SDK.configure do |c|
...
c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
...
end
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Die vollständige Liste der unterstützten Bibliotheksinstrumentationen für OpenTelemetry Ruby finden Sie unter [opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation).
Alternativ können Sie in der OpenTelemetry Registry suchen, um herauszufinden, ob Instrumentierung OpenTelemetry unterstützt wird. Weitere Informationen finden Sie unter [Registrierung](https://opentelemetry.io/ecosystem/registry/).
## Manuelles Erstellen von Trace-Daten
------
#### [ With X-Ray SDK ]
Mit X-Ray mussten Sie für das `aws-xray-sdk` Paket manuell Segmente und deren untergeordnete Untersegmente erstellen, um Ihre Anwendung zu verfolgen. Möglicherweise haben Sie Ihren Segmenten oder Untersegmenten auch X-Ray-Anmerkungen und -Metadaten hinzugefügt:
```
require 'aws-xray-sdk'
...
# Start a segment
segment = XRay.recorder.begin_segment('my-service')
# Add annotations (indexed key-value pairs)
segment.annotations[:user_id] = 'user-123'
segment.annotations[:payment_status] = 'completed'
# Add metadata (non-indexed data)
segment.metadata[:order] = {
id: 'order-456',
items: [
{ product_id: 'prod-1', quantity: 2 },
{ product_id: 'prod-2', quantity: 1 }
],
total: 67.99
}
# Add metadata to a specific namespace
segment.metadata(namespace: 'payment') do |metadata|
metadata[:transaction_id] = 'tx-789'
metadata[:payment_method] = 'credit_card'
end
# Create a subsegment with annotations and metadata
segment.subsegment('payment-processing') do |subsegment1|
subsegment1.annotations[:payment_id] = 'pay-123'
subsegment1.metadata[:details] = { amount: 67.99, currency: 'USD' }
# Create a nested subsegment
subsegment1.subsegment('operation-2') do |subsegment2|
# Do more work...
end
end
# Close the segment
segment.close
```
------
#### [ With OpenTelemetry SDK ]
Sie können benutzerdefinierte Zeitspannen verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Untersegmente umgewandelt. Standardmäßig sind Spans. `INTERNAL`
Erstellen Sie zunächst einen Tracer, um Spans zu generieren, die Sie mit der Methode abrufen können. `OpenTelemetry.tracer_provider.tracer('')` Dadurch wird eine Tracer-Instanz bereitgestellt, die global in der Konfiguration Ihrer Anwendung registriert ist. OpenTelemetry Es ist üblich, einen einzigen Tracer für eine gesamte Anwendung zu haben. Erstellen Sie einen OpenTelemetry Tracer und verwenden Sie ihn, um Spans zu erstellen:
```
require 'opentelemetry-sdk'
...
# Get a tracer
tracer = OpenTelemetry.tracer_provider.tracer('my-application')
# Create a server span (equivalent to X-Ray segment)
tracer.in_span('my-application', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span|
# Do work...
# Create nested spans of default kind INTERNAL will become an X-Ray subsegment
tracer.in_span('operation-1') do |child_span1|
# Set attributes (equivalent to X-Ray annotations and metadata)
child_span1.set_attribute('key', 'value')
# Do more work...
tracer.in_span('operation-2') do |child_span2|
# Do more work...
end
end
end
```
**Hinzufügen von Anmerkungen und Metadaten zu Traces mit SDK OpenTelemetry **
Verwenden Sie die `set_attribute` Methode, um jedem Bereich Attribute hinzuzufügen. Beachten Sie, dass alle diese Span-Attribute standardmäßig in Metadaten in X-Rohdaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, können Sie diesen Attributschlüssel zur `aws.xray.annotations` Attributliste hinzufügen. Weitere Informationen finden Sie unter [Aktivieren der benutzerdefinierten X-Ray-Anmerkungen.](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)
```
# SERVER span will become an X-Ray segment
tracer.in_span('my-server-operation', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span|
# Your server logic here
span.set_attribute('attribute.key', 'attribute.value')
span.set_attribute("metadataKey", "metadataValue")
span.set_attribute("annotationKey1", "annotationValue")
# Create X-Ray annotations
span.set_attribute("aws.xray.annotations", ["annotationKey1"])
end
```
------
## Manuelle Lambda-Instrumentierung
------
#### [ With X-Ray SDK ]
Nachdem *Active Tracing* auf Lambda aktiviert wurde, sind keine zusätzlichen Konfigurationen erforderlich, um das X-Ray SDK zu verwenden. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie können Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellen.
------
#### [ With OpenTelemetry SDK ]
Betrachten Sie das folgende Beispiel für einen Lambda-Funktionscode (ohne Instrumentierung):
```
require 'json'
def lambda_handler(event:, context:)
# TODO implement
{ statusCode: 200, body: JSON.generate('Hello from Lambda!') }
end
```
Um Ihr Lambda manuell zu instrumentieren, müssen Sie:
1. Füge die folgenden Edelsteine für dein Lambda hinzu
```
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-propagator-xray'
gem 'aws-distro-opentelemetry-exporter-xray-udp'
gem 'opentelemetry-instrumentation-aws_lambda'
gem 'opentelemetry-propagator-xray', '~> 0.24.0' # Requires version v0.24.0 or higher
```
1. Initialisieren Sie OpenTelemetry das SDK außerhalb Ihres Lambda-Handlers. Es wird empfohlen, das OpenTelemetry SDK zu konfigurieren mit:
1. Ein einfacher Span-Prozessor mit einem X-Ray-UDP-Span-Exporter zum Senden von Traces an den UDP-X-Ray-Endpunkt von Lambda
1. Ein Röntgen-Lambda-Propagator
1. `service_name`Konfiguration, die auf den Namen der Lambda-Funktion gesetzt werden soll
1. Fügen Sie in Ihrer Lambda-Handler-Klasse die folgenden Zeilen hinzu, um Ihren Lambda-Handler zu instrumentieren:
```
class Handler
extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
...
instrument_handler :process
end
```
Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen.
```
require 'json'
require 'opentelemetry-sdk'
require 'aws/distro/opentelemetry/exporter/xray/udp'
require 'opentelemetry/propagator/xray'
require 'opentelemetry/instrumentation/aws_lambda'
# Initialize OpenTelemetry SDK outside handler
OpenTelemetry::SDK.configure do |c|
# Configure the AWS Distro for OpenTelemetry X-Ray Lambda exporter
c.add_span_processor(
OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
AWS::Distro::OpenTelemetry::Exporter::XRay::UDP::AWSXRayUDPSpanExporter.new
)
)
# Configure X-Ray Lambda propagator
c.propagators = [OpenTelemetry::Propagator::XRay.lambda_text_map_propagator]
# Set minimal resource information
c.resource = OpenTelemetry::SDK::Resources::Resource.create({
OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => ENV['AWS_LAMBDA_FUNCTION_NAME']
})
c.use 'OpenTelemetry::Instrumentation::AwsLambda'
end
module LambdaFunctions
class Handler
extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
def self.process(event:, context:)
"Hello!"
end
instrument_handler :process
end
end
```
------
Im Folgenden finden Sie ein Beispiel für eine Trace-Map einer instrumentierten Lambda-Funktion, die in Ruby geschrieben wurde.
![\[Trace-Map in der CloudWatch Konsole für Ruby.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/deprecation_ruby.png)
Sie können Lambda-Ebenen auch verwenden, um Ihr Lambda OpenTelemetry zu konfigurieren. Weitere Informationen finden Sie unter [OpenTelemetry AWS-Lambda](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_lambda#usage) Instrumentation.