November 2026 release is live Read More

OpenTelemetry FAQ

Reference for the Connect OpenTelemetry to Mavvrik and Connect OpenRouter agents guides.

OpenTelemetry connection

What Mavvrik reads from your traces

Element

Source in your telemetry

Used for

Agent identity

The attribute you nominate, or mvk.agent_id and mvk.agent_name

Grouping all activity under a named agent

Model and provider

Model call span attributes

Cost rate selection

Token usage

Input and output token counts on model call spans

List Price calculation

Reported cost

Cost reported by the sender, where present

The Reported cost view

Session

Session attributes, where present

Session-level grouping

Tags

Span attribute mvk.tags

The Tags column in Cost Items

Spans that contain no model call are ingested but contribute no cost. One model request counts as one LLM call. Routing and proxy spans added by gateways are not counted as separate calls.

Supported protocols

Item

Value

Protocol

OTLP over HTTP

Encoding

http/protobuf

Signals

Traces

Not supported

http/json, OTLP over gRPC

If your applications use gRPC, send to your own OpenTelemetry Collector and let it forward to Mavvrik over http/protobuf.

How Mavvrik identifies agents

Mavvrik resolves agent identity in this order:

  1. The attribute named in Agent ID attribute, read from the span.

  2. The same attribute, read from the resource.

  3. The resource attributes mvk.agent_id and mvk.agent_name.

Use one method consistently across the agents on a connection:

  • Resource attributes: set mvk.agent_id and mvk.agent_name on the resource in your SDK. Leave Agent ID attribute empty.

  • Your own attribute: if your traces already carry an agent identifier, enter its name in Agent ID attribute.

One connection supports any number of agents. Send a distinct agent ID for each agent. Traces without an agent ID are grouped as Unattributed.

Adding tags

Set the span attribute mvk.tags to a JSON object on each span you want tagged:

Python
span.set_attribute("mvk.tags", '{"team": "finops", "env": "prod"}')

Tags appear in the Tags column of Agent Cost Items. Tags set only as resource attributes (for example in OTEL_RESOURCE_ATTRIBUTES) are not read. Tags are not supported on OpenRouter connections.

Cost views

Three views are available under Agent Cost → Cost Options:

View

Basis

On an OpenRouter connection

List Price

Token usage multiplied by the model’s published list price

May differ from Reported where OpenRouter applies its own rate or fees

Actual

Provider billing data, where Mavvrik holds it for the account

Not populated by OpenRouter traffic alone

Reported

Cost supplied by the sender on each request

What OpenRouter billed. Matches your OpenRouter invoice, including BYOK upstream cost

Limitations

  • Cost needs model call attributes. If spans do not record model, provider and token counts, Mavvrik cannot calculate List Price for those calls.

  • Connection changes are not retrospective. A change to the Agent ID attribute applies to traces received after the change.

  • Traces are stored as received. If spans carry prompt or response content, it is stored. Remove those attributes at the sender or Collector if you do not want them retained.

  • Data appears within 24 hours. Typical latency is under one hour.

Key rotation

Contact your Mavvrik administrator to rotate the key. After rotation, update the Authorization header on every sender using the connection, including the OpenRouter Broadcast destination. Senders holding the previous key receive HTTP 401.

Troubleshooting

Symptom

Cause

Resolution

HTTP 401

The Authorization header is incomplete or stale

Copy the headers again from the connection. The value must begin with Bearer and contain the full key

No export attempted by the sender

Unsupported encoding

Set the protocol to http/protobuf. http/json and gRPC are rejected

All activity appears as Unattributed

The Agent ID attribute does not match the attribute your traces carry

Edit the connection and set Agent ID attribute to the exact attribute name. The change applies to new traces only

Agents appear, but LLM calls are zero

Spans do not carry model call attributes

Confirm that your instrumentation records model, provider and token counts on model call spans

List Price shows 0

The model is free, or no list price is held

Use the Reported view, or contact support to add pricing for the model

Tags column is empty

Tags are set as resource attributes

Set mvk.tags on each span

No data after 24 hours

Traces are not reaching Mavvrik

Check sender logs for export errors, then contact Mavvrik support