ratel-ai-telemetry (Python)

v0.1.3 · Python · PyPI · source

Generated from the doc comments at ratel-ai/ratel@d8635d5 — do not edit by hand. Regenerate with pnpm sync:api in apps/docs.

Classes

AuthOutcome

Outcome of an MCP auth flow. Carried by ratel.auth.outcome; NEEDS_AUTH is the 401-driven AuthNeeds case (ADR-0007 auth_needs).

Attributes:

• FAILED = 'failed'
• NEEDS_AUTH = 'needs_auth'
• OK = 'ok'
• REFRESHED = 'refreshed'

Origin

Whether a ratel.* span was a direct library call or synthesized by the agent inside its loop. Carried by ratel.origin; mirrors the local trace Origin (ADR-0007).

A str-Enum: each member equals its exact wire string, so it is usable directly as an OTel attribute value.

Attributes:

• AGENT = 'agent'
• DIRECT = 'direct'

SearchTarget

What a ratel.search span was searching. Carried by ratel.search.target; folds capability-tool search and skill search into one span shape.

Attributes:

• SKILL = 'skill'
• TOOL = 'tool'

ContentCapture

Message/tool content capture modes for OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (CONVENTIONS.md § Capture gating). Default off.

Attributes:

• EVENT_ONLY = 'EVENT_ONLY'
• NO_CONTENT = 'NO_CONTENT'
• SPAN_AND_EVENT = 'SPAN_AND_EVENT'
• SPAN_ONLY = 'SPAN_ONLY'

OtlpConfig

OtlpConfig(url: str, logs_url: str, headers: dict[str, str], service_name: str)

Resolved exporter configuration; the pure core of init().

Attributes:

• headers: dict[str, str]
• logs_url: str
• service_name: str
• url: str

TelemetryHandle

What init() returns: a shutdown handle, not a full provider.

Both the enabled path and the disabled/no-op path satisfy this, so the return type is honest either way. Emit telemetry through the global OpenTelemetry APIs, not off this handle — init() registers both signal providers globally.

force_flush

force_flush(timeout_millis: int = 30000) -> bool

shutdown

shutdown() -> Any

Functions

init

init(*, api_key: str | None = None, endpoint: str | None = None, logs_endpoint: str | None = None, headers: Mapping[str, str] | None = None, service_name: str | None = None, span_filter: SpanFilter | None = None, log_filter: LogFilter | None = None, enabled: bool = True) -> TelemetryHandle

Wire OTLP http/protobuf exporters + batch processors + one service.name resource, register global tracer and logger providers, and return a shutdown handle (call handle.shutdown() / handle.force_flush()). Emit through the global OTel APIs.

init() owns the global provider, so it exports every span by default (unlike ratel_span_processor, whose default gen_ai./ratel. filter exists for sharing a provider); pass span_filter to narrow it. Repeated calls return the original Ratel-owned handle. It raises — pointing at ratel_span_processor — if a foreign provider is already registered globally. On first setup, pass enabled=False for an OTel-free no-op handle that needs no endpoint; once Ratel owns the provider, repeated calls return it regardless of options. Enabled initialization needs the [otlp] extra and raises a clear error without it.

Shutdown is terminal: after handle.shutdown(), a later init() raises rather than hand back the dead provider (OTel's global provider is set once per process). Note that the handle is shared across repeated calls, so shutting it down stops export for every caller.

resolve_otlp_config

resolve_otlp_config(*, api_key: str | None = None, endpoint: str | None = None, logs_endpoint: str | None = None, headers: Mapping[str, str] | None = None, service_name: str | None = None, env: Mapping[str, str] | None = None) -> OtlpConfig

Resolve init() options into concrete exporter config.

Accepts either api_key= (falling back to RATEL_API_KEY; endpoint defaults to RATEL_OTLP_ENDPOINT, then the superseded RATEL_URL; Authorization: Bearer) or endpoint=/headers= (custom endpoint / collector). The forms compose: explicit endpoint/api_key values win over their environment fallbacks. An explicit api_key sets the Bearer header; the RATEL_API_KEY fallback applies only when neither api_key nor an explicit Authorization header is given, so ambient env never clobbers auth the caller set on purpose. env is injectable so the precedence is testable without a network.

content_capture_mode

content_capture_mode(env: Mapping[str, str] | None = None) -> ContentCapture

Parse the ecosystem content-capture gate. A mode set via set_content_capture wins outright (env is the fallback, as in OTel); otherwise defaults to NO_CONTENT when unset/empty/unrecognized. The legacy boolean form maps true to full capture (SPAN_AND_EVENT) and false to none.

set_content_capture

set_content_capture(mode: ContentCapture | str | None) -> int

Programmatically set the content-capture mode. While set, content_capture_mode() returns this mode regardless of OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — programmatic config wins over the environment, matching how OpenTelemetry treats env vars as the fallback for code-level configuration. Pass None to clear the override unconditionally and return to env-driven parsing.

The mode is validated like the env var (case-insensitive, legacy true/false/1/0 accepted) and raises a ValueError on anything unrecognized — failing loud at config time instead of storing a value that would both disable capture and mask the env var.

Returns a generation token identifying this call as the current owner of the override; pass it to clear_content_capture to clear only if no newer set has happened since (the safe form for shutdown/teardown hooks).

clear_content_capture

clear_content_capture(generation: int) -> None

Clear the programmatic content-capture override, but only when generation — the token returned by set_content_capture — still identifies the most recent set. A stale token no-ops, so an old handle shutting down late cannot clobber an override a newer caller installed (and silently re-enable, or disable, capture via the env fallback). For an unconditional clear, use set_content_capture(None).

ratel_event_filter

ratel_event_filter(record: ReadWriteLogRecord) -> bool

Default log filter: forward only named gen_ai.* / ratel.* EventRecords.

ratel_log_exporter

ratel_log_exporter(*, api_key: str | None = None, endpoint: str | None = None, logs_endpoint: str | None = None, headers: Mapping[str, str] | None = None) -> LogRecordExporter

Build the OTLP http/protobuf log exporter at the resolved logs endpoint.

ratel_log_record_processor

ratel_log_record_processor(*, api_key: str | None = None, endpoint: str | None = None, logs_endpoint: str | None = None, headers: Mapping[str, str] | None = None, log_filter: LogFilter | None = None, enabled: bool = True) -> LogRecordProcessor

A filtered BatchLogRecordProcessor for a host-owned LoggerProvider.

ratel_signal_filter

ratel_signal_filter(span: ReadableSpan) -> bool

Default span filter: forward only signal-bearing spans — a ratel.* span name, or any attribute key under gen_ai.* / ratel.*.

This is what lets Ratel share a provider with e.g. Langfuse + the Vercel AI SDK and ingest only the gen_ai/ratel signal (the AI SDK's gen_ai.* spans + Ratel's own ratel.search / execute_tool), dropping the framework's ai.* wrapper noise.

ratel_span_exporter

ratel_span_exporter(*, api_key: str | None = None, endpoint: str | None = None, headers: Mapping[str, str] | None = None) -> SpanExporter

Build the OTLP http/protobuf span exporter at the resolved Ratel endpoint.

The standalone exporter for callers wiring their own span-processor; ratel_span_processor batches over it. Carries no resource — the caller's provider owns service.name. Needs the [otlp] extra; raises a clear error otherwise.

ratel_span_processor

ratel_span_processor(*, api_key: str | None = None, endpoint: str | None = None, headers: Mapping[str, str] | None = None, span_filter: SpanFilter | None = None, enabled: bool = True) -> SpanProcessor

A BatchSpanProcessor over the Ratel OTLP exporter that forwards only the spans passing span_filter (default ratel_signal_filter; pass lambda _s: True to forward everything).

Add it to your own provider (provider.add_span_processor(ratel_span_processor(...))) to send Ratel telemetry alongside another provider — no global side effects, no resource. Greenfield apps that want Ratel to own the provider should call init() instead. Pass enabled=False for an OTel-free no-op processor that needs no endpoint. Enabled processors need the [otlp] extra and raise a clear error without it.

Constants

• CAPTURE_CONTENT_ENV: Final = 'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT' — The ecosystem instrumentation env var gating message/tool content capture. Default off; honored by init() rather than a Ratel-invented flag (CONVENTIONS.md § Capture gating). Values: legacy boolean, or the enum NO_CONTENT (default) / SPAN_ONLY / EVENT_ONLY / SPAN_AND_EVENT.
• EXECUTE_TOOL: Final = 'execute_tool' — execute_tool — the gen_ai.operation.name value for a tool invocation. Deliberately the standard OTel gen_ai operation, not a bespoke ratel.invoke span, so a generic OTel backend already understands it (locked 2026-07-05). The invoke is enriched with ratel.* attributes.
• GEN_AI_INFERENCE_DETAILS: Final = 'gen_ai.client.inference.operation.details' — gen_ai.client.inference.operation.details — inference request/response content.
• GEN_AI_INPUT_MESSAGES: Final = 'gen_ai.input.messages' — gen_ai.input.messages — the input message list (Opt-In content).
• GEN_AI_OPERATION_NAME: Final = 'gen_ai.operation.name' — gen_ai.operation.name — set to EXECUTE_TOOL for a tool invocation.
• GEN_AI_OUTPUT_MESSAGES: Final = 'gen_ai.output.messages' — gen_ai.output.messages — generated outputs; every message includes finish_reason.
• GEN_AI_SYSTEM_INSTRUCTIONS: Final = 'gen_ai.system_instructions' — gen_ai.system_instructions — the system prompt as a bare parts[] (Opt-In content).
• GEN_AI_TOOL_CALL_ARGUMENTS: Final = 'gen_ai.tool.call.arguments' — gen_ai.tool.call.arguments — tool arguments (Opt-In content, gated).
• GEN_AI_TOOL_CALL_ID: Final = 'gen_ai.tool.call.id' — gen_ai.tool.call.id — tool call id, when available.
• GEN_AI_TOOL_CALL_RESULT: Final = 'gen_ai.tool.call.result' — gen_ai.tool.call.result — tool result (Opt-In content, gated).
• GEN_AI_TOOL_NAME: Final = 'gen_ai.tool.name' — gen_ai.tool.name — the capability tool id.
• RATEL_AUTH_FLOW: Final = 'ratel.auth.flow' — ratel.auth.flow — MCP auth flow.
• RATEL_AUTH_OUTCOME: Final = 'ratel.auth.outcome' — ratel.auth.outcome — "ok" / "refreshed" / "needs_auth" / "failed" (see AuthOutcome).
• RATEL_ORIGIN: Final = 'ratel.origin' — ratel.origin — direct library call vs agent-synthesized (shared attribute).
• RATEL_SEARCH: Final = 'ratel.search' — ratel.search — capability search (unifies tool-search and skill-search).
• RATEL_SEARCH_HIT_COUNT: Final = 'ratel.search.hit_count' — ratel.search.hit_count — results returned.
• RATEL_SEARCH_QUERY: Final = 'ratel.search.query' — ratel.search.query — the search text (content, gated like message content).
• RATEL_SEARCH_RESULTS: Final = 'ratel.search.results' — ratel.search.results — Opt-In search-content event; gated like content.
• RATEL_SEARCH_TARGET: Final = 'ratel.search.target' — ratel.search.target — "tool" or "skill" (see SearchTarget).
• RATEL_SEARCH_TOP_K: Final = 'ratel.search.top_k' — ratel.search.top_k — requested result count.
• RATEL_SKILL_ID: Final = 'ratel.skill.id' — ratel.skill.id — skill loaded on the ratel.skill.load span.
• RATEL_SKILL_LOAD: Final = 'ratel.skill.load' — ratel.skill.load — skill content load (get_skill_content).
• RATEL_TOOL_ARGS_SIZE_BYTES: Final = 'ratel.tool.args_size_bytes' — ratel.tool.args_size_bytes — argument payload size on the execute_tool span.
• RATEL_TOOL_EXECUTION_DETAILS: Final = 'ratel.tool.execution.details' — ratel.tool.execution.details — Opt-In structured tool arguments/result event.
• RATEL_UPSTREAM_REGISTER: Final = 'ratel.upstream.register' — ratel.upstream.register — upstream-MCP ingest.
• RATEL_UPSTREAM_SERVER: Final = 'ratel.upstream.server' — ratel.upstream.server — upstream MCP server backing a tool / auth flow.
• RATEL_UPSTREAM_TOOL_COUNT: Final = 'ratel.upstream.tool_count' — ratel.upstream.tool_count — tools ingested on register.
• RATEL_UPSTREAM_TRANSPORT: Final = 'ratel.upstream.transport' — ratel.upstream.transport — "stdio" / "http" / "sse" / ...
• SEMCONV_VERSION: Final = '1.42.0' — The pinned OpenTelemetry semantic-conventions version this vocabulary tracks (the gen_ai group). The pin is the contract; consumers read against this exact version, never "latest" (CONVENTIONS.md § The pin).
• API_KEY_ENV = 'RATEL_API_KEY' — Env var whose value is the default API key when api_key= is omitted.
• ENDPOINT_ENV = OTLP_ENDPOINT_ENV — Backwards-compatible alias of :data:OTLP_ENDPOINT_ENV, the var callers set.
• OTLP_ENDPOINT_ENV = 'RATEL_OTLP_ENDPOINT' — Env var whose value is the default OTLP traces endpoint.
• LEGACY_ENDPOINT_ENV = 'RATEL_URL' — Superseded spelling, still read as a fallback. RATEL_URL also names the SDK's catalog source (ADR-0003), so overloading it as the OTLP endpoint conflated two unrelated destinations. Setting it still works and warns.
• DEFAULT_SERVICE_NAME = 'ratel' — service.name used when the caller does not pass one.
• SpanFilter = Callable[['ReadableSpan'], bool] — Predicate deciding whether a finished span is forwarded to Ratel.
• LogFilter = Callable[['ReadWriteLogRecord'], bool]