enterprise_ai.telemetry
Source: sdks/python/src/enterprise_ai/telemetry/__init__.py. Back to the Python SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Model SpanRecord
A finished span in the fallback exporter format.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
name | str | yes | Name of the span. |
trace_id | str | yes | W3C trace id, 32 lowercase hexadecimal characters, to correlate the event with a trace. |
span_id | str | yes | Identifier of the span, 16 random hexadecimal characters. |
parent_span_id | str | None | yes | Identifier of the parent span (16 hexadecimal characters), or None for a root span. |
start_time_unix_nano | int | yes | Start time in nanoseconds since the Unix epoch. |
end_time_unix_nano | int | no | End time in nanoseconds since the Unix epoch; 0 while the span is open. |
attributes | dict[str, Any] | no | Free attributes of the component, such as the provider of a model. |
status | str | no | Status of the span: ok (default) or error. |
events | list[dict[str, Any]] | no | Timed events of the span: name, time_unix_nano, attributes. |
SpanRecord.add_event
add_event(name: str, attributes: dict[str, Any] | None = None) -> None
Append a timed event to the span.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | str | yes | Name of the event. | |
attributes | dict[str, Any] | None | None | no | Attributes of the event; empty by default. |
Returns: None.
SpanRecord.set_attribute
set_attribute(key: str, value: Any) -> None
Set one attribute of the span.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
key | str | yes | Attribute name, such as a gen_ai.* semantic convention name. | |
value | Any | yes | Attribute value; replaces the previous one. |
Returns: None.
SpanRecord.to_dict
to_dict() -> dict[str, Any]
Span as the dict posted to /v1/telemetry/spans.
This element takes no parameter.
Returns: dict[str, Any]. Dict of every field of the span.
Class TelemetryClient
/v1/telemetry.
Resource
TelemetryClient.end_span
end_span(span: SpanRecord, status: str = 'ok') -> Any
Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).
Route: /v1/telemetry/spans (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
span | SpanRecord | yes | Open span returned by start_span; an ended span raises ValueError. | |
status | str | 'ok' | no | Final status of the span: ok (default) or error. |
Returns: Any. Decoded JSON answer of the operation "Ingest telemetry spans".
Raises: ValueError, the typed errors of the transport (Errors).
TelemetryClient.ingest
ingest(spans: list[dict[str, Any]]) -> Any
Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).
Route: /v1/telemetry/spans (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
spans | list[dict[str, Any]] | yes | Spans to send, as dicts in the SpanRecord.to_dict() format. |
Returns: Any. Decoded JSON answer of the operation "Ingest telemetry spans".
Raises: the typed errors of the transport (Errors).
TelemetryClient.logs
logs(**filters: Any) -> Any
List the request journal. Request journal of the tenant from the span summaries, newest first: one line per span with its time, level (error when the span failed, else info), service, name, message (error type, or method, route and status code), duration, trace, span, run and kept attributes. Never a prompt or a model output. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown level or a from after to answers 400 invalid_request.
Route: /v1/telemetry/logs (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**filters | Any | no | Query filters: level (error, info), service, trace_id, q, from, to, limit. |
Returns: Any. Decoded JSON answer of the operation "List the request journal".
Raises: the typed errors of the transport (Errors).
TelemetryClient.overview
overview(**filters: Any) -> Any
Read the telemetry overview. Dashboard of the tenant over the last days days: number of requests (root spans), errors, error rate, p50 and p95 latency in milliseconds, total cost, and per day requests, errors and cost (span costs plus the measured or estimated cost of the LLM usage events). Also says which exporters (Opik, OpenTelemetry, ClickHouse) are configured. The total cost is labelled USD. Requires a tenant principal (403 tenant_required).
Route: /v1/telemetry/overview (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**filters | Any | no | Query parameters sent as is to /v1/telemetry/overview. |
Returns: Any. Decoded JSON answer of the operation "Read the telemetry overview".
Raises: the typed errors of the transport (Errors).
TelemetryClient.record_event
record_event(span: SpanRecord, name: str, attributes: dict[str, Any] | None = None) -> SpanRecord
Add a timed event to an open span (no request).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
span | SpanRecord | yes | Open span; an ended span raises ValueError. | |
name | str | yes | Name of the event. | |
attributes | dict[str, Any] | None | None | no | Attributes of the event; empty by default. |
Returns: SpanRecord. A SpanRecord: A finished span in the fallback exporter format.
Raises: ValueError.
TelemetryClient.set_slo_target
set_slo_target(service: str, availability: float, latency_seconds: float, latency_objective: float, reason: str = '') -> Any
Set the objectives of a service. Objectives of one platform service, written in the database where they override the EAI_SLO_* defaults for every replica within 30 seconds. Platform administrator only (403 forbidden). An unknown service answers 404 slo_service_unknown. The change, with the values before and after and the reason, is audited (telemetry.slo.target.update); the answer gives the stored objectives with their version.
Route: /v1/telemetry/slo/targets/{service} (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
service | str | yes | Service whose objectives are set: control_plane_api, model_gateway, tool_gateway or realtime. | |
availability | float | yes | Availability target: share of requests that must not fail with a 5xx, from 0.5 included to 1 excluded (for example 0.999). | |
latency_seconds | float | yes | Latency target in seconds: a request slower than this counts against the latency objective. Greater than 0, at most 300. | |
latency_objective | float | yes | Share of requests that must be faster than latency_seconds, from 0.5 included to 1 excluded. | |
reason | str | '' | no | Why the objectives change, 500 characters at most, empty by default. Written to the audit trail. |
Returns: Any. Decoded JSON answer of the operation "Set the objectives of a service".
Raises: the typed errors of the transport (Errors).
TelemetryClient.slo
slo(window_minutes: int | None = None, tenant_id: str | None = None) -> Any
Read the SLO error budgets. For each service, over the last window_minutes minutes: requests, errors (5xx), requests over the latency target, the latency target and where it comes from (database or settings), and for availability and latency the target, bad ratio, remaining budget and burn rate. Counts are those of the replica that answers. Requires platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). A platform administrator reads the whole platform or one tenant; anyone else reads only its own tenant (403 slo_scope_forbidden for another one). A window outside 1 to EAI_SLO_RETENTION_MINUTES answers 422 slo_window_invalid. Each read is audited (telemetry.slo.read).
Route: /v1/telemetry/slo (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
window_minutes | int | None | None | no | Length of the window in minutes, default 60, from 1 to the retention EAI_SLO_RETENTION_MINUTES. |
tenant_id | str | None | None | no | Tenant to read. A platform administrator may omit it for the whole platform; any other caller may only give its own tenant. |
Returns: Any. Decoded JSON answer of the operation "Read the SLO error budgets".
Raises: the typed errors of the transport (Errors).
TelemetryClient.start_span
start_span(name: str, attributes: dict[str, Any] | None = None, traceparent: str | None = None) -> SpanRecord
Open an explicit span (no request): child of traceparent or of the current context.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | str | yes | Name of the span. | |
attributes | dict[str, Any] | None | None | no | Initial attributes of the span. |
traceparent | str | None | None | no | W3C traceparent of the parent (00-<trace_id>-<span_id>-<flags>); the current context when omitted, a new trace when none. |
Returns: SpanRecord. A SpanRecord: A finished span in the fallback exporter format.
Raises: ValueError.
TelemetryClient.stream
stream(last_event_id: str | None = None, **params: Any) -> Any
Stream live telemetry events. Server-Sent Events (text/event-stream) of the tenant: a metrics event at every tick (requests, errors, error rate and p95 latency over the last minute), a trace event for every new root span and an incident event for every incident created or changed. Each event carries an id: (a timestamp) the client sends back as Last-Event-ID or since to resume. The stream closes after timeout seconds (the EventSource reconnects after 3 seconds) or after max_events events. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer.
Route: /v1/telemetry/stream (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
last_event_id | str | None | None | no | Identifier of the last event already received, sent as Last-Event-ID to resume the stream. |
**params | Any | no | Extra fields merged into the request. |
Returns: Any. Decoded JSON answer of the operation "Stream live telemetry events".
Raises: the typed errors of the transport (Errors).
TelemetryClient.trace
trace(trace_id: str) -> Any
Get one trace. Every span of the trace in start order (with cost when known), the span count, total duration in milliseconds, error count, the audit events that carry this trace id, and a link to the trace in Opik when Opik is configured. Requires a tenant principal (403 tenant_required). A malformed id answers 400 invalid_request; a trace without span nor audit event answers 404 not_found.
Route: /v1/telemetry/traces/{trace_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
trace_id | str | yes | Trace identifier: 32 hexadecimal characters (W3C trace context), case insensitive. |
Returns: Any. Decoded JSON answer of the operation "Get one trace".
Raises: the typed errors of the transport (Errors).
TelemetryClient.tracer
tracer(service: str = 'enterprise-ai-agent', batch_size: int = 50, use_otel: bool | None = None) -> Tracer
A :class:Tracer exporting through OpenTelemetry or this client.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
service | str | 'enterprise-ai-agent' | no | Service name set as service.name on every span (default enterprise-ai-agent). |
batch_size | int | 50 | no | Number of finished spans buffered before they are sent (default 50). |
use_otel | bool | None | None | no | Use OpenTelemetry: None when installed, True always (import error otherwise), False never. |
Returns: Tracer. A Tracer: Minimal GenAI tracer with W3C context propagation into SDK calls.
TelemetryClient.traces
traces(**filters: Any) -> Any
List the recent traces. Recent traces of the tenant, newest first: one row per root span with its name, service, start, duration, status, run, session and its span and error counts. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown status or a from after to answers 400 invalid_request.
Route: /v1/telemetry/traces (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**filters | Any | no | Query filters: status (ok, error, unset), service, run_id, from, to, limit. |
Returns: Any. Decoded JSON answer of the operation "List the recent traces".
Raises: the typed errors of the transport (Errors).
Class Tracer
Minimal GenAI tracer with W3C context propagation into SDK calls.
Attributes:
| Name | Type | Required | Description |
|---|---|---|---|
batch_size | yes | Number of finished spans buffered before they are sent. | |
service | yes | Service name set as service.name on every span. | |
telemetry | yes | Telemetry client that receives the fallback spans, or None. |
Constructor Tracer
Tracer(telemetry: TelemetryClient | None, service: str, batch_size: int = 50, use_otel: bool | None = None) -> None
Create a tracer; it uses OpenTelemetry when available, otherwise buffers spans and posts them through telemetry.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
telemetry | TelemetryClient | None | yes | Telemetry client that receives the fallback spans, or None to only buffer them. | |
service | str | yes | Service name set as service.name on every span. | |
batch_size | int | 50 | no | Number of finished spans buffered before they are sent (default 50). |
use_otel | bool | None | None | no | Use OpenTelemetry: None when installed, True always (import error otherwise), False never. |
Tracer.flush
flush() -> list[dict[str, Any]]
Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).
Route: /v1/telemetry/spans (POST).
This element takes no parameter.
Returns: list[dict[str, Any]]. Decoded JSON answer of the operation "Ingest telemetry spans".
Raises: the typed errors of the transport (Errors).
Tracer.span
span(name: str, attributes: dict[str, Any] | None = None) -> Iterator[Any]
Open a span; SDK requests made inside carry its traceparent.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | str | yes | Name of the span. | |
attributes | dict[str, Any] | None | None | no | Attributes of the span, added to service.name. |
Returns: Iterator[Any]. Context manager yielding the OpenTelemetry span or a SpanRecord; an exception marks the record error with error.type.
Functions
usage_attributes
usage_attributes(response: dict[str, Any]) -> dict[str, Any]
GenAI attributes from an OpenAI style completion.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
response | dict[str, Any] | yes | Chat completion dict with model, id, usage and choices. |
Returns: dict[str, Any]. Dict of gen_ai.response.model, gen_ai.response.id, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens and gen_ai.response.finish_reasons, without missing values.