Export to OpenTelemetry

OTelEventSink turns every action into one OpenTelemetry span, named for the action, with one span event per step: proposed, decided, reserved, executed, recorded. It hands spans to whatever tracer provider your process configured and never blocks. Argument values are not attributes unless you ask, because a trace backend is not the receipt store. Prerequisites: pip install "ctrlrun[otel]", which brings the API, the SDK and the OTLP/HTTP exporter, and a backend that speaks OTLP (or, below, an in-memory exporter to see the spans without one).

Attach the sink

runnable

schema: ctrlrun.policy/v2

actions:
  crm.update_record:
    effect: "crm:{record_id}:{field}"
    decision: allow

runnable

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter

import ctrlrun
from ctrlrun import Control, Policy, SQLiteStateStore
from ctrlrun.otel import OTelEventSink

exporter = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))

control = Control(
    Policy.from_file("ctrlrun.yaml"),
    SQLiteStateStore(".ctrlrun/state.db"),
    sinks=[OTelEventSink(tracer_provider=provider)],
)


@ctrlrun.protect("crm.update_record", effect="crm:{record_id}:{field}", control=control)
def update(record_id: str, field: str, value: str) -> str:
    return "updated"


with ctrlrun.context(agent="crm-agent"):
    update(record_id="c_42", field="phone", value="+353 1 555 0100")

(span,) = exporter.get_finished_spans()
print("span:", span.name)
print("events:", [event.name for event in span.events])
print("arguments in attributes:", any("phone" in str(v) for v in span.attributes.values()))

span: crm.update_record
events: ['ACTION_PROPOSED', 'POLICY_EVALUATED', 'EFFECT_RESERVED', 'EXECUTION_STARTED', 'EXECUTION_COMMITTED']
arguments in attributes: False

Export for real

Replace the in-memory exporter with the OTLP one your backend expects, or rely on the provider your application already configured and pass nothing: with no tracer_provider the sink uses the global one, and with none configured the API’s no-op provider makes the sink free.

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))   # OTEL_EXPORTER_OTLP_ENDPOINT

With the gateway, --otel does the same, and --otel-arguments opts argument values in.

Read the span

The span’s status is an error for failed and ambiguous, unset for a refusal (a refusal is CTRLRun doing its job, not an error), and ok for committed. Attributes carry the action name, the decision, the effect key, the outcome and the receipt id; the receipt itself stays in the store. Open spans are bounded, so a process that dies mid-action leaves at most a fixed number unended, stated rather than solved.

What the sink is not

It is not the evidence. Receipts live in the store and the JSONL file, are chained, and are what ctrlrun receipts --verify-chain checks; a trace is a view of them for the people who already look at traces. Deleting a trace deletes nothing CTRLRun relies on.

If it didn’t work

MissingDependency: pip install "ctrlrun[otel]": the extra is not installed.
No spans arrive: no span processor is attached to the provider the sink was given, or the batch processor has not flushed yet; provider.force_flush() before exit.
Argument values appear: arguments=True was passed, or --otel-arguments on the gateway.

Receipts and evidence.
Receipt and event schemas: the event names above.
Get started · Why.

Start

Get started

MCP

Concepts

Guides

Cookbook

Compare

FAQ

More

Export to OpenTelemetry

What the sink is not

If it didn’t work

Next

​What the sink is not

​If it didn’t work

​Next

What the sink is not

If it didn’t work

Next