Skip to content

Update GenAI span format to OTel semantic conventions #1621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jimilp7 wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Update GenAI span format to OTel semantic conventions #1621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf0dd23
Update GenAI span format to OTel semantic conventions
jimilp7 Jan 9, 2026
915e895
lint fix
jimilp7 Jan 9, 2026
65427fe
lint fix
jimilp7 Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions logfire/_internal/integrations/llm_providers/anthropic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from __future__ import annotations

from typing import TYPE_CHECKING, Any
from typing import TYPE_CHECKING, Any, cast

import anthropic
from anthropic.types import Message, TextBlock, TextDelta
Expand All @@ -25,15 +25,20 @@
def get_endpoint_config(options: FinalRequestOptions) -> EndpointConfig:
"""Returns the endpoint config for Anthropic or Bedrock depending on the url."""
url = options.url
json_data = options.json_data
if not isinstance(json_data, dict): # pragma: no cover
raw_json_data = options.json_data
if not isinstance(raw_json_data, dict): # pragma: no cover
# Ensure that `{request_data[model]!r}` doesn't raise an error, just a warning about `model` missing.
json_data = {}
raw_json_data = {}
json_data = cast('dict[str, Any]', raw_json_data)

if url == '/v1/messages':
return EndpointConfig(
message_template='Message with {request_data[model]!r}',
span_data={'request_data': json_data},
span_data={
'request_data': json_data,
'gen_ai.request.model': json_data.get('model'),
'gen_ai.operation.name': 'chat',
},
stream_state_cls=AnthropicMessageStreamState,
)
else:
Expand Down
20 changes: 18 additions & 2 deletions logfire/_internal/integrations/llm_providers/llm_provider.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,18 @@
from contextlib import AbstractContextManager, ExitStack, contextmanager, nullcontext
from typing import TYPE_CHECKING, Any, Callable, cast

from opentelemetry.trace import SpanKind

from logfire import attach_context, get_context
from logfire.propagate import ContextCarrier

from ...constants import ONE_SECOND_IN_NANOSECONDS
from ...utils import is_instrumentation_suppressed, log_internal_error, suppress_instrumentation

# GenAI semantic convention attribute names for span naming
OPERATION_NAME = 'gen_ai.operation.name'
REQUEST_MODEL = 'gen_ai.request.model'

if TYPE_CHECKING:
from ...main import Logfire, LogfireSpan
from .types import EndpointConfig, StreamState
Expand Down Expand Up @@ -132,11 +138,20 @@ def __stream__(self) -> Iterator[Any]:
# In these methods, `*args` is only expected to be `(self,)`
# in the case where we instrument classes rather than client instances.

def _get_otel_span_name(span_data: dict[str, Any]) -> str | None:
"""Construct OTel-compliant span name as '{operation} {model}'."""
operation = span_data.get(OPERATION_NAME)
model = span_data.get(REQUEST_MODEL)
if operation and model:
return f'{operation} {model}'
return None

def instrumented_llm_request_sync(*args: Any, **kwargs: Any) -> Any:
message_template, span_data, kwargs = _instrumentation_setup(*args, **kwargs)
if message_template is None:
return original_request_method(*args, **kwargs)
with logfire_llm.span(message_template, **span_data) as span:
span_name = _get_otel_span_name(span_data)
with logfire_llm.span(message_template, _span_kind=SpanKind.CLIENT, _span_name=span_name, **span_data) as span:
with maybe_suppress_instrumentation(suppress_otel):
if kwargs.get('stream'):
return original_request_method(*args, **kwargs)
Expand All @@ -148,7 +163,8 @@ async def instrumented_llm_request_async(*args: Any, **kwargs: Any) -> Any:
message_template, span_data, kwargs = _instrumentation_setup(*args, **kwargs)
if message_template is None:
return await original_request_method(*args, **kwargs)
with logfire_llm.span(message_template, **span_data) as span:
span_name = _get_otel_span_name(span_data)
with logfire_llm.span(message_template, _span_kind=SpanKind.CLIENT, _span_name=span_name, **span_data) as span:
with maybe_suppress_instrumentation(suppress_otel):
if kwargs.get('stream'):
return await original_request_method(*args, **kwargs)
Expand Down
45 changes: 32 additions & 13 deletions logfire/_internal/integrations/llm_providers/openai.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,31 +37,37 @@ def get_endpoint_config(options: FinalRequestOptions) -> EndpointConfig:
"""Returns the endpoint config for OpenAI depending on the url."""
url = options.url

json_data = options.json_data
if not isinstance(json_data, dict): # pragma: no cover
raw_json_data = options.json_data
if not isinstance(raw_json_data, dict): # pragma: no cover
# Ensure that `{request_data[model]!r}` doesn't raise an error, just a warning about `model` missing.
json_data = {}
raw_json_data = {}
json_data = cast('dict[str, Any]', raw_json_data)

if url == '/chat/completions':
if is_current_agent_span('Chat completion with {gen_ai.request.model!r}'):
return EndpointConfig(message_template='', span_data={})

return EndpointConfig(
message_template='Chat Completion with {request_data[model]!r}',
span_data={'request_data': json_data, 'gen_ai.request.model': json_data['model']},
span_data={
'request_data': json_data,
'gen_ai.request.model': json_data.get('model'),
'gen_ai.operation.name': 'chat',
},
stream_state_cls=OpenaiChatCompletionStreamState,
)
elif url == '/responses':
if is_current_agent_span('Responses API', 'Responses API with {gen_ai.request.model!r}'):
return EndpointConfig(message_template='', span_data={})

stream = json_data.get('stream', False) # type: ignore
stream = json_data.get('stream', False)
span_data: dict[str, Any] = {
'gen_ai.request.model': json_data['model'],
'request_data': {'model': json_data['model'], 'stream': stream},
'gen_ai.request.model': json_data.get('model'),
'gen_ai.operation.name': 'chat',
'request_data': {'model': json_data.get('model'), 'stream': stream},
'events': inputs_to_events(
json_data['input'], # type: ignore
json_data.get('instructions'), # type: ignore
json_data.get('input'),
json_data.get('instructions'),
),
}

Expand All @@ -73,18 +79,30 @@ def get_endpoint_config(options: FinalRequestOptions) -> EndpointConfig:
elif url == '/completions':
return EndpointConfig(
message_template='Completion with {request_data[model]!r}',
span_data={'request_data': json_data, 'gen_ai.request.model': json_data['model']},
span_data={
'request_data': json_data,
'gen_ai.request.model': json_data.get('model'),
'gen_ai.operation.name': 'text_completion',
},
stream_state_cls=OpenaiCompletionStreamState,
)
elif url == '/embeddings':
return EndpointConfig(
message_template='Embedding Creation with {request_data[model]!r}',
span_data={'request_data': json_data, 'gen_ai.request.model': json_data['model']},
span_data={
'request_data': json_data,
'gen_ai.request.model': json_data.get('model'),
'gen_ai.operation.name': 'embeddings',
},
)
elif url == '/images/generations':
return EndpointConfig(
message_template='Image Generation with {request_data[model]!r}',
span_data={'request_data': json_data, 'gen_ai.request.model': json_data['model']},
span_data={
'request_data': json_data,
'gen_ai.request.model': json_data.get('model'),
'gen_ai.operation.name': 'image_generation',
},
)
else:
span_data = {'request_data': json_data, 'url': url}
Expand Down Expand Up @@ -183,7 +201,8 @@ def on_response(response: ResponseT, span: LogfireSpan) -> ResponseT:
on_response(response.parse(), span) # type: ignore
return cast('ResponseT', response)

span.set_attribute('gen_ai.system', 'openai')
# Note: gen_ai.system is deprecated in favor of gen_ai.provider.name
# It was removed as a breaking change for OTel GenAI semantic convention compliance

if isinstance(response_model := getattr(response, 'model', None), str):
span.set_attribute('gen_ai.response.model', response_model)
Expand Down
22 changes: 16 additions & 6 deletions logfire/_internal/main.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
from opentelemetry.context import Context
from opentelemetry.metrics import CallbackT, Counter, Histogram, UpDownCounter
from opentelemetry.sdk.trace import ReadableSpan, Span
from opentelemetry.trace import SpanContext
from opentelemetry.trace import SpanContext, SpanKind
from opentelemetry.util import types as otel_types
from typing_extensions import LiteralString, ParamSpec

Expand Down Expand Up @@ -188,6 +188,7 @@ def _span(
_span_name: str | None = None,
_level: LevelName | int | None = None,
_links: Sequence[tuple[SpanContext, otel_types.Attributes]] = (),
_span_kind: SpanKind | None = None,
) -> LogfireSpan:
try:
if _level is not None:
Expand Down Expand Up @@ -243,6 +244,7 @@ def _span(
self._spans_tracer,
json_schema_properties,
links=_links,
span_kind=_span_kind,
)
except Exception:
log_internal_error()
Expand Down Expand Up @@ -540,6 +542,7 @@ def span(
_span_name: str | None = None,
_level: LevelName | None = None,
_links: Sequence[tuple[SpanContext, otel_types.Attributes]] = (),
_span_kind: SpanKind | None = None,
**attributes: Any,
) -> LogfireSpan:
"""Context manager for creating a span.
Expand All @@ -559,6 +562,7 @@ def span(
_tags: An optional sequence of tags to include in the span.
_level: An optional log level name.
_links: An optional sequence of links to other spans. Each link is a tuple of a span context and attributes.
_span_kind: An optional span kind (e.g., SpanKind.CLIENT for external calls).
attributes: The arguments to include in the span and format the message template with.
Attributes starting with an underscore are not allowed.
"""
Expand All @@ -571,6 +575,7 @@ def span(
_span_name=_span_name,
_level=_level,
_links=_links,
_span_kind=_span_kind,
)

@overload
Expand Down Expand Up @@ -2382,12 +2387,14 @@ def __init__(
tracer: _ProxyTracer,
json_schema_properties: JsonSchemaProperties,
links: Sequence[tuple[SpanContext, otel_types.Attributes]],
span_kind: SpanKind | None = None,
) -> None:
self._span_name = span_name
self._otlp_attributes = otlp_attributes
self._tracer = tracer
self._json_schema_properties = json_schema_properties
self._links = list(trace_api.Link(context=context, attributes=attributes) for context, attributes in links)
self._span_kind = span_kind

self._added_attributes = False
self._token: None | Token[Context] = None
Expand All @@ -2402,11 +2409,14 @@ def __getattr__(self, name: str) -> Any:
def _start(self):
if self._span is not None:
return
self._span = self._tracer.start_span(
name=self._span_name,
attributes=self._otlp_attributes,
links=self._links,
)
kwargs: dict[str, Any] = {
'name': self._span_name,
'attributes': self._otlp_attributes,
'links': self._links,
}
if self._span_kind is not None:
kwargs['kind'] = self._span_kind
self._span = self._tracer.start_span(**kwargs)

@handle_internal_errors
def _attach(self):
Expand Down
Loading
Loading