Migration zu OpenTelemetry: proprietäre Agents schrittweise ablösen

Proprietäre Agents waren sinnvoll, solange jeder Anbieter sein eigenes Datenmodell hatte. Heute deckt OpenTelemetry Traces, Metriken und Logs mit einem Satz SDKs, einem Übertragungsprotokoll (OTLP) und einheitlichen Namensregeln ab, und die meisten Observability-Backends nehmen es nativ an. Wer OpenTelemetry einführt, macht aus der Instrumentierung ein eigenes Asset statt eines Anbietervertrags: Backends wechseln oder ergänzen Sie durch eine Änderung der Collector-Konfiguration, ohne jeden Service neu auszurollen.

Diese Anleitung beschreibt eine schrittweise Migration zu OpenTelemetry, wie wir sie bei Teams erlebt haben, die proprietäre Agents wie den Datadog Agent ablösen, von der Bestandsaufnahme bis zur finalen Umstellung. Ziel ist, während der Migration keine blinden Flecken zu haben. Die zentrale Technik ist daher Dual-Shipping: Dieselbe Telemetrie geht parallel an das alte und das neue Backend. Wenn Sie die Grundbausteine auffrischen möchten, beginnen Sie mit Was ist OpenTelemetry?.

Schritt 1: Bestandsaufnahme, was der Agent heute wirklich tut

Ein proprietärer Agent erledigt meist mehr, als irgendjemand im Kopf hat. Bevor Sie etwas ändern, dokumentieren Sie pro Umgebung:

• Signale: Host-Metriken, Container- und Kubernetes-Metriken, APM-Traces, Log-Tailing, eigene Metriken (oft über StatsD oder DogStatsD), Prozess-Monitoring, Netzwerk-Checks, Profiling.
• Integrationen: Checks für Datenbanken, Queues und Webserver, die der Agent ausführt, sowie Cloud-Integrationen, die Metriken über Provider-APIs statt über den Agent abrufen.
• Abnehmer: Dashboards, Monitore und Alerts, SLOs, geplante Reports und alles, was Daten per API liest, etwa Autoscaler oder Deployment-Gates.
• Tags und Benennung: die Tag-Konventionen, auf die Ihre Teams sich verlassen, zum Beispiel env, service und version sowie Team- oder Kostenstellen-Tags.

Exportieren Sie die Liste der Monitore und Dashboards mit dem Datum der letzten Nutzung oder Auslösung. In den meisten Organisationen wurde ein beträchtlicher Teil seit Monaten nicht mehr angesehen. Jedes ungenutzte Dashboard, das Sie löschen, müssen Sie nicht migrieren.

Schritt 2: Collector ausrollen und Dual-Shipping einrichten

Der OpenTelemetry Collector ist der Dreh- und Angelpunkt der Migration. Rollen Sie ihn als Agent pro Node aus (in Kubernetes als DaemonSet) und bei größeren Umgebungen zusätzlich als Gateway-Schicht. Anwendungen senden OTLP an den lokalen Collector, der an beide Backends exportiert. Das Beispiel nutzt Komponenten aus der Contrib-Distribution des Collectors, darunter Datadog-Exporter und -Connector, sodass der bisherige Anbieter weiter Daten erhält, während sich das neue Backend füllt:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu: {}
      memory: {}
      disk: {}
      filesystem: {}
      network: {}
      load: {}

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 80
    spike_limit_percentage: 20
  resourcedetection:
    detectors: [env, system]
  batch:
    timeout: 5s

connectors:
  datadog/connector: {}

exporters:
  datadog:
    api:
      key: ${env:DD_API_KEY}
      site: ${env:DD_SITE}
  otlp/obseria:
    endpoint: ${env:OBSERIA_OTLP_ENDPOINT}
    headers:
      authorization: "Bearer ${env:OBSERIA_TOKEN}"
    compression: zstd

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [datadog/connector, datadog, otlp/obseria]
    metrics:
      receivers: [otlp, hostmetrics, datadog/connector]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [datadog, otlp/obseria]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [datadog, otlp/obseria]

Der Connector berechnet die aus Traces abgeleiteten Metriken, die das alte Backend erwartet. Bestehende APM-Ansichten funktionieren also weiter, obwohl die Traces bereits aus OpenTelemetry stammen. Können Sie einzelne Services noch nicht umstellen, bietet die Contrib-Distribution auch Receiver, die Daten bestehender proprietärer Tracer und StatsD-Clients annehmen. So läuft auch Legacy-Traffic über denselben Collector. Bevor dieser Collector Produktionsdaten trägt, setzen Sie die Härtung aus unseren Best Practices für den Collector in Produktion um: Speicherlimits, persistente Queues und Self-Monitoring.

Log-Erfassung und Infrastruktur-Metriken umziehen

Anwendungstelemetrie ist nur die Hälfte dessen, was der alte Agent erfasst hat. Für Logs liest der filelog-Receiver Container- und Anwendungs-Logdateien, parst JSON- oder Regex-Formate und bildet Severity und Zeitstempel auf das Log-Datenmodell von OpenTelemetry ab. In Kubernetes richten Sie ihn auf /var/log/pods aus und kombinieren ihn mit dem k8sattributes-Processor, damit jeder Eintrag Pod-, Namespace- und Workload-Attribute trägt. Für die Infrastruktur deckt der hostmetrics-Receiver aus dem Beispiel CPU, Speicher, Festplatte und Netzwerk ab; die Receiver kubeletstats und k8s_cluster ergänzen Metriken auf Node-, Pod- und Cluster-Ebene. Auch für viele Datenbanken und Middleware-Komponenten gibt es Collector-Receiver, etwa für PostgreSQL, MySQL, Redis oder Kafka, und alles, was bereits Prometheus-Metriken bereitstellt, erfassen Sie mit dem prometheus-Receiver. Ordnen Sie jedem Agent-Check aus Ihrer Bestandsaufnahme einen Receiver zu, bevor Sie den Agent entfernen, und notieren Sie die wenigen Checks ohne Entsprechung. Diese bleiben beim alten Agent, bis Sie Ersatz gefunden oder entschieden haben, dass die Daten verzichtbar sind.

Schritt 3: Services auf OpenTelemetry-Auto-Instrumentierung umstellen

Die meisten Services lassen sich ohne Codeänderung umstellen. Für jede Sprache gibt es eine Zero-Code-Variante, die gängige Frameworks, HTTP-Clients und Datenbanktreiber instrumentiert:

• Java: Binden Sie den OpenTelemetry Java Agent ein, etwa mit JAVA_TOOL_OPTIONS=-javaagent:/otel/opentelemetry-javaagent.jar. Entfernen Sie den alten Agent in derselben Änderung; zwei Bytecode-Agents auf denselben Klassen erzeugen doppelte Spans und Overhead. Details für JVM-Services finden Sie im Leitfaden Java Monitoring.
• Python: Installieren Sie opentelemetry-distro, führen Sie opentelemetry-bootstrap -a install aus und starten Sie den Service mit opentelemetry-instrument python app.py.
• Node.js: Installieren Sie @opentelemetry/auto-instrumentations-node und setzen Sie NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register".
• .NET: Nutzen Sie die OpenTelemetry .NET Automatic Instrumentation, die über dieselben Umgebungsvariablen und zusätzlich eigene OTEL_DOTNET_AUTO_*-Einstellungen konfiguriert wird.
• Go: Einen Laufzeit-Agent im klassischen Sinn gibt es nicht. Verwenden Sie die Instrumentierungsbibliotheken für Ihre HTTP- und gRPC-Frameworks oder prüfen Sie die eBPF-basierte Zero-Code-Instrumentierung für Services, die Sie nicht ändern können.

In Kubernetes injiziert der OpenTelemetry Operator diese Agents automatisch über eine Instrumentation-Ressource und eine Pod-Annotation wie instrumentation.opentelemetry.io/inject-java: "true". Die Konfiguration ist über alle Sprachen gleich:

OTEL_SERVICE_NAME=checkout
OTEL_RESOURCE_ATTRIBUTES=service.version=1.42.0,deployment.environment.name=production
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=1.0
OTEL_PROPAGATORS=tracecontext,baggage

Achten Sie während der Übergangszeit auf die Context Propagation. Ruft ein migrierter Service einen Service auf, der noch den alten Tracer nutzt, müssen beide ein gemeinsames Header-Format verstehen, sonst reißen Traces in der Mitte ab. W3C Trace Context ist der Standard von OpenTelemetry; viele proprietäre Tracer lassen sich so konfigurieren, dass sie ihn ebenfalls lesen und schreiben. Migrieren Sie nach Möglichkeit entlang von Aufrufketten, beginnend am Rand Ihrer Architektur.

Schritt 4: Semantic Conventions und Resource-Attribute sauber setzen

Die Migration ist Ihre Chance, die Benennung ein für alle Mal zu bereinigen. Die OpenTelemetry Semantic Conventions definieren Standardnamen für Attribute. Backends, die ihnen folgen, erzeugen Service-Maps, RED-Metriken und Korrelationen automatisch. Übertragen Sie alte Tags bewusst:

Typischer proprietärer Tag	OpenTelemetry-Attribut	Hinweis
service	service.name	Pflicht; gesetzt über OTEL_SERVICE_NAME
version	service.version	Aus dem CI-Build setzen
env	deployment.environment.name	Ältere SDKs nutzen deployment.environment
host	host.name	Ergänzt durch den resourcedetection-Processor
pod, namespace	k8s.pod.name, k8s.namespace.name	Ergänzt durch den k8sattributes-Processor
http.status_code	http.response.status_code	Aktuelle HTTP-Konventionen

Führen Sie eigene Tags wie Team oder Kostenstelle als Resource-Attribute mit einheitlichem Präfix und dokumentieren Sie sie. Inkonsistente Resource-Attribute sind der häufigste Grund, warum Ansichten im Distributed Tracing nach einer Migration lückenhaft wirken.

Schritt 5: Dashboards und Alerts nach Anwendungsfall migrieren

Übersetzen Sie Dashboards nicht eins zu eins. Metriknamen und Einheiten unterscheiden sich zwischen proprietären Agents und OpenTelemetry (OpenTelemetry nutzt etwa Sekunden für Dauern und Punkt-Namen wie http.server.request.duration), eine mechanische Übersetzung erzeugt daher kaputte Panels. Gehen Sie stattdessen so vor:

1. Gruppieren Sie Dashboards und Alerts nach Anwendungsfall: Service-Gesundheit (RED-Metriken), Infrastruktur (USE-Metriken), Business-KPIs, SLOs.
2. Bauen Sie pro Anwendungsfall ein zentrales Dashboard auf OpenTelemetry-Daten neu, mit Variablen für Service und Umgebung statt eines Dashboards pro Service.
3. Legen Sie Alerts neu an, zuerst jene, die Menschen wecken. Bevorzugen Sie symptombasierte Alerts und SLO-Burn-Rates gegenüber Dutzenden ursachenbasierter Schwellwerte.
4. Speichern Sie neue Dashboards und Alerts als Code, damit sie reviewt und reproduzierbar sind.

Schritt 6: Validieren und Service für Service umstellen

Dual-Shipping liefert zwei Sichten auf dieselbe Realität. Nutzen Sie sie. Vergleichen Sie pro Service Request-Rate, Fehlerrate und Latenz-Perzentile zwischen altem und neuem Backend über mindestens einen vollständigen Geschäftszyklus, oft eine Woche. Abweichungen von wenigen Prozent sind wegen unterschiedlichem Sampling und unterschiedlicher Aggregation normal; große Lücken deuten auf fehlende Instrumentierung oder abgerissene Propagation hin. Stellen Sie außerdem sicher, dass jeder Alert mit Rufbereitschaftsbezug im neuen System mindestens einmal ausgelöst hat, natürlich oder durch einen kontrollierten Test.

Hat ein Service die Prüfung bestanden, entfernen Sie dort den alten Agent oder Tracer und nehmen seine Daten aus dem alten Exporter. Haben alle Services bestanden, entfernen Sie den alten Exporter aus der Collector-Konfiguration. Das ist die Umstellung: eine Konfigurationsänderung statt eines Krisenwochenendes.

Typische Fehler bei der Migration zu OpenTelemetry

• Zwei Agents in einem Prozess: Ein proprietärer Bytecode-Agent und der OpenTelemetry-Agent gemeinsam führen zu doppelten Spans und höherem Overhead. Stellen Sie pro Service um, nicht pro Bibliothek.
• Abgerissene Traces an gemischten Grenzen: Gleichen Sie die Propagatoren an, bevor Sie Aufrufer und Aufgerufene getrennt migrieren.
• Überraschungen bei der Kardinalität: Auto-Instrumentierung kann Attribute wie vollständige URLs erzeugen. Entfernen oder normalisieren Sie hochkardinale Attribute im Collector vor dem Export.
• Logs ohne Trace-Kontext: Konfigurieren Sie die Bridge Ihrer Logging-Bibliothek so, dass Log-Einträge trace_id und span_id enthalten, sonst verlieren Sie die Korrelation zwischen Logs und Traces.
• Ungehärteter Collector: Ohne Speicherlimits und Queues wird der Collector zum neuen Single Point of Failure.
• Vergessene Abnehmer: Autoscaler, Deployment-Gates und Reports, die die API des alten Anbieters abfragen, fallen bei der Umstellung stillschweigend aus.

Ein realistischer Zeitplan für die Migration

Der folgende Zeitplan passt zu einer Organisation mit einigen Dutzend Services auf Kubernetes. Große Landschaften wiederholen die Phasen 3 bis 5 in Wellen.

Phase	Dauer	Ergebnis
1. Bestandsaufnahme und Bereinigung	1 Woche	Liste der zu migrierenden Signale, Integrationen, Dashboards und Alerts
2. Collector und Dual-Shipping	1 Woche	Gehärteter Collector exportiert an altes und neues Backend
3. Auto-Instrumentierung	2–4 Wochen	Services senden OTLP mit konsistenten Resource-Attributen
4. Dashboards und Alerts	2–3 Wochen	Zentrale Dashboards und Rufbereitschafts-Alerts als Code neu aufgebaut
5. Validierung	1–2 Wochen	Abgenommener Vergleich pro Service
6. Umstellung und Rückbau	1 Woche	Alte Agents und Exporter entfernt, Vertrag ausgelaufen

Wie Obseria Sie beim Wechsel unterstützt

Obseria ist OpenTelemetry-nativ: Die Plattform nimmt OTLP direkt an, folgt den Semantic Conventions und erlaubt den Export Ihrer Daten jederzeit. Die Instrumentierung, die Sie in dieser Migration aufbauen, bleibt also Ihre. Teams mit bestehenden OpenTelemetry-SDKs sehen ihren ersten Trace in rund 15 Minuten. Wenn Sie Optionen abwägen, beschreibt unser Vergleich Obseria vs. Datadog Preis- und Datenmodelle. Teams, die von Datadog, Dynatrace oder New Relic wechseln, können den Wechselbonus beantragen, der nutzungsbasierte Gebühren für bis zu drei Monate gutschreibt. Unser Migrationsservice unterstützt bei Collector-Konfiguration, dem Neuaufbau von Dashboards und der Validierungsphase.