Add OTel GenAI semantic convention attributes to LLM instrumentations

logfire/_internal/integrations/llm_providers/anthropic.py

@@ -1,12 +1,22 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+import json
+from typing import TYPE_CHECKING, Any, cast
 
 import anthropic
 from anthropic.types import Message, TextBlock, TextDelta
 
 from logfire._internal.utils import handle_internal_errors
 
+from .semconv import (
+    PROVIDER_NAME,
+    REQUEST_MAX_TOKENS,
+    REQUEST_STOP_SEQUENCES,
+    REQUEST_TEMPERATURE,
+    REQUEST_TOP_K,
+    REQUEST_TOP_P,
+    TOOL_DEFINITIONS,
+)
 from .types import EndpointConfig, StreamState
 
 if TYPE_CHECKING:
@@ -22,24 +32,57 @@
 )
 
 
+def _extract_request_parameters(json_data: dict[str, Any], span_data: dict[str, Any]) -> None:
+    """Extract request parameters from json_data and add to span_data."""
+    if (max_tokens := json_data.get('max_tokens')) is not None:
+        span_data[REQUEST_MAX_TOKENS] = max_tokens
+
+    if (temperature := json_data.get('temperature')) is not None:
+        span_data[REQUEST_TEMPERATURE] = temperature
+
+    if (top_p := json_data.get('top_p')) is not None:
+        span_data[REQUEST_TOP_P] = top_p
+
+    if (top_k := json_data.get('top_k')) is not None:
+        span_data[REQUEST_TOP_K] = top_k
+
+    if (stop_sequences := json_data.get('stop_sequences')) is not None:
+        span_data[REQUEST_STOP_SEQUENCES] = json.dumps(stop_sequences)
+
+    if (tools := json_data.get('tools')) is not None:
+        span_data[TOOL_DEFINITIONS] = json.dumps(tools)
+
+
 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':
+        span_data: dict[str, Any] = {
+            'request_data': json_data,
+            PROVIDER_NAME: 'anthropic',
+        }
+        _extract_request_parameters(json_data, span_data)
+
         return EndpointConfig(
             message_template='Message with {request_data[model]!r}',
-            span_data={'request_data': json_data},
+            span_data=span_data,
             stream_state_cls=AnthropicMessageStreamState,
         )
     else:
+        span_data = {
+            'request_data': json_data,
+            'url': url,
+            PROVIDER_NAME: 'anthropic',
+        }
         return EndpointConfig(
             message_template='Anthropic API call to {url!r}',
-            span_data={'request_data': json_data, 'url': url},
+            span_data=span_data,
         )
 
 

logfire/_internal/integrations/llm_providers/llm_provider.py

@@ -4,6 +4,8 @@
 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
 
@@ -136,7 +138,7 @@ 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:
+        with logfire_llm.span(message_template, _span_kind=SpanKind.CLIENT, **span_data) as span:
             with maybe_suppress_instrumentation(suppress_otel):
                 if kwargs.get('stream'):
                     return original_request_method(*args, **kwargs)
@@ -148,7 +150,7 @@ 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:
+        with logfire_llm.span(message_template, _span_kind=SpanKind.CLIENT, **span_data) as span:
             with maybe_suppress_instrumentation(suppress_otel):
                 if kwargs.get('stream'):
                     return await original_request_method(*args, **kwargs)

logfire/_internal/integrations/llm_providers/openai.py

@@ -18,6 +18,17 @@
 from logfire import LogfireSpan
 
 from ...utils import handle_internal_errors, log_internal_error
+from .semconv import (
+    PROVIDER_NAME,
+    REQUEST_FREQUENCY_PENALTY,
+    REQUEST_MAX_TOKENS,
+    REQUEST_PRESENCE_PENALTY,
+    REQUEST_SEED,
+    REQUEST_STOP_SEQUENCES,
+    REQUEST_TEMPERATURE,
+    REQUEST_TOP_P,
+    TOOL_DEFINITIONS,
+)
 from .types import EndpointConfig, StreamState
 
 if TYPE_CHECKING:
@@ -33,61 +44,122 @@
 )
 
 
+def _extract_request_parameters(json_data: dict[str, Any], span_data: dict[str, Any]) -> None:
+    """Extract request parameters from json_data and add to span_data."""
+    if (max_tokens := json_data.get('max_tokens')) is not None:
+        span_data[REQUEST_MAX_TOKENS] = max_tokens
+    elif (max_output_tokens := json_data.get('max_output_tokens')) is not None:
+        span_data[REQUEST_MAX_TOKENS] = max_output_tokens
+
+    if (temperature := json_data.get('temperature')) is not None:
+        span_data[REQUEST_TEMPERATURE] = temperature
+
+    if (top_p := json_data.get('top_p')) is not None:
+        span_data[REQUEST_TOP_P] = top_p
+
+    if (stop := json_data.get('stop')) is not None:
+        if isinstance(stop, str):
+            span_data[REQUEST_STOP_SEQUENCES] = json.dumps([stop])
+        else:
+            span_data[REQUEST_STOP_SEQUENCES] = json.dumps(stop)
+
+    if (seed := json_data.get('seed')) is not None:
+        span_data[REQUEST_SEED] = seed
+
+    if (frequency_penalty := json_data.get('frequency_penalty')) is not None:
+        span_data[REQUEST_FREQUENCY_PENALTY] = frequency_penalty
+
+    if (presence_penalty := json_data.get('presence_penalty')) is not None:
+        span_data[REQUEST_PRESENCE_PENALTY] = presence_penalty
+
+    if (tools := json_data.get('tools')) is not None:
+        span_data[TOOL_DEFINITIONS] = json.dumps(tools)
+
+
 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={})
 
+        span_data: dict[str, Any] = {
+            'request_data': json_data,
+            'gen_ai.request.model': json_data.get('model'),
+            PROVIDER_NAME: 'openai',
+        }
+        _extract_request_parameters(json_data, 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=span_data,
             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
-        span_data: dict[str, Any] = {
-            'gen_ai.request.model': json_data['model'],
-            'request_data': {'model': json_data['model'], 'stream': stream},
+        stream = json_data.get('stream', False)
+        span_data = {
+            'gen_ai.request.model': json_data.get('model'),
+            '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'),
             ),
+            PROVIDER_NAME: 'openai',
         }
+        _extract_request_parameters(json_data, span_data)
 
         return EndpointConfig(
             message_template='Responses API with {gen_ai.request.model!r}',
             span_data=span_data,
             stream_state_cls=OpenaiResponsesStreamState,
         )
     elif url == '/completions':
+        span_data = {
+            'request_data': json_data,
+            'gen_ai.request.model': json_data.get('model'),
+            PROVIDER_NAME: 'openai',
+        }
         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=span_data,
             stream_state_cls=OpenaiCompletionStreamState,
         )
     elif url == '/embeddings':
+        span_data = {
+            'request_data': json_data,
+            'gen_ai.request.model': json_data.get('model'),
+            PROVIDER_NAME: 'openai',
+        }
         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=span_data,
         )
     elif url == '/images/generations':
+        span_data = {
+            'request_data': json_data,
+            'gen_ai.request.model': json_data.get('model'),
+            PROVIDER_NAME: 'openai',
+        }
         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=span_data,
         )
     else:
-        span_data = {'request_data': json_data, 'url': url}
+        span_data = {
+            'request_data': json_data,
+            'url': url,
+            PROVIDER_NAME: 'openai',
+        }
         if 'model' in json_data:
             span_data['gen_ai.request.model'] = json_data['model']
         return EndpointConfig(

logfire/_internal/integrations/llm_providers/semconv.py

@@ -0,0 +1,44 @@
+"""Gen AI Semantic Convention attribute names.
+
+These constants follow the OpenTelemetry Gen AI Semantic Conventions.
+See: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+"""
+
+from __future__ import annotations
+
+# Provider and operation
+PROVIDER_NAME = 'gen_ai.provider.name'
+OPERATION_NAME = 'gen_ai.operation.name'
+
+# Model information
+REQUEST_MODEL = 'gen_ai.request.model'
+RESPONSE_MODEL = 'gen_ai.response.model'
+
+# Request parameters
+REQUEST_MAX_TOKENS = 'gen_ai.request.max_tokens'
+REQUEST_TEMPERATURE = 'gen_ai.request.temperature'
+REQUEST_TOP_P = 'gen_ai.request.top_p'
+REQUEST_TOP_K = 'gen_ai.request.top_k'
+REQUEST_STOP_SEQUENCES = 'gen_ai.request.stop_sequences'
+REQUEST_SEED = 'gen_ai.request.seed'
+REQUEST_FREQUENCY_PENALTY = 'gen_ai.request.frequency_penalty'
+REQUEST_PRESENCE_PENALTY = 'gen_ai.request.presence_penalty'
+
+# Response metadata
+RESPONSE_ID = 'gen_ai.response.id'
+RESPONSE_FINISH_REASONS = 'gen_ai.response.finish_reasons'
+
+# Token usage
+INPUT_TOKENS = 'gen_ai.usage.input_tokens'
+OUTPUT_TOKENS = 'gen_ai.usage.output_tokens'
+
+# Message content
+INPUT_MESSAGES = 'gen_ai.input.messages'
+OUTPUT_MESSAGES = 'gen_ai.output.messages'
+SYSTEM_INSTRUCTIONS = 'gen_ai.system_instructions'
+
+# Tool definitions
+TOOL_DEFINITIONS = 'gen_ai.tool.definitions'
+
+# Conversation tracking
+CONVERSATION_ID = 'gen_ai.conversation.id'

logfire/_internal/main.py

@@ -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
 
@@ -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:
@@ -243,6 +244,7 @@ def _span(
                 self._spans_tracer,
                 json_schema_properties,
                 links=_links,
+                span_kind=_span_kind,
             )
         except Exception:
             log_internal_error()
@@ -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.
@@ -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: The span kind. If not provided, defaults to INTERNAL.
             attributes: The arguments to include in the span and format the message template with.
                 Attributes starting with an underscore are not allowed.
         """
@@ -571,6 +575,7 @@ def span(
             _span_name=_span_name,
             _level=_level,
             _links=_links,
+            _span_kind=_span_kind,
         )
 
     @overload
@@ -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
@@ -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):