Observability¶
Tracing is emitted natively from the C++ runtime over OTLP/HTTP and is off until you configure it. Point it at Langfuse or any OpenTelemetry backend.
Explicit OpenTelemetry configuration for A11.
Tracing is emitted natively from the C++ runtime and is off until
configure_otel (or a backend helper such as langfuse) is
called. Spans are exported directly from C++ over OTLP/HTTP (JSON), so
telemetry never depends on the Python layer being on the hot path.
A standalone tracing span, e.g. to group work that isn't a single action.
Create one with start_span, pass span.traceparent() to
enable_tracing on child actions to nest them, and end() it (or
use it as a context manager). Mutators are no-ops when tracing is off.
start_span(name: str, *, kind: str = 'internal', parent_traceparent: str | None = None) -> Span
Start a standalone span. When parent_traceparent is given the span
continues that trace; otherwise it begins a new root trace. Returns an
inactive Span (all no-ops) if tracing is not configured.
configure_otel(*, service_name: str = 'a11', resource_attributes: Mapping[str, str] | None = None, exporter: str = 'otlp_http', endpoint: str = '', headers: Mapping[str, str] | None = None, timeout_millis: int = 10000, use_simple_processor: bool = False, baggage_span_attributes: Sequence[str] | None = None) -> None
Install the global tracer provider.
exporter is one of "otlp_http", "ostream", "in_memory" or
"none". For "otlp_http" supply endpoint (a full traces URL) and
any auth headers. baggage_span_attributes names W3C baggage keys
that are copied onto every span as attributes (e.g. langfuse.session.id)
while still propagating downstream. Raises StatusException on error
(e.g. an OTLP endpoint on a build without OTLP support).
Return the OTLP traces endpoint for a Langfuse host.
Return the HTTP Basic auth header value Langfuse expects.
langfuse(*, public_key: str, secret_key: str, host: str = 'https://cloud.langfuse.com', service_name: str = 'a11', resource_attributes: Mapping[str, str] | None = None, extra_headers: Mapping[str, str] | None = None, baggage_span_attributes: Sequence[str] | None = None, timeout_millis: int = 10000) -> str
Configure native OTLP/HTTP export to Langfuse's ingestion endpoint.
Langfuse is OTLP-compatible, so this just points the native exporter at the
Langfuse traces endpoint with Basic auth. Additional resource_attributes
(and extra_headers) let a Langfuse integration attach its own metadata.
baggage_span_attributes defaults to LANGFUSE_BAGGAGE_KEYS, so
request-scoped values set upstream via the x-otel-baggage header --
e.g. langfuse.session.id -- are promoted to span attributes Langfuse
reads, and still propagate across nested/remote actions.
Returns the resolved endpoint.
Mint a fresh W3C traceparent value for a brand-new root trace.
Use this when the action you run/call has no upstream context and you want
it to start its own trace: set it as the TRACEPARENT_HEADER before
run()/call() (or just use enable_tracing).
enable_tracing(action: 'Action', *, traceparent: str | None = None, tracestate: str | None = None, baggage: Mapping[str, str] | str | None = None) -> 'Action'
Enable tracing on a root action before you run or call it.
Sets the reserved W3C headers so the action's handler run becomes a span
(tracing must already be configured). With no traceparent an existing
one on the action is reused, otherwise a fresh root trace is minted.
baggage -- a mapping such as {"langfuse.session.id": "..."} or a
preformatted header string -- rides along and propagates downstream.
Returns the action so it chains: enable_tracing(a).run(). Nested actions
are traced automatically and do not need this call.
Configure native tracing from standard OpenTelemetry environment vars.
Honors OTEL_SDK_DISABLED, OTEL_TRACES_EXPORTER
(otlp | console | none), OTEL_SERVICE_NAME,
OTEL_RESOURCE_ATTRIBUTES, and the OTEL_EXPORTER_OTLP_* endpoint,
headers and timeout variables (per-signal ..._TRACES_* overrides win).
Only OTLP/HTTP (JSON) transport is supported, so a gRPC protocol selection
is rejected. Returns True if a provider was installed, False if the
environment disabled tracing.
Configure native OTLP export to Langfuse from LANGFUSE_* env vars.
Reads LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_HOST
(also honoring OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES).
Returns True when configured, False when both keys are absent, and
raises ValueError if only one of the key pair is set.