Telemetry

Telemetry records what BitRouter did. Start with the smallest surface that answers your operational question:

Use Models to preview a selector before sending traffic. Use Evaluations to decide whether a completed result met an objective.

Local request receipts

The local metering store records settled requests independently of OpenTelemetry export:

bro requests --limit 25

Each receipt distinguishes the requested selector, resolved model, serving provider, token usage, cost, latency, and status. It remains available when the exporter is disabled and can be inspected with no daemon running.

Self-hosted OpenTelemetry

OpenTelemetry export is opt-in. Configure the current bitrouter-telemetry plugin and point it at an OTLP endpoint:

plugins:
  bitrouter-telemetry:
    otel:
      endpoint: "http://otel-collector:4318"
      service_name: "bitrouter"

Or enable it with standard environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_SERVICE_NAME=bitrouter
bro serve

Each request produces an ingress span, a routing span, one client span per upstream attempt, and settlement metadata. Retry and fallback attempts therefore remain visible as separate hops. Metrics include request counts, latency, token usage, errors, and streaming activity.

The binary pushes OTLP; it does not expose a production Prometheus scrape endpoint. Use an OpenTelemetry Collector when Prometheus is the destination.

Privacy and sampling

Message bodies are excluded by default. Enabling full capture copies prompts and responses into your telemetry backend:

plugins:
  bitrouter-telemetry:
    otel:
      endpoint: "http://otel-collector:4318"
      content_capture: full

The equivalent environment override is BITROUTER_TELEMETRY_CONTENT_CAPTURE=full. Apply backend access control and retention before enabling it.

For high-volume deployments, configure a standard sampler:

plugins:
  bitrouter-telemetry:
    otel:
      sampler: parentbased_traceidratio
      sampler_arg: 0.1

Standard OTEL_* environment variables take precedence over YAML.

Verify export

bro reload
bro observe status
bro observe status --json

Then send one request and confirm that the collector receives the trace. A stopped status means no endpoint opted the exporter in or the installed binary lacks the required OTLP transport feature.

Cloud Activity

BitRouter Cloud records request receipts without storing prompt or response bodies. The Activity view shows spend, request count, tokens, model, provider, latency, status, routing profile, and funding source for the active workspace.

The same data is available from the CLI:

bro cloud usage
bro cloud requests --limit 25

Cloud receipts are not span waterfalls. Use your own OTLP backend when you need the complete trace across an agent, router, tools, and every upstream attempt.

Telemetry is not evaluation

Receipts, spans, and metrics establish what ran and what it cost. They do not establish whether the result was correct or whether a cheaper policy is safe to adopt.

Evaluations defines the separate subject, result, admission, and snapshot lifecycle. An evaluator may consume telemetry, but the evaluator's objective and result remain explicit evidence rather than inferred metadata.