InferenceScope Class

Provides OpenTelemetry tracing scope for generative AI inference operations.

Constructor

InferenceScope()

Parameters

Name	Description
request Required
details Required
agent_details Required
user_details	Default value: None
span_details	Default value: None

Methods

__init__	Initialize the inference scope.
__new__
dispose	Dispose the scope and finalize telemetry data collection.
get_context	Get the OpenTelemetry context for this scope's span. This method returns a Context object containing this scope's span, which can be used to propagate trace context to child operations or downstream services.
inject_context_to_headers	Inject this span's trace context into W3C HTTP headers. Returns a dictionary of headers containing traceparent and optionally tracestate that can be forwarded to downstream services or stored for later context propagation. Example usage: scope = OpenTelemetryScope(...) headers = scope.inject_context_to_headers() # Add headers to outgoing HTTP request requests.get("https://downstream-service/api", headers=headers)
record_attributes	Record multiple attribute key/value pairs for telemetry tracking. This method allows setting multiple custom attributes on the span at once.
record_cancellation	Record task cancellation.
record_error	Record an error in the span.
record_finish_reasons	Records the finish reasons for telemetry tracking.
record_input_messages	Records the input messages for telemetry tracking. Accepts plain strings (auto-wrapped as OTEL ChatMessage with role user) or a versioned InputMessages wrapper.
record_input_tokens	Records the number of input tokens for telemetry tracking.
record_output_messages	Records the output messages for telemetry tracking. Accepts plain strings (auto-wrapped as OTEL OutputMessage with role assistant) or a versioned OutputMessages wrapper.
record_output_tokens	Records the number of output tokens for telemetry tracking.
record_response	Record an response in the span.
record_thought_process	Records the thought process.
set_end_time	Set a custom end time for the scope. When set, dispose() will pass this value to span.end() instead of using the current wall-clock time. This is useful when the actual end time of the operation is known before the scope is disposed.
set_tag_maybe	Set a tag on the span if the value is not None.
start	Creates and starts a new scope for inference tracing.

__init__

Initialize the inference scope.

__init__(request: Request, details: InferenceCallDetails, agent_details: AgentDetails, user_details: UserDetails | None = None, span_details: SpanDetails | None = None)

Parameters

Name	Description
request Required	Request Request details for the inference
details Required	InferenceCallDetails The details of the inference call
agent_details Required	AgentDetails The details of the agent making the call
user_details	UserDetails | None Optional human user details Default value: None
span_details	SpanDetails | None Optional span configuration (parent context, timing) Default value: None

__new__

__new__(**kwargs)

dispose

Dispose the scope and finalize telemetry data collection.

dispose() -> None

Returns

Type	Description
None

get_context

Get the OpenTelemetry context for this scope's span.

This method returns a Context object containing this scope's span, which can be used to propagate trace context to child operations or downstream services.

get_context() -> Context | None

Returns

Type	Description
Context | None	A Context containing this scope's span, or None if telemetry is disabled or no span exists.

inject_context_to_headers

Inject this span's trace context into W3C HTTP headers.

Returns a dictionary of headers containing traceparent and optionally tracestate that can be forwarded to downstream services or stored for later context propagation.

Example usage:

   scope = OpenTelemetryScope(...)
   headers = scope.inject_context_to_headers()
   # Add headers to outgoing HTTP request
   requests.get("https://downstream-service/api", headers=headers)

inject_context_to_headers() -> dict[str, str]

Returns

Type	Description
dict[str, str]	A dictionary containing W3C trace context headers. Returns an empty dictionary if telemetry is disabled or no span exists.

record_attributes

Record multiple attribute key/value pairs for telemetry tracking.

This method allows setting multiple custom attributes on the span at once.

record_attributes(attributes: dict[str, Any] | list[tuple[str, Any]]) -> None

Parameters

Name	Description
attributes Required	dict[str, Any] | list[tuple[str, Any]] Dictionary or list of tuples containing attribute key-value pairs. Keys that are None or empty will be skipped.

Returns

Type	Description
None

record_cancellation

Record task cancellation.

record_cancellation() -> None

Returns

Type	Description
None

record_error

Record an error in the span.

record_error(exception: Exception) -> None

Parameters

Name	Description
exception Required	Exception The exception that occurred

Returns

Type	Description
None

record_finish_reasons

Records the finish reasons for telemetry tracking.

record_finish_reasons(finish_reasons: List[str]) -> None

Parameters

Name	Description
finish_reasons Required	List[str] List of finish reasons

Returns

Type	Description
None

record_input_messages

Records the input messages for telemetry tracking.

Accepts plain strings (auto-wrapped as OTEL ChatMessage with role user) or a versioned InputMessages wrapper.

record_input_messages(messages: str | list[str] | InputMessages) -> None

Parameters

Name	Description
messages Required	str | list[str] | InputMessages List of input message strings or an InputMessages wrapper

Returns

Type	Description
None

record_input_tokens

Records the number of input tokens for telemetry tracking.

record_input_tokens(input_tokens: int) -> None

Parameters

Name	Description
input_tokens Required	int Number of input tokens

Returns

Type	Description
None

record_output_messages

Records the output messages for telemetry tracking.

Accepts plain strings (auto-wrapped as OTEL OutputMessage with role assistant) or a versioned OutputMessages wrapper.

record_output_messages(messages: str | list[str] | OutputMessages) -> None

Parameters

Name	Description
messages Required	str | list[str] | OutputMessages List of output message strings or an OutputMessages wrapper

Returns

Type	Description
None

record_output_tokens

Records the number of output tokens for telemetry tracking.

record_output_tokens(output_tokens: int) -> None

Parameters

Name	Description
output_tokens Required	int Number of output tokens

Returns

Type	Description
None

record_response

Record an response in the span.

record_response(response: str) -> None

Parameters

Name	Description
response Required	str The response content to record

Returns

Type	Description
None

record_thought_process

Records the thought process.

record_thought_process(thought_process: str) -> None

Parameters

Name	Description
thought_process Required	str The thought process to record

Returns

Type	Description
None

set_end_time

Set a custom end time for the scope.

When set, dispose() will pass this value to span.end() instead of using the current wall-clock time. This is useful when the actual end time of the operation is known before the scope is disposed.

set_end_time(end_time: datetime) -> None

Parameters

Name	Description
end_time Required	datetime The end time as a datetime object.

Returns

Type	Description
None

set_tag_maybe

Set a tag on the span if the value is not None.

set_tag_maybe(name: str, value: Any) -> None

Parameters

Name	Description
name Required	str The name of the tag
value Required	Any The value to set (will be skipped if None)

Returns

Type	Description
None

start

Creates and starts a new scope for inference tracing.

static start(request: Request, details: InferenceCallDetails, agent_details: AgentDetails, user_details: UserDetails | None = None, span_details: SpanDetails | None = None) -> InferenceScope

Parameters

Name	Description
request Required	Request Request details for the inference
details Required	InferenceCallDetails The details of the inference call
agent_details Required	AgentDetails The details of the agent making the call
user_details	UserDetails | None Optional human user details Default value: None
span_details	SpanDetails | None Optional span configuration (parent context, timing) Default value: None

Returns

Type	Description
InferenceScope	A new InferenceScope instance