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).