🔭OpenTelemetry Integration

Revenium accepts OTLP (OpenTelemetry Protocol) data directly from your instrumented applications. If your app already emits telemetry via an OTLP exporter—using LangChain, the OpenAI Python SDK with OTel instrumentation, or your own custom spans—you can point it at Revenium with a few lines of configuration and start seeing AI usage data immediately.

This page covers Revenium-specific configuration. It assumes you already understand OTLP and have an exporter set up.

---

Endpoints

Revenium accepts both OTLP/HTTP and OTLP/gRPC.

OTLP/HTTP

Path	Accepts
https://api.revenium.io/v2/otlp/v1/traces	Traces (JSON or protobuf)
https://api.revenium.io/v2/otlp/v1/logs	Logs (JSON or protobuf)
https://api.revenium.io/v2/otlp/v1/metrics	Metrics (JSON or protobuf)
https://api.revenium.io/v2/otlp	Unified (traces + logs + metrics in one request)

Both application/json and application/x-protobuf content types are accepted.

OTLP/gRPC

Host	Port	Service
api.revenium.io	4317	opentelemetry.proto.collector.trace.v1.TraceService

The gRPC endpoint accepts traces. For logs and metrics, use the HTTP endpoints.

---

Authentication

Your Revenium API key goes in the Authorization header as a Bearer token. Both Authorization: Bearer and x-api-key headers are accepted.

Authorization: Bearer hak_your_tenant_yourkey

or

x-api-key: hak_your_tenant_yourkey

For frameworks or SDKs that cannot set custom headers (e.g., some CLI tools), you can pass the API key as an OTLP resource attribute instead:

export OTEL_RESOURCE_ATTRIBUTES="revenium.api_key=hak_your_tenant_yourkey"

This travels inside the encrypted OTLP payload body and is secure over TLS. Note: this fallback is not available for OTLP/gRPC (interceptors run before message deserialization on the gRPC path).

You can find your API key in the Revenium app under Settings → API Keys.

---

Quick Start

1. Configure your OTLP exporter

Set the exporter endpoint and auth header. The exact env vars depend on your SDK, but the standard OpenTelemetry environment variables work with all OTel SDKs:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.revenium.io/v2/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer hak_your_tenant_yourkey"

If your framework uses separate endpoint vars for signals:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.revenium.io/v2/otlp/v1/traces
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://api.revenium.io/v2/otlp/v1/logs
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer hak_your_tenant_yourkey"

Python SDK note: The Python OpenTelemetry SDK requires header values in OTEL_EXPORTER_OTLP_HEADERS to be percent-encoded. Use Bearer%20 instead of Bearer (with a space):

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20hak_your_tenant_yourkey"

Other SDKs (Node.js, Go, Java) accept the unencoded space. If data is not arriving from a Python app, check for a "Header format invalid" error and switch to the percent-encoded form.

2. Send a trace

Run your application normally. The OTel instrumentation in your app creates spans when AI calls are made, and the exporter sends them to Revenium.

3. See it in Revenium

Go to System & Transaction Logs or Trace Analytics. If the span contained recognized GenAI attributes (see below), you'll see token counts, model, provider, and cost data populated automatically.

---

Supported Frameworks and SDKs

Revenium auto-detects the source based on resource attributes and instrumentation scope names. No special configuration in Revenium is required—just point your exporter at the endpoint.

Python: opentelemetry-instrumentation-openai

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

tracer_provider = TracerProvider()
exporter = OTLPSpanExporter(
    endpoint="https://api.revenium.io/v2/otlp/v1/traces",
    headers={"Authorization": "Bearer hak_your_tenant_yourkey"},
)
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

Python: opentelemetry-instrumentation-anthropic

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

tracer_provider = TracerProvider()
exporter = OTLPSpanExporter(
    endpoint="https://api.revenium.io/v2/otlp/v1/traces",
    headers={"Authorization": "Bearer hak_your_tenant_yourkey"},
)
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
AnthropicInstrumentor().instrument(tracer_provider=tracer_provider)

Python: LangChain via OpenInference or OpenLLMetry

Both OpenInference and OpenLLMetry emit GenAI semantic convention spans. Configure the OTLP exporter as shown above; Revenium picks them up automatically.

Node.js: @opentelemetry/instrumentation-openai

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { OpenAIInstrumentation } = require('@opentelemetry/instrumentation-openai');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://api.revenium.io/v2/otlp/v1/traces',
    headers: { 'Authorization': 'Bearer hak_your_tenant_yourkey' },
  }),
  instrumentations: [new OpenAIInstrumentation()],
});

sdk.start();

Go SDK (gRPC)

import (
    "context"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "google.golang.org/grpc/credentials"
)

ctx := context.Background()
exporter, _ := otlptracegrpc.New(ctx,
    otlptracegrpc.WithEndpoint("api.revenium.io:4317"),
    otlptracegrpc.WithTLSCredentials(credentials.NewClientTLSFromCert(nil, "")),
    otlptracegrpc.WithHeaders(map[string]string{
        "Authorization": "Bearer hak_your_tenant_yourkey",
    }),
)

OpenTelemetry Collector

If you're already running an OTel Collector, add Revenium as an exporter:

exporters:
  otlphttp/revenium:
    endpoint: https://api.revenium.io/v2/otlp
    headers:
      Authorization: "Bearer hak_your_tenant_yourkey"

service:
  pipelines:
    traces:
      exporters: [otlphttp/revenium]
    logs:
      exporters: [otlphttp/revenium]

---

What Gets Captured Automatically

Revenium reads OpenTelemetry GenAI semantic conventions from your spans and log records. If your instrumentation library follows the spec, these fields populate automatically—no extra code required.

Token Counts

GenAI Attribute	Revenium Field	Notes
gen_ai.usage.input_tokens	Input tokens	Also accepts deprecated gen_ai.usage.prompt_tokens
gen_ai.usage.output_tokens	Output tokens	Also accepts deprecated gen_ai.usage.completion_tokens
gen_ai.usage.cache_read_input_tokens	Cache read tokens	Also accepts gen_ai.usage.cache_read_tokens
gen_ai.usage.cache_creation_input_tokens	Cache creation tokens	Also accepts gen_ai.usage.cache_creation_tokens

Model and Provider

GenAI Attribute	Revenium Field	Notes
gen_ai.response.model	Model	Preferred; falls back to gen_ai.request.model
gen_ai.provider.name	Provider	Also accepts deprecated gen_ai.system
gen_ai.request.model	Model (request)	Used when response model is absent

Operation Type and Finish Reason

GenAI Attribute	Revenium Field	Values
gen_ai.operation.name	Operation type	chat → Chat; embeddings → Embed; text_completion → Chat; generate_content → Chat
gen_ai.response.finish_reasons	Stop reason	Array; Revenium uses the first element — see mapping table below

Finish reason mapping:

gen_ai.response.finish_reasons value	Revenium stop reason
stop, end_turn	End
max_tokens, length	Token Limit
stop_sequence	End Sequence
content_filter	Error
tool_calls, function_call	End
(any other value)	End

Request Parameters

GenAI Attribute	Revenium Field	Notes
gen_ai.request.temperature	Temperature	Standard OTel attribute; captured automatically
gen_ai.response.id	System fingerprint	Response identifier from the model provider

Timing and Errors

Span start/end nanosecond timestamps (startTimeUnixNano, endTimeUnixNano) are used to populate request time, response time, and duration. Error details are read from exception.message (primary) and error.type (fallback). HTTP status codes are read from http.response.status_code.

Infrastructure Context

Standard OTel Attribute	Revenium Field
deployment.environment	Environment
cloud.region	Region

Span Hierarchy

traceId, spanId, and parentSpanId from spans are mapped to Revenium's trace, transaction, and parent transaction fields respectively. This powers the Trace Analytics dependency tree and waterfall visualizations.

Revenium skips spans with gen_ai.operation.name of execute_tool, invoke_agent, or create_agent — these are orchestration spans, not LLM calls. Only spans that represent actual model invocations are metered.

---

Deep Attribution with revenium.* Attributes

Standard OTel tells you what happened — which model was called, how many tokens were used. revenium.* attributes tell Revenium why it happened and who it happened for. This is what enables per-customer, per-product, per-agent, and per-job cost attribution that goes beyond what the OTel spec captures.

Set these on spans or log records (record-level attributes take precedence over resource-level attributes, so you can set defaults at the resource level and override on individual spans).

System Fingerprint

revenium.system.fingerprint is one of Revenium's most powerful attribution tools. It lets you tag each AI call with an identifier that represents what configuration produced it — your system prompt version, your prompt template ID, your agent configuration hash, or any other identifier you use to distinguish one variant from another.

This is how you answer questions like: "Which version of my system prompt is more expensive?" or "Did my prompt optimization actually reduce costs?" Standard OTel has no equivalent.

Attribute	Revenium Field	Notes
gen_ai.response.id	System fingerprint	Populated automatically if your provider returns a response ID
revenium.system.fingerprint	System fingerprint	Use this to set your own fingerprint — overrides gen_ai.response.id when both are present

span.set_attribute("revenium.system.fingerprint", "system-prompt-v3-2025-03-12")

Use any value that uniquely identifies the configuration: a version string, a git SHA, a prompt template ID, or a hash of your system prompt content.

Organization and Product

Attribute	Revenium Field	Example
revenium.organization.name	Organization	"acme-corp"
revenium.product.name	Product	"document-summarizer"
revenium.subscription.id	Subscription	"enterprise-plan-q1"

Subscribers and Users

Attribute	Revenium Field	Example
revenium.subscriber.id	Subscriber ID	"user-12345"
revenium.subscriber.email	Subscriber email	"[email protected]"
revenium.subscriber.credential.name	Credential name	"api-key-prod"
revenium.subscriber.credential.value	Credential value	"pk-abc123"

Agents and Agentic Workflows

Attribute	Revenium Field	Example
revenium.agent.name	Agent	"support-agent-v2"
revenium.task.type	Task type	"summarize"
revenium.trace.type	Trace type	"rag-pipeline"
revenium.trace.name	Trace name	"support-ticket-resolution"
revenium.transaction.name	Transaction name	"retrieve-context"

Squads (Multi-Agent Teams)

Attribute	Revenium Field	Example
revenium.squad.id	Squad ID	"squad-billing"
revenium.squad.name	Squad name	"Billing Support Squad"
revenium.squad.role	Role in squad	"orchestrator"

Agentic Jobs

Attribute	Revenium Field	Example
revenium.job.id	Job ID	"job-20250312-001"
revenium.job.name	Job name	"nightly-report-gen"
revenium.job.type	Job type	"batch"
revenium.job.version	Job version	"2.1.0"

Other Fields

Attribute	Revenium Field	Notes
revenium.operation.subtype	Operation subtype	Free-form sub-classification
revenium.retry.number	Retry number	Integer; useful for tracking retry cost
revenium.request.stream	Is streamed	Boolean
revenium.middleware.source	Middleware source	Identifies the SDK or integration layer

Setting Attribution Attributes (Python Example)

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("llm-call") as span:
    span.set_attribute("revenium.organization.name", "acme-corp")
    span.set_attribute("revenium.product.name", "support-bot")
    span.set_attribute("revenium.agent.name", "tier1-support-agent")
    span.set_attribute("revenium.task.type", "classify-ticket")
    span.set_attribute("revenium.subscriber.id", "user-98765")
    span.set_attribute("revenium.system.fingerprint", "system-prompt-v3")
    # ... make your LLM call

You can also set defaults at the resource level so they apply to all spans from your service, and override on individual spans where needed:

from opentelemetry.sdk.resources import Resource

resource = Resource(attributes={
    "service.name": "support-bot",
    "revenium.organization.name": "acme-corp",
    "revenium.product.name": "support-bot",
})

Record-level (span) attributes always win over resource-level attributes when the same key is set at both levels.

---

Troubleshooting

Data not appearing in Revenium

Check that:

1. Your API key starts with hak_ and is in the correct format (hak_<tenant>_<secret>).

2. Your spans include at least one of the following so Revenium can route them to the correct mapper:

   • gen_ai.provider.name or gen_ai.system attribute (resource-level or span-level)

   • An instrumentation scope name starting with gen_ai, openai, anthropic, opentelemetry.instrumentation.openai, or opentelemetry.instrumentation.anthropic

3. The exporter endpoint URL is correct and includes the full path (/v2/otlp/v1/traces, not /v2/otlp), unless your SDK sends all signals to a single base URL—in that case, use /v2/otlp.

Tokens showing as zero

Verify your instrumentation library emits gen_ai.usage.input_tokens and gen_ai.usage.output_tokens (or their deprecated equivalents gen_ai.usage.prompt_tokens / gen_ai.usage.completion_tokens) as numeric attributes on the span.

Tool call and agent orchestration spans are not appearing

This is expected behavior. Revenium filters out execute_tool, invoke_agent, and create_agent spans because they are not LLM calls. Only spans that represent actual model invocations produce metering records.

---

Related Documentation

• Integration Options for AI Metering — SDK and direct API options

• Trace Analytics — Visualizing trace hierarchies and costs

• Cost & Performance Alerts — Set thresholds on usage and cost

• System & Transaction Logs — Per-transaction detail view