Provon OpenTelemetry Setup

Provon accepts standard OTLP/HTTP telemetry, so teams that already use OpenTelemetry can keep their existing SDKs and exporters. Route model calls through the Provon Gateway when you want request-time policy, provider routing, cost capture, and guardrails. Use OTLP when your agent or application already emits traces, logs, or metrics that should join the same feedback loop.

Gateway telemetry and OTLP telemetry converge into the same project-scoped trace evidence. Workflows, dashboards, trace search, conversations, and user views can use both sources.

Quick Start

Create a project in the Workspace, copy a project API key, then point your OTLP/HTTP exporter at Provon:

export PROVON_API_KEY=your_project_api_key
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:3000
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Most OpenTelemetry SDKs append signal paths automatically when OTEL_EXPORTER_OTLP_ENDPOINT is set. For local development, Provon accepts:

POST /v1/traces
POST /v1/logs
POST /v1/metrics

If your SDK requires signal-specific endpoints, configure the trace endpoint directly:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:3000/v1/traces

Python Trace Exporter

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="http://127.0.0.1:3000/v1/traces",
            headers={"Authorization": "Bearer your_project_api_key"},
        )
    )
)
trace.set_tracer_provider(provider)

Node.js Trace Exporter

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://127.0.0.1:3000/v1/traces',
    headers: {
      Authorization: `Bearer ${process.env.PROVON_API_KEY}`,
    },
  }),
});

sdk.start();

What To Send

Provon works best when agent traces include stable identifiers and model-call attributes:

• service.name for the agent or application name.
• session.id, conversation.id, or another stable conversation key when available.
• OpenTelemetry GenAI attributes for model name, prompts, completions, token usage, and errors.
• Tool-call spans as child spans of the agent run.
• Logs or metrics that explain evaluation failures, retries, latency, or cost changes.

Do not send secrets, raw credentials, or unredacted private data unless your deployment and retention settings are configured for that data.

Production Notes

For production deployments, replace http://127.0.0.1:3000 with your Provon runtime URL. Keep using a project API key in the Authorization header, and prefer OTLP/HTTP protobuf unless your existing collector or SDK already emits OTLP JSON.

If your organization already runs an OpenTelemetry Collector, configure an OTLP/HTTP exporter from the collector to Provon. This keeps language SDK configuration stable while letting the collector handle batching, retries, sampling, and redaction.

Troubleshooting

• 401 or 403: verify the project API key and Authorization=Bearer ... header.
• No traces appear: confirm the exporter is using OTLP/HTTP, not OTLP/gRPC.
• Only traces appear: add log or metric exporters, or set signal-specific endpoints.
• Payload rejected: check exporter compression, content type, and batch size.
• Missing conversation views: add a stable conversation or session attribute to agent spans.