OTLP endpoint reference

Paths, authentication, content types, compression, response codes, Retry-After and the per-request limits of OTLP/HTTP sent to Belvador.

Markdown

On this page

Endpoint
Authentication
Format
Responses
Limits
Resource attributes Belvador reads

Belvador accepts OpenTelemetry traces, logs and metrics over OTLP/HTTP, as defined by the OTLP 1.x specification. Any exporter that follows it works; this page lists Belvador's paths, rules and limits.

Endpoint#

Text

https://ingest.belvador.dev/otlp/<project-id>

Exporters append /v1/traces, /v1/logs and /v1/metrics themselves when you set OTEL_EXPORTER_OTLP_ENDPOINT. If you set the per-signal variables (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT) instead, give the full URL including /v1/traces, /v1/logs or /v1/metrics. Metrics need a key with Metrics ticked (Metrics).

Authentication#

Text

Authorization: Bearer <ingest key>

The key (bvi_…) is created in Project settings → Ingest keys, belongs to one project, and lists the signals it may send. Requests that carry a browser Origin header are refused, so a key that ends up in front-end code is useless to whoever finds it. Revoking a key takes effect within 60 seconds.

Format#

	Accepted
Method	`POST`
`Content-Type`	`application/x-protobuf` (recommended) or `application/json`
`Content-Encoding`	none or `gzip`
Transport	HTTPS only; gRPC is not accepted directly — use a Collector

Responses#

Code	Means	The exporter should
200	Accepted and stored durably at the edge (empty response body).	Nothing. Records can still be dropped by the node later — see Usage.
400	The body is not valid OTLP.	Do not retry; fix the exporter.
401	Key missing, malformed or revoked.	Do not retry; check `OTEL_EXPORTER_OTLP_HEADERS`.
403	Key belongs to another project or lacks the signal scope (for example Metrics is not ticked), a browser sent it, or intake is paused for the workspace.	Do not retry; use the right project/signal key, server-side.
404	Unknown path.	Do not retry; the endpoint ends in `/otlp/<project-id>` and exporters add `/v1/traces`, `/v1/logs`, `/v1/metrics`.
413	Body larger than 4 MiB (compressed).	Send smaller batches.
415	Unsupported Content-Type or Content-Encoding.	Use `http/protobuf` or `http/json`, `gzip` or no compression.
429	Rate or monthly quota exceeded.	Retry after `Retry-After` (usually 1 s).
503	The edge cannot take it right now (node buffer full, transient fault).	Retry after `Retry-After` (30 s).

A successful response has an empty body ({} for JSON). Belvador does not return OTLP partial success counts: a 200 means the request is stored durably at the edge, and your node validates each record afterwards. Records it drops are counted by reason in Project settings → Traces, logs and metrics received (what each reason means).

429 and 503 carry Retry-After. Standard exporters retry these, as well as 502 and 504, with backoff; Deno's built-in exporter does not (details).

Limits#

Limit	Value
Request body (compressed)	4 MiB
Body after decompression	16 MiB
Maximum compression ratio	32×
Records per request	8192
Attributes per span/log/resource	128
Attribute key length	256 bytes
Attribute string value	16 KiB
Log body	64 KiB
Events / links per span	128 / 128
Accepted timestamps	7 days back to 5 minutes ahead

Values over the attribute and log body limits are cut and end with …[truncated]; attributes beyond the count limit are dropped. Both are counted, and the rest of the record is kept.

Resource attributes Belvador reads#

Attribute	Used for
`service.name`	The service in Traces, Logs and the Connection tab (up to 200 services per project are listed by name)
`deployment.environment.name`	The environment filter; `deployment.environment` is read when the new name is absent
`telemetry.sdk.name`, `telemetry.sdk.language`, `telemetry.sdk.version`	The SDK column of Evidence per signal
`belvador.verification_id` (on a span or log)	Marks a connection check

Spotted something wrong or missing? Tell us: hello@belvador.dev