Skip to main content
This is the wire contract for watching. Most founders should merge the watching PR or follow the manual OpenTelemetry install. Use this page when you already speak OTEL or are wiring exporters yourself.

​
Where to send

Host: https://intake.focale.io in production. Do not add an /otlp/ prefix. There is no gRPC. Unknown versions such as /v2/... return 404.

​
Auth

The ingest key is the userinfo in your DSN. Prefer parsing FOCALE_DSN=https://<key>@host into endpoint + Bearer. Also honor OTEL_EXPORTER_OTLP_* if already set. Missing or invalid keys return 401.

​
Body

Send OTLP/HTTP JSON (Content-Type: application/json) or protobuf (application/x-protobuf, application/protobuf, or application/vnd.google.protobuf). Anything else returns 415.
GET /healthz does not require a key. It only tells you the intake is up.

​
When to use each signal

Enable exporters for all three at boot, then instrument confirmed handlers with judgment: Do not dump verbose success logs per request. Redact secrets and PII.

​
Focale attributes

Set on spans, metrics, and error logs:
  • focale.flow_key = confirmed flow key
  • focale.signal = {flowKey}.started | .succeeded | .failed when relevant
  • Boot: focale.boot=true only
Standard first: resource service.name, span status OK/ERROR, record exceptions, HTTP semantic conventions when auto-instrumentation exists. Suggested metric names: focale.flow.started, focale.flow.succeeded, focale.flow.failed, focale.flow.duration (unit ms), with attribute focale.flow_key.