Tracing für Ihre App Runner-Anwendung mit X-Ray

AWS X-Ray ist ein Dienst, der Daten über Anfragen sammelt, die Ihre Anwendung bearbeitet, und Tools bereitstellt, mit denen Sie diese Daten anzeigen, filtern und Einblicke in sie gewinnen können, um Probleme und Optimierungsmöglichkeiten zu identifizieren. Für jede verfolgte Anfrage an Ihre Anwendung können Sie detaillierte Informationen nicht nur über die Anfrage und Antwort abrufen, sondern auch über Aufrufe, die Ihre Anwendung an nachgelagerte AWS Ressourcen, Microservices, Datenbanken und HTTP-Web-APIs sendet.

X-Ray verwendet Trace-Daten aus den AWS Ressourcen, die Ihre Cloud-Anwendungen unterstützen, um ein detailliertes Service-Diagramm zu erstellen. Das Servicediagramm zeigt den Client, Ihren Frontend-Service und die Backend-Services, die Ihr Frontend-Services für die Verarbeitung von Anforderungen und Persistenzdaten aufruft. Sie können das Servicediagramms zur Ermittlung von Engpässen, Latenzspitzen und anderen Problemen verwenden, die Sie zur Verbesserung der Leistung Ihrer Anwendungen beheben können.

Weitere Informationen zu X-Ray finden Sie im Entwicklerhandbuch für AWS X-Ray.

Instrumentieren Sie Ihre Anwendung für die Rückverfolgung

Instrumentieren Sie Ihre App Runner-Dienstanwendung für die Ablaufverfolgung mithilfe OpenTelemetryeiner portablen Telemetriespezifikation. Derzeit unterstützt App Runner AWS Distro for OpenTelemetry (ADOT), eine OpenTelemetry Implementierung, die Telemetriedaten mithilfe von Diensten sammelt und präsentiert. AWS X-Ray implementiert die Tracing-Komponente.

Abhängig vom spezifischen ADOT-SDK, das Sie in Ihrer Anwendung verwenden, unterstützt ADOT bis zu zwei Instrumentierungsansätze: automatisch und manuell. Weitere Informationen zur Instrumentierung mit Ihrem SDK finden Sie in der ADOT-Dokumentation. Wählen Sie im Navigationsbereich Ihr SDK aus.

Runtime-Setup

Im Folgenden finden Sie allgemeine Anweisungen zur Runtime-Setup, mit denen Sie Ihre App Runner-Dienstanwendung für die Ablaufverfolgung instrumentieren können.

So richten Sie die Ablaufverfolgung für Ihre Laufzeit ein

1. Folgen Sie den Anweisungen für Ihre Laufzeit in AWS Distro for OpenTelemetry (ADOT), um Ihre Anwendung zu instrumentieren.

2. Installieren Sie die erforderlichen OTEL Abhängigkeiten im build Abschnitt der apprunner.yaml Datei, wenn Sie das Quellcode-Repository verwenden, oder im Dockerfile, wenn Sie ein Container-Image verwenden.

3. Richten Sie Ihre Umgebungsvariablen in der apprunner.yaml Datei ein, wenn Sie das Quellcode-Repository verwenden, oder im Dockerfile, wenn Sie ein Container-Image verwenden.

   Beispiel Umgebungsvariablen

   Anmerkung

   Das folgende Beispiel listet die wichtigen Umgebungsvariablen auf, die der apprunner.yaml Datei hinzugefügt werden sollen. Fügen Sie diese Umgebungsvariablen zu Ihrem Dockerfile hinzu, wenn Sie ein Container-Image verwenden. Jede Laufzeit kann jedoch ihre eigenen Eigenheiten haben, und Sie müssen der folgenden Liste möglicherweise weitere Umgebungsvariablen hinzufügen. Weitere Informationen zu Ihren runtime-spezifischen Anweisungen und Beispiele zur Einrichtung Ihrer Anwendung für Ihre Runtime finden Sie unter AWS Distribution for OpenTelemetry und Go to your runtime unter Getting Started.

   env:
       - name: OTEL_PROPAGATORS
         value: xray
       - name: OTEL_METRICS_EXPORTER
         value: none
       - name: OTEL_EXPORTER_OTLP_ENDPOINT
         value: http://localhost:4317  
       - name: OTEL_RESOURCE_ATTRIBUTES
         value: 'service.name=example_app'

   Anmerkung

   OTEL_METRICS_EXPORTER=noneist eine wichtige Umgebungsvariable für App Runner, da der App Runner Otel Collector keine Metrikprotokollierung akzeptiert. Er akzeptiert nur die Nachverfolgung von Metriken.

Beispiel für die Einrichtung einer Laufzeit

Das folgende Beispiel zeigt die automatische Instrumentierung Ihrer Anwendung mit dem ADOT Python SDK. Das SDK erzeugt automatisch Spans mit Telemetriedaten, die die Werte beschreiben, die von den Python-Frameworks in Ihrer Anwendung verwendet werden, ohne eine einzige Zeile Python-Code hinzuzufügen. Sie müssen nur ein paar Zeilen in zwei Quelldateien hinzufügen oder ändern.

Fügen Sie zunächst einige Abhängigkeiten hinzu, wie im folgenden Beispiel gezeigt.

Beispiel requirements.txt

opentelemetry-distro[otlp]>=0.24b0
opentelemetry-sdk-extension-aws~=2.0
opentelemetry-propagator-aws-xray~=1.0

Instrumentieren Sie dann Ihre Anwendung. Die Art und Weise, wie Sie dies tun, hängt von Ihrer Service-Quelle ab — Quellbild oder Quellcode.

Source image

Wenn es sich bei Ihrer Servicequelle um ein Image handelt, können Sie das Dockerfile, das die Erstellung Ihres Container-Images und die Ausführung der Anwendung im Image steuert, direkt instrumentieren. Das folgende Beispiel zeigt ein instrumentiertes Dockerfile für eine Python-Anwendung. Hinzufügungen zur Instrumentierung sind fett hervorgehoben.

Beispiel Dockerfile

FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install python3.7 -y && curl -O https://bootstrap.pypa.io/get-pip.py && python3 get-pip.py && yum update -y
COPY . /app
WORKDIR /app
RUN pip3 install -r requirements.txt
RUN opentelemetry-bootstrap --action=install
ENV OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=urllib3
ENV OTEL_METRICS_EXPORTER=none              
ENV OTEL_RESOURCE_ATTRIBUTES='service.name=example_app'
CMD OTEL_PROPAGATORS=xray OTEL_PYTHON_ID_GENERATOR=xray opentelemetry-instrument python3 app.py
EXPOSE 8080

Source code repository

Wenn Ihre Dienstquelle ein Repository ist, das Ihre Anwendungsquelle enthält, instrumentieren Sie Ihr Image indirekt mithilfe der Einstellungen der App Runner-Konfigurationsdatei. Diese Einstellungen steuern das Dockerfile, das App Runner generiert und verwendet, um das Image für Ihre Anwendung zu erstellen. Das folgende Beispiel zeigt eine instrumentierte App Runner-Konfigurationsdatei für eine Python-Anwendung. Hinzufügungen zur Instrumentierung sind fett hervorgehoben.

Beispiel apprunner.yaml

version: 1.0
runtime: python3 
build:
  commands:
    build:
      - pip install -r requirements.txt
      - opentelemetry-bootstrap --action=install
run: 
  command: opentelemetry-instrument python app.py
  network: 
    port: 8080 
  env:
    - name: OTEL_PROPAGATORS
      value: xray
    - name: OTEL_METRICS_EXPORTER
      value: none
    - name: OTEL_PYTHON_ID_GENERATOR
      value: xray  
    - name: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS 
      value: urllib3
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: 'service.name=example_app'

X-Ray-Berechtigungen zu Ihrer App Runner-Dienstinstanzrolle hinzufügen

Um X-Ray Tracing mit Ihrem App Runner-Dienst verwenden zu können, müssen Sie den Instanzen des Dienstes Berechtigungen für die Interaktion mit dem X-Ray-Dienst erteilen. Dazu ordnen Sie Ihrem Service eine Instanzrolle zu und fügen eine verwaltete Richtlinie mit X-Ray-Berechtigungen hinzu. Weitere Informationen zu einer App Runner-Instanzrolle finden Sie unterInstanzrolle. Fügen Sie die AWSXRayDaemonWriteAccess verwaltete Richtlinie zu Ihrer Instanzrolle hinzu und weisen Sie sie bei der Erstellung Ihrem Service zu.

X-Ray-Tracing für Ihren App Runner-Dienst aktivieren

Wenn Sie einen Dienst erstellen, deaktiviert App Runner die Ablaufverfolgung standardmäßig. Sie können X-Ray Tracing für Ihren Service als Teil der Konfiguration von Observability aktivieren. Weitere Informationen finden Sie unter Beobachtbarkeit verwalten.

Wenn Sie die App Runner-API oder die verwenden AWS CLI, enthält das TraceConfigurationObjekt innerhalb des ObservabilityConfigurationRessourcenobjekts Tracing-Einstellungen. Um die Ablaufverfolgung weiterhin zu deaktivieren, geben Sie kein TraceConfiguration Objekt an.

Stellen Sie sowohl bei der Konsole als auch bei der API sicher, dass Sie Ihre im vorherigen Abschnitt beschriebene Instanzrolle Ihrem App Runner-Dienst zuordnen.

Sehen Sie sich die X-Ray-Tracing-Daten für Ihren App Runner-Dienst an

Wählen Sie auf der Registerkarte Observability der Service-Dashboard-Seite in der App Runner-Konsole die Option Service Map anzeigen aus, um zur CloudWatch Amazon-Konsole zu navigieren.

Verwenden Sie die CloudWatch Amazon-Konsole, um Service-Maps und Traces für Anfragen anzuzeigen, die Ihre Anwendung bearbeitet. Service Maps zeigen Informationen wie die Latenz von Anfragen und Interaktionen mit anderen Anwendungen und AWS Diensten. Mit den benutzerdefinierten Anmerkungen, die Sie Ihrem Code hinzufügen, können Sie ganz einfach nach Spuren suchen. Weitere Informationen finden Sie unter Verwendung ServiceLens zur Überwachung des Zustands Ihrer Anwendungen im CloudWatch Amazon-Benutzerhandbuch.