GenAI Semantic Conventions

Was sind die GenAI Semantic Conventions?

Die Semantic Conventions von OpenTelemetry legen einheitliche Namen und Bedeutungen für Telemetriedaten fest, zum Beispiel http.request.method für HTTP oder db.system.name für Datenbanken. Die GenAI Semantic Conventions erweitern dieses Vokabular auf generative KI: Aufrufe von Sprachmodellen, Embeddings, Retrieval, Agenten und Tools. Ziel ist, dass ein Chat-Aufruf, der über das SDK eines Anbieters oder ein Agenten-Framework erfasst wird, dieselbe Span-Struktur und dieselben Attributnamen erzeugt wie jeder andere.

Die Konventionen werden von der GenAI Special Interest Group bei OpenTelemetry entwickelt und inzwischen in einem eigenen Repository, semantic-conventions-genai, in der OpenTelemetry-Organisation auf GitHub gepflegt. Stand 2026 haben sie den Status Development: Attributnamen und Strukturen können sich zwischen Versionen noch ändern. Das ist für Dashboards und Abfragen, die darauf aufbauen, relevant.

Was die Konventionen abdecken

• Modell-Spans für Inferenzoperationen wie chat, generate_content, text_completion und embeddings sowie retrieval für Suchen in einer Wissensquelle.
• Agenten-Spans für create_agent, invoke_agent und execute_tool, die Grundlage der KI-Agenten-Observability, ergänzt um Spans für Workflows und Skills.
• Metriken wie gen_ai.client.operation.duration, Zähler für den Token-Verbrauch und serverseitige Metriken wie gen_ai.server.time_to_first_token und gen_ai.server.time_per_output_token.
• Events für Ein- und Ausgaben sowie Konventionen für Exceptions.
• Anbieterspezifische Konventionen, etwa für Anthropic, AWS Bedrock, Azure AI Inference und OpenAI, sowie Konventionen für das Model Context Protocol.

Der praktische Nutzen liegt in der Vergleichbarkeit. Ohne gemeinsame Namen erfindet jede Bibliothek eigene Attribute, ein Framework speichert das Modell etwa als llm.model, ein anderes als model_name, und jedes Dashboard, jeder Alert und jeder Kostenbericht muss pro Integration neu gebaut werden. Mit den Konventionen fügen sich GenAI-Spans in bestehende verteilte Traces neben HTTP- und Datenbank-Spans ein, und ein Wechsel des Modellanbieters oder Frameworks bricht Ihre Abfragen nicht. Zugleich verringert das die Abhängigkeit von einzelnen Herstellern, weil das Datenmodell zu einem offenen Standard gehört und nicht zu einem Observability-Produkt.

Wichtige gen_ai-Attribute

Attribut	Bedeutung
gen_ai.operation.name	Art der Operation, etwa chat oder invoke_agent (erforderlich)
gen_ai.provider.name	Anbieter, etwa openai oder aws.bedrock; ersetzt das ältere gen_ai.system
gen_ai.request.model	Vom Client angefordertes Modell
gen_ai.response.model	Modell, das die Antwort tatsächlich erzeugt hat
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens	Input-Tokens (einschließlich gecachter) und Output-Tokens
gen_ai.response.finish_reasons	Grund für das Ende der Generierung, etwa stop oder length
gen_ai.conversation.id	Kennung, die die Aufrufe eines Gesprächs oder einer Sitzung bündelt
gen_ai.agent.name, gen_ai.tool.name	Beteiligter Agent und beteiligtes Tool eines Schritts

Span-Namen folgen dem Muster {gen_ai.operation.name} {gen_ai.request.model}, zum Beispiel chat gpt-4o. Details zu Token-Zahlen finden Sie unter Token-Verbrauch.

Erfassung von Inhalten und Datenschutz

Prompt- und Antwortinhalte sind sensibel. Die Konventionen definieren Attribute wie gen_ai.input.messages, gen_ai.output.messages und gen_ai.system_instructions deshalb als Opt-in: Instrumentierungen sollen sie nur erfassen, wenn Sie das ausdrücklich aktivieren, etwa über eine Einstellung wie OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. Dasselbe gilt für abgerufene Dokumente und Argumente von Tool-Aufrufen. Wenn Sie Inhalte erfassen, sollten Sie personenbezogene Daten vor der Speicherung in einer Pipeline maskieren und Zugriff sowie Aufbewahrung beschränken. Gerade im Hinblick auf die DSGVO ist das ein Punkt, den Sie früh mit Datenschutz und Security abstimmen sollten.

Beispiel: Span eines Chat-Aufrufs

Ein illustrativer Span, den ein instrumentierter Modell-Client erzeugt, in vereinfachter Form:

span: chat gpt-4o   (kind: CLIENT, Dauer 1,84 s)
  gen_ai.operation.name        = "chat"
  gen_ai.provider.name         = "openai"
  gen_ai.request.model         = "gpt-4o"
  gen_ai.response.model        = "gpt-4o-2024-08-06"
  gen_ai.request.max_tokens    = 500
  gen_ai.usage.input_tokens    = 1240
  gen_ai.usage.output_tokens   = 312
  gen_ai.response.finish_reasons = ["stop"]
  server.address               = "api.openai.com"

Weil diese Namen standardisiert sind, funktioniert eine Abfrage wie „p95-Dauer und Output-Tokens je gen_ai.request.model“ unabhängig davon, welches SDK oder Framework die Spans erzeugt hat.

Best Practices für die Einführung

• Bevorzugen Sie Instrumentierungen, die die GenAI-Konventionen erzeugen, statt eigener Attributnamen. So bleiben Ihre Daten portabel.
• Halten Sie fest, welche Version der Konventionen Ihre Instrumentierung erzeugt. Manche Instrumentierungen erlauben das Opt-in in die neueste experimentelle Version, etwa über OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental; prüfen Sie die Dokumentation Ihrer Bibliothek.
• Planen Sie Umbenennungen ein: Bauen Sie Dashboards auf wenigen Kernattributen auf und prüfen Sie sie bei jedem Update der Instrumentierung.
• Lassen Sie die Erfassung von Inhalten standardmäßig aus und aktivieren Sie sie bewusst pro Umgebung.
• Propagieren Sie den Trace-Kontext in Tools und Sub-Agenten, damit GenAI-Spans Teil des übrigen verteilten Traces werden.

Wie Obseria hilft

Obseria ist OpenTelemetry-nativ und speichert GenAI-Spans, -Metriken und -Events so, wie sie per OTLP eingehen, ohne proprietäres Schema. Da Obseria Lake mit Schema-on-Read arbeitet, sind neue oder umbenannte gen_ai.*-Attribute sofort mit PromQL, OQL oder SQL abfragbar. Die Obseria Pipeline kann Inhaltsattribute vor der Speicherung verwerfen oder maskieren. Mehr unter OpenTelemetry in Obseria.