Traces an Observability übertragen

Diese Anleitung erklärt, wie Sie Tracing in Ihrer Anwendung einrichten, den Export über den OpenTelemetry Collector konfigurieren und eine sichere Übertragung an die STACKIT Observability-Instanz gewährleisten.

Voraussetzungen

Bevor Sie Traces an Ihre STACKIT Observability-Instanz übertragen können, stellen Sie sicher, dass Sie Folgendes bereitstehen haben:

• Technische Zugangsdaten: Sie benötigen einen technischen <USERNAME> und ein <PASSWORD> für Ihre spezifische Instanz. Wenn Sie diese noch nicht erstellt haben, folgen Sie den Anweisungen in unserer Authentifizierungsübersicht.

In den folgenden Konfigurationsbeispielen müssen Sie <TRACING_ENDPOINT_URL> und <BASE64_ENCODED_CREDENTIALS> durch Ihre spezifischen Daten ersetzen.

Wenn Sie Hilfe beim Auffinden Ihrer Endpunkt-URLs benötigen, lesen Sie unsere Anleitung zum Auffinden der Identifiers und Endpunkt-URLs.

Der Pfad der Tracing-Daten

Traces folgen einem bestimmten Pfad von Ihrer Anwendung bis zum Tempo-Backend:

• Anwendung: Ihr Code nutzt das OpenTelemetry (OTel) SDK/Exporter-Paket (oft als „Agent“ bezeichnet), um Operationen (Spans) zu erfassen.
• OTel-Exporter: Der OTel-Exporter der Anwendung sendet diese Spans über das lokale Netzwerk an die nächste Komponente.
• OpenTelemetry Collector (Empfohlen): Der Collector empfängt die Traces, verarbeitet sie in Bündeln (Batch-Verarbeitung) und wendet eine sichere Authentifizierung an, bevor er sie über das Internet weiterleitet.
• STACKIT Observability Endpunkt (Tempo): Der Collector überträgt die Traces an den spezifischen Tempo-Ingestion-Endpunkt in Ihrer STACKIT-Instanz, wo sie gespeichert und für Abfragen indexiert werden.

Dieses Modell ermöglicht es Ihrer Anwendung, sich auf die eigentliche Geschäftslogik zu konzentrieren, während Sicherheit und zuverlässige Übertragung an den Collector delegiert werden.

Tracing in Ihre Anwendung integrieren

Um Tracing in Ihrer Anwendung zu aktivieren, müssen Sie das passende OpenTelemetry SDK für Ihre Programmiersprache einbinden. Dieses SDK erfasst die Tracing-Daten.

Detaillierte sprachspezifische Anleitungen zur Integration finden Sie in der offiziellen OpenTelemetry-Dokumentation: OpenTelemetry Language Documentation

Authentifizierung konfigurieren (Base64-Kodierung)

Aus Sicherheitsgründen ist der Trace-Endpunkt durch Basic Authentication geschützt. Der OTLP-Exporter im Collector erfordert, dass Ihre technischen Zugangsdaten im Format username:password Base64-kodiert vorliegen.

Kodierungsformat: BASE64(<USERNAME>:<PASSWORD>)

Sie können diese Kodierung mit einem Standard-Kommandozeilenwerkzeug durchführen. Ersetzen Sie dabei <USERNAME> und <PASSWORD> durch Ihre generierten technischen Zugangsdaten:

echo -n "<USERNAME>:<PASSWORD>" | base64

Kopieren Sie die generierte Base64-Zeichenfolge, da Sie diese für den authorization-Header in der Collector-Konfiguration benötigen.

Beispiel für eine OpenTelemetry Collector-Konfiguration

Der Collector ist die bevorzugte Methode zur Verwaltung der Authentifizierung und zum Exportieren von Daten. Dieses Beispiel zeigt eine einfache Konfiguration (collector-config.yaml), die Traces über OTLP empfängt und sie unter Verwendung der erforderlichen Basic-Auth-Header sicher an den STACKIT-Endpunkt weiterleitet.

collector-config.yaml

receivers:
  # Empfängt OTLP-Traces von Ihren Anwendungen (z. B. auf Port 4317)
  otlp:
    protocols:
      grpc:
      http:
  jaeger:
    protocols:
      thrift_compact:

processors:
  # Bündelt Traces für eine effiziente Übertragung
  batch:

exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200

  # Leitet Traces an die STACKIT Observability-Instanz (Tempo) weiter
  otlp:
    # WICHTIG: Kopieren Sie die vollständige "OTLP ingest"-URL für Traces aus dem STACKIT Portal.
    # Diese URL enthält bereits den erforderlichen Port 443 für OTLP/gRPC über TLS.
    endpoint: "<TRACING_ENDPOINT_URL>"
    headers:
      # Erforderlich für Basic Authentication
      authorization: "Basic <BASE64_ENCODED_CREDENTIALS>"
    tls:
      # Verwenden Sie TLS, wenn Ihr Endpunkt dies erfordert (dringend empfohlen und Standard)
      insecure: false

service:
  pipelines:
    traces:
      receivers: [otlp, jaeger]
      processors: [batch]
      exporters: [otlp]

docker-compose.yaml

Der OTel Collector kann wie folgt über Docker ausgeführt werden. Er mountet Ihre lokale Konfigurationsdatei in den Container.

services:
  otel-collector:
    image: otel/opentelemetry-collector:latest
    # image: otel/opentelemetry-collector-contrib
    container_name: otel-collector
    command:
      - --config=/etc/otel-config.yaml
    volumes:
      - ./conf/collector-config.yaml:/etc/otel-config.yaml:ro

Durch die Umsetzung dieser Collector-Konfiguration stellen Sie sicher, dass Ihre Traces zuverlässig gesammelt, gebündelt, authentifiziert und sicher an Ihre Tempo-Instanz geliefert werden.

Traces prüfen

Nun können Sie in Grafana die Datenquelle Tempo auswählen. Der empfohlene Weg zur Indexierung von Traces besteht darin, die Datenquelle Tempo zu verwenden und die Traces in Loki zu protokollieren. Dadurch werden die Traces den Logs zeitlich zugeordnet.