Instrumentierung bezeichnet das Ergänzen von Code, Bibliotheken oder Agents in Software, damit sie Telemetrie wie Traces, Metriken, Logs und Profile erzeugt. Sie kann automatisch erfolgen, wobei sich ein Agent oder eine Bibliothek ohne Codeänderung in Frameworks einklinkt, oder manuell, wobei Entwickler über eine API wie OpenTelemetry Spans, Attribute und Metriken für fachliche Abläufe ergänzen.
Was Instrumentierung ist
Software erklärt sich nicht von selbst. Um zu wissen, wie lange ein Request gedauert hat, welche Datenbankabfrage er ausgeführt hat oder warum er fehlgeschlagen ist, muss der Code diese Informationen erfassen und weitergeben. Instrumentierung ist alles, was das ermöglicht: API-Aufrufe, die Spans erzeugen, Counter und Histogramme, die Messwerte festhalten, Logger, die strukturierte Events schreiben, und Agents, die einen Teil davon oder alles automatisch erledigen.
Instrumentierung ist das erste Glied der Telemetrie-Kette. Collector, Pipelines, Speicher und Dashboards können nur mit dem arbeiten, was die Instrumentierung erzeugt hat. Ist ein kritischer Codepfad nicht instrumentiert, kann kein Backend zeigen, was darin passiert ist.
Warum Instrumentierung wichtig ist
Die Qualität einer Analyse ist durch die Qualität der Instrumentierung dahinter begrenzt. Gute Instrumentierung liefert einheitliche Servicenamen, sinnvolle Span-Grenzen, standardisierte Attributnamen und korrelierte Signale. So lässt sich ein Latenz-Peak im Dashboard mit wenigen Klicks zu einem Trace, einer Logzeile und einem Profil verfolgen. Schlechte Instrumentierung erzeugt unverbundene Fragmente: Metriken ohne Kontext, Logs ohne Trace-IDs und Traces, die an der ersten Message Queue enden. Außerdem werden in der Instrumentierung die ersten Entscheidungen über Kosten und Datenschutz getroffen, denn jedes erfasste Attribut muss später transportiert, gespeichert und geschützt werden.
Automatische und manuelle Instrumentierung
| Aspekt | Automatisch (Zero-Code) | Manuell (im Code) |
|---|---|---|
| Wie | Agent oder Bibliothek klinkt sich zur Laufzeit in Frameworks und Clients ein | Entwickler rufen die OpenTelemetry-API im Anwendungscode auf |
| Abdeckung | HTTP-Server und -Clients, gRPC, Datenbanken, Messaging, verbreitete Frameworks | Fachliche Abläufe, eigene Protokolle, Domänenattribute |
| Aufwand | Minuten, oft nur Konfiguration | Laufende Entwicklungsarbeit |
| Kontext | Technisch: Routen, Statuscodes, Queries | Fachlich: Bestellwert, Mandant, Feature Flag |
Die meisten Teams kombinieren beides. Automatische Instrumentierung liefert vom ersten Tag an breite Abdeckung, manuelle Instrumentierung ergänzt die Spans und Attribute, die Traces fachlich aussagekräftig machen. Eine dritte Option ist Instrumentierung auf Kernel-Ebene mit eBPF, die Daten von außerhalb des Prozesses erfasst, ohne Code oder Runtime anzufassen.
Instrumentierung mit OpenTelemetry
OpenTelemetry trennt die API, die Bibliotheken und Anwendungen aufrufen, vom SDK, das die Daten verarbeitet und exportiert. Bibliotheksautoren können gegen die API instrumentieren, ohne ein bestimmtes Backend vorzuschreiben, und Anwendungsverantwortliche wählen SDK-Konfiguration und Exporter, typischerweise OTLP. Semantic Conventions legen Standardnamen für Attribute wie http.request.method, http.route und db.system fest, damit Telemetrie aus verschiedenen Sprachen einheitlich aussieht.
Für viele Sprachen gibt es Zero-Code-Optionen. Beispielhafte Startbefehle:
# Java: Agent anhängen
OTEL_SERVICE_NAME=checkout java -javaagent:opentelemetry-javaagent.jar -jar app.jar
# Python: Instrumentierungen installieren, dann über den Wrapper starten
opentelemetry-bootstrap -a install
OTEL_SERVICE_NAME=checkout opentelemetry-instrument python app.py
# Node.js: Auto-Instrumentierungen beim Start registrieren
OTEL_SERVICE_NAME=checkout node --require @opentelemetry/auto-instrumentations-node/register app.jsIn Kubernetes kann der OpenTelemetry Operator diese Agents anhand von Annotationen in Pods injizieren, sodass Teams ihre Container-Images nicht ändern müssen.
Beispiel: ein manueller Span
Die automatische Instrumentierung zeigt, dass ein Request POST /checkout 900 ms gedauert hat. Die manuelle Instrumentierung zeigt, warum:
with tracer.start_as_current_span("apply_discounts") as span:
span.set_attribute("cart.items", len(cart.items))
span.set_attribute("discount.rules_evaluated", rules_count)
total = discount_engine.apply(cart)Der neue Span erscheint als Kind des automatisch erzeugten Server-Spans, mit Attributen, über die Sie langsame Traces nach Warenkorbgröße filtern können.
Best Practices
- Mit automatischer Instrumentierung beginnen, um schnell Service-Maps und Request-Metriken zu erhalten.
- Resource-Attribute setzen, etwa
service.name,service.versionunddeployment.environment.name, und zwar überall. Sie sind das Rückgrat für Filterung und Korrelation. - Manuelle Spans für geschäftskritische Pfade ergänzen, nicht für jede Funktion. Spans sollten sinnvolle Arbeitseinheiten abbilden.
- Semantic Conventions befolgen, statt pro Team eigene Attributnamen zu erfinden.
- Context Propagation sicherstellen, über Threads, Queues und Servicegrenzen hinweg, sonst zerfallen Traces.
- Sensible Daten schützen. Keine Passwörter, Tokens oder vollständigen Request-Bodies erfassen und personenbezogene Daten an der Quelle oder in der Pipeline maskieren.
Häufige Fehler
Zu viel Instrumentierung schadet ebenso wie zu wenig: Spans für jeden Getter blähen das Datenvolumen auf und verdecken die wichtige Arbeit. Unbegrenzte Werte wie User-IDs in Metrik-Attributen verursachen Kardinalitätsprobleme. Proprietäre Agents mit herstellerspezifischen APIs verteuern jede spätere Migration. Und Instrumentierung, die nie in Produktion überprüft wurde, etwa bei einem kritischen Batch-Job, offenbart ihre Lücken erst im Incident.
Wie Obseria unterstützt
Obseria ist OpenTelemetry-nativ: Vorhandene OpenTelemetry-SDKs und -Agents senden Daten per OTLP, der erste Trace kommt typischerweise innerhalb von 15 Minuten an. Der Obseria Agent, einmal pro Host installiert, ergänzt Infrastrukturmetriken, Logs, Profile und Security-Signale. Sprachspezifische Anleitungen gibt es für Java, Python und Node.js, den zugrunde liegenden Standard erklärt Was ist OpenTelemetry?.
