Elysia Tools
Mobile Navigation
Workflow Playbook
Alte Attribute erfassen, semantische Konventionen migrieren, Kontextweitergabe prüfen und einen echten Trace vor dem Release untersuchen.
Themen
Dieser Ablauf richtet sich an Verantwortliche für ein geplantes OpenTelemetry-Konventionsupgrade, nicht an ein Incident-Team. Sichern Sie einen bereinigten Logauszug vor der Änderung, die Instrumentierungs- oder Collector-Konfiguration und eine Anfrage über mindestens zwei Dienste. Entfernen Sie personenbezogene Daten und Geheimnisse. structured-log-analyzer zeigt vorhandene Attribute; bei logfmt macht logfmt-to-json-structured-log-bridge Anführungszeichen, Typumwandlungen und doppelte Schlüssel sichtbar. Bereits strukturiertes JSON muss nicht umgewandelt werden. Für eine ausführliche Prüfung sensibler Logdaten ist pii-log-redaction zuständig.
Führen Sie otel-semantic-convention-migration-tool auf einer Kopie von Code, Collector-Regeln oder Dashboard-Abfragen aus. Halten Sie Quell- und Zielversion, vorgeschlagene Änderungen, entfernte und nicht zugeordnete Felder fest. Das Ergebnis ist ein Entwurf und kein Deployment. Bei http.target kann eine bewusste Aufteilung in Pfad und Query erforderlich sein, nicht bloß eine neue Schreibweise. Lassen Sie solche Fälle fachlich entscheiden und rollen Sie nur geprüfte Änderungen aus. Prüfen Sie danach auch Dashboard-Abfragen: Eine hohe Zahl umbenannter Attribute beweist nicht, dass alte Referenzen verschwunden sind.
Prüfen Sie W3C-Header traceparent, tracestate, baggage sowie OTLP-Header mit opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator. Beim nächsten Dienst bleibt die Trace-ID erhalten, während die Span-ID wechselt. Korrekte Header garantieren jedoch keine emittierten Spans. Untersuchen Sie deshalb einen Export nach dem Upgrade mit distributed-trace-decoder-waterfall-visualizer. Vergleichen Sie Dienstfolge, Eltern-Kind-Kanten, Fehler und Laufzeiten mit dem erwarteten Anfragepfad und notieren Sie fehlende Spans ausdrücklich.
Falls ein Latenzziel vereinbart ist, vergleichen Sie mit api-latency-budget-planner beobachtete Etappenzeiten und Budgetanteile. Ein Einzeltrace hilft bei der Ursachenfindung, liefert aber keinen statistischen P99. Zur Abnahme gehören Versionen, Attribut-Diff, Headerprüfung, Trace-Beleg und offene Abweichungen. Geht es stattdessen um einen akuten Vorfall oder das Nachspielen einer API-Anfrage, nutzen Sie observability-debugging beziehungsweise api-request-replay-and-debugging.
Workflow-Leitfaden
Einen bereinigten Logauszug vor der Änderung auswerten. logfmt nur bei Bedarf in JSON umwandeln, um zitierte Werte und doppelte Schlüssel zu erkennen.
Unterstützte Attribute aus v1.20 umschreiben, Diff und Umbenennungsregeln prüfen und entfernte oder nicht zugeordnete Felder separat entscheiden.
traceparent, tracestate, baggage und OTLP-Header an einem Beispielübergang auf unveränderte Trace-ID und neue Span-ID prüfen.
Einen OTel-, Jaeger- oder Zipkin-JSON-Export nach der Änderung dekodieren und Dienste, Eltern, Fehler und Dauer mit dem erwarteten Ablauf vergleichen.
logfmt bei verdeckten Feldern oder doppelten Schlüsseln umwandeln; typisiertes JSON direkt analysieren.
Entfernte und nicht zugeordnete Attribute wie http.target vor dem Einsatz von Collector-Regeln manuell prüfen.
Header für Kontextkontinuität, den Export für tatsächlich verbundene Spans und ein Budget nur bei vorhandenem Ziel prüfen.
Bei vorhandenem Ziel beobachtete Span-Zeiten den vereinbarten Etappenbudgets gegenüberstellen und Überschreitungen dokumentieren.