OpenTelemetry for custom agents

This page is for an agent connecting a custom agent, framework or service that already emits OpenTelemetry. It gives the endpoint, the authentication header, the attributes Zaun reads, the limits and the proof to show. If you are the person, this path observes and alerts; to block, have your agent call the API scan before it acts.

Point the exporter at Zaun#

Zaun accepts OTLP over HTTP; gRPC is not accepted. Most OpenTelemetry SDKs read these standard variables:

export OTEL_EXPORTER_OTLP_ENDPOINT='https://api.zaun.ai/v1/ingest/otlp'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
export OTEL_EXPORTER_OTLP_HEADERS='x-zaun-ingest-key=<INGEST_KEY>'

• <INGEST_KEY> is an ingest key for a generic OpenTelemetry source. It can only submit events for one project, and it cannot scan or read results. Treat it like an error-reporting key: low risk if read, cheap to rotate. Still keep it out of source control.
• The SDK appends the signal path, so logs go to /v1/ingest/otlp/v1/logs and traces to /v1/ingest/otlp/v1/traces. An exporter that needs a full URL per signal takes those.
• Send application/x-protobuf or application/json, optionally gzipped. Metrics are accepted and discarded, so an exporter with metrics on does not fail.
• Authorization: Bearer <INGEST_KEY> also works. The x-zaun-ingest-key header avoids the space, which exporters that parse header strings as key=value pairs handle differently.

What Zaun reads#

Zaun reads the OpenTelemetry generative AI conventions on log records and on span events. Put the attributes there:

Without the message attributes, Zaun sees that calls happened but has nothing to assess. Message content capture is often off by default in instrumentation libraries; turn it on.

If the exporter reports a user (user.email, enduser.id, user.name or process.owner), Zaun removes it from the event and keeps only a hash. The hash is made with a key only Zaun holds, derived per organization, so it cannot be computed from an email outside Zaun and the same person has a different hash in every organization. To find a user's results, pass their email to the violations filter, principal=dev@example.com; Zaun hashes it for you.

Limits#

Telemetry has its own budgets, so a busy exporter does not slow down your API scans. Its scans spend the same credit as API scans.

The proof to show#

The source's health report in the console shows the state (waiting, receiving or degraded), the first and last event times, event counts by name, whether message content is present, how many conversation turns were scanned, and each rejection with its reason and fix. Start a connectivity check, send an event that contains its code, and show the person the check marked satisfied.