Semantic Conventions

Was sind Semantic Conventions?

Semantic Conventions, kurz semconv, sind der Teil der OpenTelemetry-Spezifikation, der festlegt, wie Telemetrie heißt und was sie bedeutet. Ohne sie würde eine Java-Bibliothek status erfassen, eine Python-Bibliothek http_code und ein Go-Service response.status, alles für denselben HTTP-Statuscode. Mit ihnen meldet jeder instrumentierte HTTP-Server http.response.status_code als Ganzzahl, und eine einzige Abfrage funktioniert über die gesamte Landschaft.

Die Konventionen umfassen Resource-Attribute (wer die Daten erzeugt), Span-Attribute und Span-Namen, Metriknamen und Einheiten, Log- und Event-Attribute sowie zahlreiche Technologiebereiche wie HTTP, Datenbanken, Messaging, RPC, Cloud, Kubernetes, Container und generative KI.

Wichtige Attribute, die Ihnen überall begegnen

Attribut	Beschreibt	Beispielwert
service.name	Logischer Name des Service (Resource)	checkout
service.version	Ausgerollte Version (Resource)	2.14.1
deployment.environment.name	Umgebung (Resource)	production
http.request.method	HTTP-Methode	POST
http.response.status_code	HTTP-Statuscode der Antwort	503
http.route	Gematchtes Routen-Template, niedrige Kardinalität	/orders/{id}
url.path	Tatsächlicher Request-Pfad	/orders/8812
server.address	Hostname des Servers	api.example.com
db.system.name	Datenbanksystem	postgresql
db.query.text	Datenbankabfrage, bereinigt	SELECT * FROM orders WHERE id = ?
k8s.pod.name	Kubernetes-Pod (Resource)	checkout-7d9f-abc12

Für Metriken gilt dieselbe Logik. Die Standardmetrik für HTTP-Server-Latenz heißt http.server.request.duration, ein Histogramm in Sekunden. Damit berechnet jedes Backend Request-Rate, Fehlerrate und Latenzperzentile für jeden Service, ganz ohne eigene Namensschemata.

Beispiel: eine Abfrage für alle Services

Weil jede konforme HTTP-Server-Instrumentierung dieselben Attribute erfasst, zählt eine einzige OQL-Abfrage (zur Veranschaulichung) Serverfehler pro Route über Java-, Python- und Go-Services hinweg:

fetch spans
| filter http.response.status_code >= 500
| summarize count(), by:{service.name, http.route}

Ohne gemeinsame Konventionen bräuchten Sie für dieselbe Frage eine Abfrage pro Sprache und Framework, und für jeden neuen Service müsste jemand Dashboards und Alarme von Hand anpassen. Gerade in gewachsenen Landschaften mit vielen Teams spart das erheblichen Pflegeaufwand.

Resource-Attribute und Span-Attribute

OpenTelemetry unterscheidet zwischen der Resource, also der Einheit, die Telemetrie erzeugt, und dem einzelnen Signal. Resource-Attribute wie service.name, host.name oder cloud.region werden einmal pro Prozess gesetzt und an jeden Span, jede Metrik und jedes Log angehängt. Span- oder Datenpunkt-Attribute wie http.route beschreiben eine einzelne Operation. Eine saubere Trennung vermeidet doppelte Metadaten und macht die Korrelation über Signale hinweg zuverlässig. Fehlt service.name, setzen SDKs unknown_service ein, und die Daten sind schwer auffindbar. Setzen Sie den Namen daher immer, etwa über OTEL_SERVICE_NAME.

Über HTTP hinaus: Messaging, RPC und generative KI

Dasselbe Prinzip gilt für weitere Bereiche. Die Messaging-Konventionen beschreiben Producer und Consumer mit Attributen wie messaging.system und messaging.destination.name, die RPC-Konventionen decken gRPC-Aufrufe ab, und die Konventionen für generative KI definieren Attribute für Modellaufrufe, etwa das angefragte Modell sowie die Zahl der Input- und Output-Tokens. Einige dieser Bereiche entwickeln sich noch weiter. Prüfen Sie daher die Stabilitätsstufe, bevor Sie langlebige Dashboards darauf aufbauen.

Stabilität und Migration

Jede Konvention hat eine Stabilitätsstufe, etwa Development, Release Candidate oder Stable. Stabile Konventionen werden nicht mehr inkompatibel umbenannt. Die HTTP-Konventionen wurden Ende 2023 für stabil erklärt; dabei wurden ältere Attribute umbenannt: Aus http.method wurde http.request.method, aus http.status_code wurde http.response.status_code. Die Datenbank-Konventionen folgten später und ersetzten zum Beispiel db.statement durch db.query.text und db.system durch db.system.name.

Damit Dashboards bei der Migration nicht brechen, unterstützen viele Instrumentierungsbibliotheken die Umgebungsvariable OTEL_SEMCONV_STABILITY_OPT_IN. Mit einem Wert wie http/dup senden sie in einer Übergangsphase alte und neue Attribute parallel, mit http nur noch die neuen. Für Quellen, die Sie nicht schnell ändern können, benennt der transform-Processor im Collector Attribute zentral um.

Best Practices

1. Konventionsnamen verwenden, wo es sie gibt, bevor Sie eigene erfinden. Prüfen Sie zuerst die Spezifikation für Ihren Bereich.
2. Eigene Attribute mit Namespace versehen, etwa app.payment.method oder acme.tenant.tier, damit sie nie mit künftigen offiziellen Namen kollidieren.
3. Die zentralen Resource-Attribute immer setzen: service.name, service.version und deployment.environment.name. Sie steuern Service Maps, Release-Vergleiche und Filter.
4. Kardinalitätsvorgaben beachten. Verwenden Sie auf Metriken http.route statt url.full, um eine Explosion der Kardinalität zu vermeiden.
5. Die semconv-Version pinnen, die Ihre Instrumentierung erzeugt, und Migrationen wie jede Schemaänderung planen.

Typische Fehler

• Alte und neue Attributnamen über Services hinweg mischen, sodass die Hälfte der Dashboards Lücken zeigt.
• Nutzer-IDs oder vollständige URLs in Metrik-Attribute schreiben.
• Unbereinigtes SQL mit Literalwerten in db.query.text erfassen, wodurch personenbezogene Daten abfließen können.

Wie Obseria hilft

Obseria ist OpenTelemetry-nativ und versteht Semantic Conventions ohne Zusatzkonfiguration: service.name sowie Kubernetes- und Cloud-Resource-Attribute speisen Obseria TopoGraph und die Service Map, und Standardattribute für HTTP, Datenbanken und Messaging treiben vorgefertigte Ansichten im Distributed Tracing. Obseria Pipeline normalisiert veraltete Attributnamen beim Ingest, sodass alte und neue Instrumentierung einheitlich erscheinen. Mehr dazu unter OpenTelemetry in Obseria.