Migration von Röntgeninstrumenten zur OpenTelemetry Instrumentierung - AWS X-Ray
Verstehen OpenTelemetry OpenTelemetry Konzepte für Migration verstehenÜberblick über die MigrationMigration von X-Ray Daemon zu AWS CloudWatch Agent oder Collector OpenTelemetry

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

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.

Themen

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.

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

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

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.

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
N/A Verarbeitung im Span
N/A Gepäck
X-Ray-Daemon OpenTelemetry Sammler
Anmerkung

Weitere Informationen zu OpenTelemetry Konzepten finden Sie in der OpenTelemetry Dokumentation.

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:

Funktion Röntgeninstrumentierung OpenTelemetry Instrumentierung
Instrumentierung der Bibliothek Unterstützt Unterstützt
Röntgenprobenahme 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 zum Filtern und Suchen 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.

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 EC2 Amazon-Instance sein, und die Ressourcenattribute, die von diesen Entitäten aufgezeichnet werden können, können den Amazon ECS-Cluster-ARN oder die EC2 Amazon-Instance-ID beinhalten.

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

  • Stichprobenahme auf Basis des Spurkennungsverhältnisses — >Stichprobenauswahl nach dem Zufallsprinzip anhand eines bestimmten Prozentsatzes der Sp

  • 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

Informationen zu OpenTelemetry Tail Sampling finden Sie unter Tail Sampling Processor

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 im X-Ray Developer Guide

  • Informationen zur OpenTelemetry Kontextweiterleitung finden Sie in der Dokumentation unter Kontext und Kontextweiterleitung OpenTelemetry

Verwendung von Bibliotheksinstrumentierung

Sowohl X-Ray als auch OpenTelemetry bieten Bibliotheksinstrumentierung, die nur minimale Codeänderungen erfordert, 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.

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 Spurendaten 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 übernimmt 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.

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

Informationen zu X-Ray-Konzepten finden Sie unter X-Ray-Konzepte 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:

  1. Ersetzen Sie die Verwendung des X-Ray-SDK durch eine OpenTelemetry Lösung

  2. Ersetzen Sie den X-Ray-Daemon durch den CloudWatch Agenten oder OpenTelemetry Collector (mit X-Ray Exporter)

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 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
Funktion X-Ray SDK OpenTelemetry
Standardkonfigurationen

  • Zentralisierte Röntgenprobenahme

  • Übertragung des X-Ray-Trace-Kon

  • Trace-Export nach X-Ray Daemon

  • Exportieren von Traces nach OpenTelemetry Collector oder CloudWatch Agent (HTTP/gRPC)

  • Weitergabe des W3C-Trace-Kontextes
Manuelle Konfigurationen

  • Lokale Probenahmeregeln

  • Plug-ins zur Ressourcenerkennung

  • X-Ray Sampling (möglicherweise nicht für alle Sprachen verfügbar)

  • Erkennung von Ressourcen

  • Übertragung des X-Ray-Trace-Kon

Ä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:

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

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

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)

Beispiel 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

So entfernen Sie den X-Ray-Daemon von Ihrer EC2 Amazon-Instance:

  1. Stoppen Sie den Daemon-Dienst:

    systemctl stop xray

  2. Löschen Sie die Konfigurationsdatei:

    rm ~/path/to/xray-daemon.yaml

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

Den Agenten konfigurieren

  1. Erstellen Sie eine Konfigurationsdatei, um die Trace-Erfassung zu aktivieren. Weitere Informationen finden Sie unter CloudWatch Agent-Konfigurationsdatei erstellen.

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

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

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

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 AWS Anmeldeinformationen mit der xray:PutTraceSegments entsprechenden Genehmigung. Weitere Informationen finden Sie unter Anmeldeinformationen angeben.

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.

  2. 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"
      }
    }
  }
}

  3. Speichern Sie die Konfiguration im Systems Manager Parameter Store:

    1. Öffnen Sie https://console.aws.amazon.com/systems-manager/

    2. Wählen Sie Parameter erstellen

    3. 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]

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

    Beispiel 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 Metriken auf EC2 Amazon-Instance-Ebene auf Amazon ECS.

Den Collector verwenden OpenTelemetry

  1. Holen Sie sich das Docker-Image otel/opentelemetry-collector-contrib von Docker Hub.

  2. Erstellen Sie eine Konfigurationsdatei otel-collector-config.yaml mit demselben Inhalt wie im Abschnitt EC2 Amazon-Konfiguration des Collectors angezeigt, aktualisieren Sie jedoch die Endpoints, die 0.0.0.0 anstelle von 127.0.0.1 verwendet werden sollen.

  3. 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]

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

    Beispiel 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

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

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