OpenTelemetry (OTel) este standardul deschis pentru trace-uri, metrici și loguri. Pentru aplicațiile generative există convențiile semantice GenAI: nume standard pentru span-uri, atribute și metrici la apeluri de inferență, embeddings, unelte și agenți. Au statusul Development (nu sunt stabile) și au fost mutate în depozitul open-telemetry/semantic-conventions-genai.
Mai multe atribute din versiunile vechi au fost înlocuite: gen_ai.system → gen_ai.provider.name, gen_ai.usage.prompt_tokens / completion_tokens → gen_ai.usage.input_tokens / output_tokens, iar gen_ai.prompt și gen_ai.completion au fost eliminate. Conținutul conversației se înregistrează în gen_ai.input.messages, gen_ai.output.messages și gen_ai.system_instructions. În registru nu există un atribut pentru cost.
Conținutul (prompturi, răspunsuri, argumente de unelte) este marcat Opt-In: specificația spune că instrumentările nu trebuie să-l captureze implicit, ci doar la cererea explicită a utilizatorului. Datele se exportă prin OTLP către un colector și de acolo către orice backend care acceptă OTLP; de exemplu, Langfuse primește trace-uri la /api/public/otel/v1/traces.
Concepte cheie și caracteristici
| Concept / Parametru | Descriere practică |
|---|---|
gen_ai.operation.name |
Tipul operației: chat, generate_content, text_completion, embeddings, execute_tool, invoke_agent și altele. |
gen_ai.provider.name |
Furnizorul, de exemplu openai, anthropic, gcp.vertex_ai. |
gen_ai.request.model / gen_ai.response.model |
Modelul cerut și modelul care a răspuns efectiv. |
gen_ai.usage.input_tokens / output_tokens |
Tokenii de intrare și de ieșire. Există și atribute pentru tokenii din cache, de exemplu gen_ai.usage.cache_read.input_tokens. |
gen_ai.response.time_to_first_chunk |
Timpul până la primul fragment, pentru cererile în stream. |
gen_ai.input.messages / gen_ai.output.messages |
Mesajele trimise și primite. Opt-In: nu se înregistrează implicit. |
OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT |
Numele cerut de specificație pentru variabila de mediu care activează capturarea conținutului. Pachetul opentelemetry-instrumentation-openai-v2 folosește încă OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. |
OTEL_EXPORTER_OTLP_ENDPOINT |
Adresa colectorului OTLP. |
Exemple practice și scenarii reale
Exemplul 1: Instrumentarea oficială pentru SDK-ul OpenAI
Pachetul trasează apelurile de chat și embeddings și înregistrează durata și tokenii ca metrici. Trebuie configurat înainte providerul OpenTelemetry (trace-uri, loguri, evenimente).
pip install opentelemetry-instrumentation-openai-v2
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
OpenAIInstrumentor().instrument()Exemplul 2: Export către un colector OpenTelemetry
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"Exemplul 3: Capturarea conținutului doar pe span-uri
Valorile span_only, event_only și span_and_event se aplică, după documentația pachetului, când sunt activate convențiile experimentale cele mai noi.
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_onlyGreșeli frecvente și capcane
- Folosești atribute vechi (
gen_ai.system,gen_ai.usage.prompt_tokens,gen_ai.prompt) sau inventate (gen_ai.usage.cost). Verifică registrul din depozitul semantic-conventions-genai. - Activezi capturarea conținutului în producție fără să te gândești la date personale. Specificația recomandă ca, în producție, conținutul să fie stocat extern, cu acces separat, iar pe span-uri să rămână doar referințe.
- Consideri convențiile stabile. Statusul este Development; numele se mai schimbă între versiuni, deci fixează versiunea pachetelor de instrumentare.