Observability

Start with the smallest surface that answers your question:

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.

Evaluation

Observability records what route ran and what it cost. Evaluation decides whether the result met an objective. Keep those responsibilities separate:

• request outcomes and metering provide evidence for routing and policy review;
• bro eval manages evaluation subjects, results, and snapshots;
• bro optimize uses admitted evidence to inspect or advance routing optimization.

See the CLI reference for the released command surface. Do not infer task success from an HTTP success code or from a low-cost route alone.