gestalt.telemetry

OpenTelemetry helpers for provider-authored GenAI instrumentation.

The Gestalt runtime configures exporters from host-provided OTEL_* environment before a provider starts serving. Provider code should use this module to create GenAI semantic-convention spans and metrics around the model, agent, and tool work it owns.

class Operation(*, span_name, span_kind, span_attrs, metric_attrs)

Bases: object

Context manager that records a GenAI span plus duration and token metrics.

Parameters:

  • span_name (str)

  • span_kind (SpanKind)

  • span_attrs (Mapping[str, Any])

  • metric_attrs (Mapping[str, Any])

mark_error(error_type, description='', *, exc=None)

Mark the operation span and duration metric as failed.

Parameters:

  • error_type (str)

  • description (str)

  • exc (BaseException | None)

Return type:

None

set_attribute(key, value)

Set a span attribute when the value is valid for OpenTelemetry.

Parameters:

  • key (str)

  • value (Any)

Return type:

None

set_response_metadata(response, *, finish_reasons=None)

Attach common model response metadata to the current span.

Parameters:

  • response (Any)

  • finish_reasons (list[str] | None)

Return type:

None

record_usage(*, input_tokens=None, output_tokens=None, cache_creation_input_tokens=None, cache_read_input_tokens=None, reasoning_output_tokens=None)

Record token usage on the span and token-usage metric.

Parameters:

  • input_tokens (Any)

  • output_tokens (Any)

  • cache_creation_input_tokens (Any)

  • cache_read_input_tokens (Any)

  • reasoning_output_tokens (Any)

Return type:

None

agent_invocation(*, agent_name, session_id, turn_id, model)

Create a GenAI agent invocation operation for a provider-owned turn.

Parameters:

  • agent_name (str)

  • session_id (str)

  • turn_id (str)

  • model (str)

Return type:

Operation

configure_from_environment(*, service_name='gestalt-provider')

Configure OpenTelemetry exporters from standard OTEL environment variables.

Parameters:

service_name (str)

Return type:

None

model_operation(*, provider_name, request_model, request_options=None, request_attrs=None)

Create a GenAI chat/model operation around an upstream model SDK call.

Parameters:

  • provider_name (str)

  • request_model (str)

  • request_options (Mapping[str, Any] | None)

  • request_attrs (Mapping[str, Any] | None)

Return type:

Operation

record_anthropic_usage(operation, response)

Record token usage fields from an Anthropic SDK response.

Parameters:
Return type:

None

record_openai_usage(operation, response)

Record token usage fields from an OpenAI SDK response.

Parameters:
Return type:

None

shutdown()

Flush and shut down configured OpenTelemetry providers.

Return type:

None

tool_execution(*, tool_name, tool_call_id='', tool_type=GENAI_TOOL_TYPE_EXTENSION)

Create a GenAI tool execution operation.

Parameters:

  • tool_name (str)

  • tool_call_id (str)

  • tool_type (str)

Return type:

Operation