OpenTelemetry

ZeroEval accepts standard OTLP trace data at POST /v1/traces, so any OpenTelemetry-instrumented application can export directly — through a collector, or straight from your app using an OTLP exporter.

When to use OTLP

Use this integration when:

Your application already uses OpenTelemetry for instrumentation
You want to fan out traces to multiple backends (ZeroEval + Datadog, Jaeger, etc.)
You’re running infrastructure you can’t modify but can route through a collector
You prefer a vendor-neutral instrumentation layer

If you’re starting fresh, the Python SDK or TypeScript SDK provide a simpler setup with automatic LLM instrumentation.

Endpoint Reference

POST https://api.zeroeval.com/v1/traces

Header	Value
`Authorization`	`Bearer YOUR_ZEROEVAL_API_KEY`
`Content-Type`	`application/json` or `application/x-protobuf`

The endpoint accepts the standard ExportTraceServiceRequest payload defined in the OTLP specification. Spans are converted to ZeroEval’s internal format — trace IDs, parent-child relationships, attributes, and status are all preserved.

Option 1: OpenTelemetry Collector

Route traces through a collector when you need batching, processing, or multi-destination fan-out.

Collector Configuration

Create otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  otlphttp:
    endpoint: https://api.zeroeval.com
    headers:
      Authorization: "Bearer ${env:ZEROEVAL_API_KEY}"
    traces_endpoint: https://api.zeroeval.com/v1/traces

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

Run with Docker Compose

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
    ports:
      - "4317:4317"
      - "4318:4318"
    environment:
      - ZEROEVAL_API_KEY=${ZEROEVAL_API_KEY}
    restart: unless-stopped

Run with Kubernetes

Full Kubernetes manifest

apiVersion: v1
kind: ConfigMap
metadata:
  name: otel-collector-config
data:
  config.yaml: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      batch:
        timeout: 1s
      k8sattributes:
        extract:
          metadata:
            - k8s.namespace.name
            - k8s.deployment.name
            - k8s.pod.name
    exporters:
      otlphttp:
        endpoint: https://api.zeroeval.com
        headers:
          Authorization: "Bearer ${env:ZEROEVAL_API_KEY}"
        traces_endpoint: https://api.zeroeval.com/v1/traces
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, k8sattributes]
          exporters: [otlphttp]
---
apiVersion: v1
kind: Secret
metadata:
  name: zeroeval-secret
type: Opaque
stringData:
  api-key: "YOUR_ZEROEVAL_API_KEY"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector
spec:
  replicas: 2
  selector:
    matchLabels:
      app: otel-collector
  template:
    metadata:
      labels:
        app: otel-collector
    spec:
      containers:
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:latest
          args: ["--config=/etc/config.yaml"]
          env:
            - name: ZEROEVAL_API_KEY
              valueFrom:
                secretKeyRef:
                  name: zeroeval-secret
                  key: api-key
          ports:
            - containerPort: 4317
              name: otlp-grpc
            - containerPort: 4318
              name: otlp-http
          volumeMounts:
            - name: config
              mountPath: /etc/config.yaml
              subPath: config.yaml
      volumes:
        - name: config
          configMap:
            name: otel-collector-config
---
apiVersion: v1
kind: Service
metadata:
  name: otel-collector
spec:
  selector:
    app: otel-collector
  ports:
    - name: otlp-grpc
      port: 4317
    - name: otlp-http
      port: 4318

Option 2: Direct from Python

Export OTLP traces directly from your Python application without a collector. Use the ZeroEvalOTLPProvider included in the SDK, or configure a standard OTLPSpanExporter.

Using ZeroEvalOTLPProvider

from opentelemetry import trace
from zeroeval.providers import ZeroEvalOTLPProvider

provider = ZeroEvalOTLPProvider(
    api_key="YOUR_ZEROEVAL_API_KEY",
    service_name="my-service"
)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("process_request") as span:
    span.set_attribute("user.id", "12345")
    result = do_work()
    span.set_attribute("result.status", "ok")

Using standard OTLPSpanExporter

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

exporter = OTLPSpanExporter(
    endpoint="https://api.zeroeval.com/v1/traces",
    headers={"Authorization": "Bearer YOUR_ZEROEVAL_API_KEY"}
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

Option 3: Direct from Node.js

import { NodeTracerProvider } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";

const exporter = new OTLPTraceExporter({
  url: "https://api.zeroeval.com/v1/traces",
  headers: {
    Authorization: "Bearer YOUR_ZEROEVAL_API_KEY",
  },
});

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
provider.register();

Attribute Mapping

ZeroEval maps standard OpenTelemetry span attributes to its internal format:

OTLP Attribute	ZeroEval Field	Notes
`span.name`	`name`	Span name
`span.kind`	`kind`	Mapped to `generic`, `llm`, etc.
`span.status`	`status`	`ok`, `error`, `unset`
`span.start_time`	`started_at`	Nanosecond timestamp converted to ISO 8601
`span.end_time`	`ended_at`	Nanosecond timestamp converted to ISO 8601
`span.trace_id`	`trace_id`	Hex-encoded trace ID
`span.parent_span_id`	`parent_span_id`	Hex-encoded span ID
`span.attributes.*`	`attributes`	All attributes preserved
`resource.service.name`	Service identification	Used for grouping

LLM Spans

To get LLM-specific features (cost calculation, token tracking), set these attributes on your spans:

Attribute	Description
`llm.provider` or `gen_ai.system`	Provider name (`openai`, `anthropic`, etc.)
`llm.model` or `gen_ai.request.model`	Model identifier
`llm.input_tokens` or `gen_ai.usage.prompt_tokens`	Input token count
`llm.output_tokens` or `gen_ai.usage.completion_tokens`	Output token count

Sessions

Attach session context to your OTLP spans via attributes:

Attribute	Description
`zeroeval.session.id`	Session ID for grouping traces
`zeroeval.session.name`	Human-readable session name

The ZeroEvalOTLPProvider stamps these automatically when you configure a session via environment variables (ZEROEVAL_SESSION_ID, ZEROEVAL_SESSION_NAME).

Tracing

Prompts

Feedback

Helpers

When to use OTLP

Endpoint Reference

Option 1: OpenTelemetry Collector

Collector Configuration

Run with Docker Compose

Run with Kubernetes

Option 2: Direct from Python

Using ZeroEvalOTLPProvider

Using standard OTLPSpanExporter

Option 3: Direct from Node.js

Attribute Mapping

LLM Spans

Sessions

​When to use OTLP

​Endpoint Reference

​Option 1: OpenTelemetry Collector

​Collector Configuration

​Run with Docker Compose

​Run with Kubernetes

​Option 2: Direct from Python

​Using ZeroEvalOTLPProvider

​Using standard OTLPSpanExporter

​Option 3: Direct from Node.js

​Attribute Mapping

​LLM Spans

​Sessions

When to use OTLP

Endpoint Reference

Option 1: OpenTelemetry Collector

Collector Configuration

Run with Docker Compose

Run with Kubernetes

Option 2: Direct from Python

Using ZeroEvalOTLPProvider

Using standard OTLPSpanExporter

Option 3: Direct from Node.js

Attribute Mapping

LLM Spans

Sessions