OpenTelemetry Python - GenAI Util

opentelemetry.util.genai.utils.is_experimental_mode()[source]

Return type:: bool

opentelemetry.util.genai.utils.get_content_capturing_mode()[source]

This function should not be called when GEN_AI stability mode is set to DEFAULT.

When the GEN_AI stability mode is DEFAULT this function will raise a ValueError – see the code below.

Return type:: ContentCapturingMode

opentelemetry.util.genai.utils.should_emit_event()[source]

Check if event emission is enabled.

Returns True if event emission is enabled, False otherwise.

If the environment variable OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT is explicitly set, its value takes precedence. Otherwise, the default value is determined by OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: - NO_CONTENT or SPAN_ONLY: defaults to False - EVENT_ONLY or SPAN_AND_EVENT: defaults to True

Return type:: bool

opentelemetry.util.genai.utils.should_capture_content_on_spans_in_experimental_mode()[source]

Return True when content conversion should be performed.

Return type:: bool

opentelemetry.util.genai.utils.gen_ai_json_dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=<class 'opentelemetry.util.genai.utils._GenAiJsonEncoder'>, indent=None, separators=(', ', ':'), default=None, sort_keys=False, **kw): Should be used by GenAI instrumentations when serializing objects that may contain bytes, datetimes, etc. for GenAI observability.

opentelemetry.util.genai.utils.gen_ai_json_dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=<class 'opentelemetry.util.genai.utils._GenAiJsonEncoder'>, indent=None, separators=(', ', ':'), default=None, sort_keys=False, **kw): Should be used by GenAI instrumentations when serializing objects that may contain bytes, datetimes, etc. for GenAI observability.

class opentelemetry.util.genai.types.ContentCapturingMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

NO_CONTENT = 0

SPAN_ONLY = 1

EVENT_ONLY = 2

SPAN_AND_EVENT = 3

class opentelemetry.util.genai.types.GenericPart(value, type='generic')[source]

Bases: object

Used for provider-specific message part types that don’t match the standard MessagePart types defined in semantic conventions. Wrap custom types with GenericPart(value=…) to explicitly opt-in to non-standard types. This will be removed in a future version when all instrumentations use core types.

value: Any

type: Literal['generic'] = 'generic'

class opentelemetry.util.genai.types.ToolCallRequest(arguments, name, id, type='tool_call')[source]

Bases: object

Represents a tool call requested by the model (message part only).

Use this for tool calls in message history. For execution tracking with spans and metrics, use ToolInvocation instead.

This model is specified as part of semconv in GenAI messages Python models - ToolCallRequestPart.

arguments: Any

name: str

id: Optional[str]

type: Literal['tool_call'] = 'tool_call'

class opentelemetry.util.genai.types.ToolCallResponse(response, id, type='tool_call_response')[source]

Bases: object

Represents a tool call result sent to the model or a built-in tool call outcome and details

This model is specified as part of semconv in GenAI messages Python models - ToolCallResponsePart.

response: Any

id: Optional[str]

type: Literal['tool_call_response'] = 'tool_call_response'

class opentelemetry.util.genai.types.ServerToolCall(name, server_tool_call, id=None, type='server_tool_call')[source]

Bases: object

Represents a server-side tool call.

Server tool calls are executed by the model provider on the server side rather than by the client application. Provider-specific tools (e.g., code_interpreter, web_search) can have well-defined schemas defined by the respective providers.

This model is specified as part of semconv in GenAI messages Python models - ServerToolCallPart.

name: str

server_tool_call: Any

id: Optional[str] = None

type: Literal['server_tool_call'] = 'server_tool_call'

class opentelemetry.util.genai.types.ServerToolCallResponse(server_tool_call_response, id=None, type='server_tool_call_response')[source]

Bases: object

Represents a server-side tool call response.

Contains the outcome and details of a server tool execution. Provider-specific tools (e.g., code_interpreter, web_search) can have well-defined response schemas defined by the respective providers.

This model is specified as part of semconv in GenAI messages Python models - ServerToolCallResponsePart.

server_tool_call_response: Any

id: Optional[str] = None

type: Literal['server_tool_call_response'] = 'server_tool_call_response'

class opentelemetry.util.genai.types.Text(content, type='text')[source]

Bases: object

Represents text content sent to or received from the model

This model is specified as part of semconv in GenAI messages Python models - TextPart.

content: str

type: Literal['text'] = 'text'

class opentelemetry.util.genai.types.Reasoning(content, type='reasoning')[source]

Bases: object

Represents reasoning/thinking content received from the model

This model is specified as part of semconv in GenAI messages Python models - ReasoningPart.

content: str

type: Literal['reasoning'] = 'reasoning'

class opentelemetry.util.genai.types.Blob(mime_type, modality, content, type='blob')[source]

Bases: object

Represents blob binary data sent inline to the model

This model is specified as part of semconv in GenAI messages Python models - BlobPart.

mime_type: Optional[str]

modality: Union[Literal['image', 'video', 'audio'], str]

content: bytes

type: Literal['blob'] = 'blob'

class opentelemetry.util.genai.types.File(mime_type, modality, file_id, type='file')[source]

Bases: object

Represents an external referenced file sent to the model by file id

This model is specified as part of semconv in GenAI messages Python models - FilePart.

mime_type: Optional[str]

modality: Union[Literal['image', 'video', 'audio'], str]

file_id: str

type: Literal['file'] = 'file'

class opentelemetry.util.genai.types.Uri(mime_type, modality, uri, type='uri')[source]

Bases: object

Represents an external referenced file sent to the model by URI

This model is specified as part of semconv in GenAI messages Python models - UriPart.

mime_type: Optional[str]

modality: Union[Literal['image', 'video', 'audio'], str]

uri: str

type: Literal['uri'] = 'uri'

class opentelemetry.util.genai.types.FunctionToolDefinition(name, description, parameters, type='function')[source]

Bases: object

Represents a function tool definition sent to the model

name: str

description: Optional[str]

parameters: Any

type: Literal['function'] = 'function'

class opentelemetry.util.genai.types.GenericToolDefinition(name, type)[source]

Bases: object

Represents a generic tool definition sent to the model

name: str

type: str

class opentelemetry.util.genai.types.InputMessage(role, parts)[source]

Bases: object

role: str

parts: list[Union[Text, ToolCallRequest, ToolCallResponse, ServerToolCall, ServerToolCallResponse, Blob, File, Uri, Reasoning, GenericPart]]

class opentelemetry.util.genai.types.OutputMessage(role, parts, finish_reason)[source]

Bases: object

role: str

parts: list[Union[Text, ToolCallRequest, ToolCallResponse, ServerToolCall, ServerToolCallResponse, Blob, File, Uri, Reasoning, GenericPart]]

finish_reason: Union[str, Literal['content_filter', 'error', 'length', 'stop', 'tool_calls']]

class opentelemetry.util.genai.types.Error(message, type)[source]

Bases: object

message: str

type: Type[BaseException]

opentelemetry.util.genai.environment_variables.OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT = 'OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT'

OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT

Controls whether to emit gen_ai.client.inference.operation.details events. Must be one of true or false (case-insensitive). Defaults to false.

opentelemetry.util.genai.environment_variables.OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK = 'OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK'

OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK

opentelemetry.util.genai.environment_variables.OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH = 'OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH'

OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH

An fsspec.open() compatible URI/path for uploading prompts and responses. Can be a local path like /path/to/prompts or a cloud storage URI such as gs://my_bucket. For more information, see

Instantiate a file-system for supported values and how to install support for additional backend implementations.
Configuration for configuring a backend with environment variables.

opentelemetry.util.genai.environment_variables.OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT = 'OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT'

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT

The format to use when uploading prompt and response data. Must be one of json or jsonl. Defaults to json.

opentelemetry.util.genai.environment_variables.OTEL_INSTRUMENTATION_GENAI_UPLOAD_MAX_QUEUE_SIZE = 'OTEL_INSTRUMENTATION_GENAI_UPLOAD_MAX_QUEUE_SIZE'

OTEL_INSTRUMENTATION_GENAI_UPLOAD_MAX_QUEUE_SIZE

The maximum number of concurrent uploads to queue. New uploads will be dropped if the queue is full. Defaults to 20.

This module defines the generic hooks for GenAI content completion

The hooks are specified as part of semconv in Uploading content to external storage.

This module defines the CompletionHook type that custom implementations should implement, and a load_completion_hook function to load it from an entry point.

class opentelemetry.util.genai.completion_hook.CompletionHook(*args, **kwargs)[source]

Bases: Protocol

A hook to be called on completion of a GenAI operation.

This is the interface for a hook that can be used to capture GenAI content on completion. The hook is a callable that takes the inputs, outputs, and system instruction of a GenAI interaction, as well as the span and log record associated with it.

The hook can be used to upload the content to any external storage, such as a database, a file system, or a cloud storage service.

The span and log_record arguments should be provided based on the content capturing mode get_content_capturing_mode().

Note

Hooks returned from load_completion_hook() are wrapped so any exception raised by on_completion() is logged and swallowed. Instrumentation code calling on_completion on a hook obtained from load_completion_hook() does not need a try/except around the call - exceptions never escape into the instrumented application.

Parameters:

inputs – The inputs of the GenAI interaction.
outputs – The outputs of the GenAI interaction.
system_instruction – The system instruction of the GenAI interaction.
tool_definitions – The list of source system tool definitions available to the GenAI agent or model.
span – The span associated with the GenAI interaction.
log_record – The event log associated with the GenAI interaction.

on_completion(*, inputs, outputs, system_instruction, tool_definitions=None, span=None, log_record=None)[source]

Return type:: None

opentelemetry.util.genai.completion_hook.load_completion_hook()[source]

Load the completion hook from entry point or return a noop implementation

This function loads an completion hook from the entry point group opentelemetry_genai_completion_hook with name coming from OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK. If one can’t be found, returns a no-op implementation.

The returned hook wraps the user-provided implementation so any exception raised by on_completion is logged and swallowed.

Return type:: CompletionHook

opentelemetry.util.genai._upload.upload_completion_hook()[source]

Return type:: CompletionHook