Collector HTTP

Lookup for the collector in this product revision. Examples use 127.0.0.1:7410.

POST paths

/v1/track
/v1/identify
/v1/page
/v1/screen
/v1/group
/v1/alias
/v1/batch
/v1/metrics
/v1/traces
/v1/logs

Any other path on POST is 400 unknown path. GET on those paths is 404.

curl -sS -X POST http://127.0.0.1:7410/v1/track \
  -H 'content-type: application/json' \
  -d '{"type":"track","event":"Signed Up","userId":"u1","properties":{"plan":"pro"}}'

GET /health

Returns ok.

curl -sS http://127.0.0.1:7410/health
ok

Success body

A 200 ingest response is JSON:

{"success":true}

Statuses

400: Invalid JSON, unknown type, missing userId or anonymousId, missing track event, missing batch array, invalid OTLP, or unknown path.
401: Write keys are mapped and Authorization is missing, not Basic, or not a known key.
404: Method is not POST, except GET /health.
413: Body over 32 768 bytes, or over 4 194 304 bytes on /v1/batch.
503: Persist failed after a valid body.

Write key

Authorization: Basic, key as username. The collector stamps instance from the key and ignores instance on the body.

When no keys are mapped, every request uses the default instance and auth is not checked.

curl -sS -X POST http://127.0.0.1:7410/v1/track \
  -u 'sk_example:' \
  -H 'content-type: application/json' \
  -d '{"type":"track","event":"Signed Up","userId":"u1"}'

Metrics

Thin envelope: name and value required. Other attribute keys are opaque.

curl -sS -X POST http://127.0.0.1:7410/v1/metrics \
  -H 'content-type: application/json' \
  -d '{"metrics":[{"name":"checkout.latency","value":184,"unit":"ms","attributes":{"step":"pay"}}]}'

OTLP JSON uses a resourceMetrics object on the same path.

Env

loadConfig reads these names. Defaults are in parentheses.

COLLECTOR_DUCKDB_PATH: collector.duckdb
COLLECTOR_HTTP_HOST: 127.0.0.1
COLLECTOR_HTTP_PORT: 7410
COLLECTOR_INSTANCE: local
COLLECTOR_WRITE_KEYS: instance:key,instance:key. Empty map falls back to COLLECTOR_WRITE_KEY on the default instance.
COLLECTOR_QUACK_TOKENS: instance:token,instance:token. Empty map uses COLLECTOR_QUACK_TOKEN or panel-token on the default instance.
COLLECTOR_QUACK_URI: quack:localhost
COLLECTOR_QUACK_PROXY: off unless 1, true, or yes
COLLECTOR_PANEL_NOTIFY_URLS: instance:url,instance:url. Empty map falls back to COLLECTOR_PANEL_NOTIFY_URL.
COLLECTOR_UPSTREAM_URL: empty
COLLECTOR_UPSTREAM_WRITE_KEY: empty
COLLECTOR_OPT_OUT: off unless 1, true, or yes
COLLECTOR_RELAY_INTERVAL_MS: 2000
COLLECTOR_FLUSH_INTERVAL_MS: 1000
COLLECTOR_HISTOGRAM_BOUNDS: 5,10,25,50,100,250,500,1000,2500,5000,10000