Sending data to Provantix
Data reaches Provantix four ways. Which one you use depends on what you can change: a service you own, an OpenTelemetry setup you already run, or a gateway you can only point somewhere else. This page says which path fits, then covers the hosted intake in full, because it is the path for systems that push to a URL and cannot sign anything.
Choosing a path
| You have | Use | What the record proves |
|---|---|---|
| A Node.js service you can change | Node.js SDK | Signed by your emitter, and sealed per record from SDK 0.2.0 |
| An OpenTelemetry GenAI setup in Node | OpenTelemetry exporter | The same: signed and sealed by your emitter |
| A service in another language | Direct HTTP API | Signed by your emitter; sealed if you build the seal |
| A gateway, an OpenTelemetry Collector, Cloudflare Workers or any source that posts OTLP/HTTP JSON | The hosted intake, below | Tamper-evident from the moment Provantix receives it |
| Entra ID or Microsoft 365 | A connector collector, under Connectors | Signed by the collector |
| History in Langfuse or LangSmith | Imports | Tagged with the connector it came from |
A source that cannot sign can still be fully useful: its records are chained, exported and verifiable. What they cannot show is that your own system vouched for them, only that Provantix held them unaltered from receipt. See How verification works.
The hosted intake
POST https://app.provantix.tech/v1/traces
authorization: Bearer pvx_otlp_…
content-type: application/json
The body is OTLP/HTTP in its JSON encoding. The binary protobuf encoding is not accepted: a body that is not valid JSON is answered with 400.
Create an intake token
On Setup, under Connect a gateway or OTLP source, give the source a label (for example "OpenRouter, production key") and, optionally, a default agent. The token is shown once; afterwards only its hash is kept. The same thing is available over the API:
curl -X POST https://app.provantix.tech/api/account/intake-tokens \
-H "authorization: Bearer <your session token>" \
-H "content-type: application/json" \
-d '{"label": "OpenRouter, production key", "default_agent": "support-bot"}'
Every plan includes intake sources: Designer gets one, Pilot and above any number. Revoke a token on Setup or with DELETE /api/account/intake-tokens/<id>; a revoked token is answered exactly like an unknown one.
What is kept
Provantix keeps the spans that describe AI activity: those carrying gen_ai.* attributes (an operation, a tool name, a system or a model). Each becomes a record, with the model, token counts, cost, target system and outcome the span states. The one other kind it keeps is a Cloudflare Workers outbound call, described under Cloudflare Workers, and only from a source you have marked as an agent. Any other span is counted as ignored in the response and stored nowhere.
Where the telemetry names a cloud region (cloud.region, faas.invoked_region, cloudflare.colo), the record also carries where it ran, labelled as derived; see Where things happened.
Prompt and completion attributes are removed on arrival and never stored. Turn on your gateway's privacy mode as well, so they are not sent at all.
Which agent a span belongs to
In order, the first present wins:
trace.metadata.agent_idtrace.metadata.agentuser.id- the default agent you set on the token
A tool span with none of these acts as the agent whose trace it runs in. Without any of them a record lands on unknown, and the data-health finding opens when more than 20% of a source's records are untagged. See Attribution.
Limits
| Limit | Value |
|---|---|
| Request body | 5 MB |
| Span start time | no more than 5 minutes in the future, no more than 30 days old |
| Requests per minute | 300 per token, 600 per organization, 120 per client address |
Spans outside the time window are rejected individually and counted. A request over a rate limit is answered 429 with a retry-after header.
Responses
| Status | Meaning |
|---|---|
| 200 | Delivered and stored. The body counts accepted, duplicates, ignored and rejected spans |
| 400 | The body is not valid JSON, or it carries logs or metrics and no spans (wrong_signal) |
| 401 | Unknown or revoked token |
| 413 | Body over 5 MB |
| 429 | Over a rate limit; retry after the time given |
A 200 means the delivery is durable: records are committed before the answer is sent. A request with an empty body, an empty resourceSpans list or the header x-test-connection: true is answered 200 and stores nothing, which is what a gateway's "test connection" button sends.
Setup shows each source's last delivery time. A source that shows none has never delivered: check the token, the endpoint and that the source is sending JSON.
Wiring common sources
OpenTelemetry Collector
Add an otlphttp exporter with the JSON encoding and put it on your traces pipeline:
exporters:
otlphttp/provantix:
traces_endpoint: https://app.provantix.tech/v1/traces
encoding: json
headers:
authorization: Bearer ${env:PROVANTIX_INTAKE_TOKEN}
service:
pipelines:
traces:
exporters: [otlphttp/provantix]
Only the traces pipeline is read. Logs and metrics sent to this endpoint are refused with a 400, so the exporter shows an error instead of a delivery that stored nothing.
OpenRouter Broadcast
Point the Broadcast destination at the endpoint with the bearer header, turn on Privacy Mode, and tag every request with trace.metadata.agent_id so calls attribute to the right agent.
Any other OTLP/HTTP JSON source
Set the traces endpoint, add the authorization header, and make sure the spans carry gen_ai.* attributes and an agent tag as above.
Cloudflare Workers
Cloudflare can export a Worker's traces to any OTLP/HTTP JSON endpoint with custom headers, which is what the intake accepts.
Traces only. Cloudflare also exports Workers Logs, which carry free text such as console.log output and no agent identity, and Provantix does not take them in: choose Traces as the destination type. A Logs destination pointed here is answered with a 400, and Cloudflare shows it as an error.
- On Setup, under Connect a gateway or OTLP source, create a token. Set the default agent to the name the Worker should appear under, for example
refund-worker. A source with a default agent is how you tell Provantix that this Worker is an agent; without one its spans are ignored. - In the Cloudflare dashboard, under Observability, Destinations, add a destination of type Traces with the endpoint
https://app.provantix.tech/v1/tracesand a custom header namedauthorizationwith the valueBearer pvx_otlp_…. - Turn on trace export for the Worker and redeploy it.
What becomes a record is the Worker's outbound call, the fetch span: the host it called as the target system, a read for GET, HEAD and OPTIONS and a write for any other method, and a failure when the status is 400 or above or the span errored. Only the host is kept, never the path, the query or a body. The region the Worker ran in (faas.invoked_region) and the Cloudflare location (cloudflare.colo) are kept as where it ran. A Worker's other spans (storage, cache, the invocation itself) are not agent activity and are ignored. A Worker that also emits gen_ai.* spans has those kept as described above.
Status: available. It is built on Cloudflare's documented span attributes and tested with them; it has not yet been run from a live Cloudflare account, so check the source's last delivery on Setup after you enable it. Cloudflare's own sampling setting applies: a sampled export delivers only some of the calls, and Provantix cannot tell a sampled-out call from one that never happened.
Related
- Emitters and keys: the signing identities the other paths use
- Batches API reference
- Findings: what opens when a source stops, falls behind or goes untagged