How the OTel gen_ai semantic conventions map directly to evaluation-ready call data

If your OpenTelemetry instrumentation records LLM spans, you can send them to Lovelaice through an additional OTLP exporter. Check that it captures the prompt, response, model, and token fields you need: instrumentation can omit content, and the exporter cannot recover fields that were never recorded.

This guide covers the field shapes Lovelaice currently recognises, the two ingestion modes, and how multimodal and tool-call content is handled.

What OTel gen_ai conventions capture

The OpenTelemetry gen_ai semantic conventions describe span attributes for LLM calls. Lovelaice treats a span as an LLM span when it carries any gen_ai.* attribute, or an event named gen_ai.content.prompt or gen_ai.content.completion. Conventions and instrumentation versions differ; inspect a sample span against the fields below before relying on the import.

Model information:

  • •gen_ai.request.model → model name (e.g. gpt-4o, claude-3-5-sonnet)
  • •gen_ai.request.temperature, gen_ai.request.top_p, gen_ai.request.max_tokens → model parameters
  • •gen_ai.request.tools, gen_ai.request.response_format, gen_ai.request.reasoning → advanced parameters

Usage:

  • •gen_ai.usage.input_tokens, gen_ai.usage.output_tokens → token counts
  • •gen_ai.usage.cost → cost (if your instrumentation library records it)

Timing:

  • •Span start and end times → latency in milliseconds (computed from nanosecond timestamps)

Provider:

  • •gen_ai.system can identify the provider in the source trace. The current call projection does not copy it to a separate provider field; it stores the requested or response model identifier

Two prompt/completion formats

Instrumentation libraries produce attributes in one of two shapes, and both are supported:

OpenLLMetry-style attributes:

gen_ai.prompt.0.role = "system"
gen_ai.prompt.0.content = "You are a helpful assistant."
gen_ai.prompt.1.role = "user"
gen_ai.prompt.1.content = "What is the capital of France?"
gen_ai.completion.0.role = "assistant"
gen_ai.completion.0.content = "The capital of France is Paris."

OTel event-style:

event: gen_ai.content.prompt
  gen_ai.prompt.role = "user"
  gen_ai.prompt = "What is the capital of France?"

event: gen_ai.content.completion
  gen_ai.completion = "The capital of France is Paris."

The event values above are event attributes, not an event body. The importer also accepts a content attribute on these events. Both styles produce prompt, user-input, and response fields; the last completion supplies the response. Avoid sending the same content in both styles within one span, which can repeat prompt content.

Multimodal and tool-call content

Vision inputs, document attachments, and tool calls are flattened to readable text markers so evaluators can process them without special handling:

Content typeFlattened to
Image[image]
Document attachment[document: filename.pdf]
Tool call[tool_use: function_name]
Tool result[tool_result]

These markers describe content types; they do not let a text evaluator inspect the underlying image, document, or tool result. Call-level extra_info does not contain the complete raw prompt or binary content. The staged trace retains the received span data, so keep the source files available for reviews that need them.

Two ingestion modes

When you configure the OTLP endpoint, you choose between two ingestion modes, set by the API key type:

Direct mode: LLM spans become call records immediately on ingestion. These records are not attached to an evaluation experiment. Use this when you want calls recorded immediately rather than choosing an experiment during promotion.

On-demand mode: Traces are staged as pending_import. You review a batch, select which traces to promote, and they become evaluation items. Use this for high-volume pipelines where you want to sample before importing.

What goes into extra_info

Attributes that don't map to first-class evaluation fields are stored in extra_info per call:

  • •Span name, kind, and status
  • •Unhandled attributes outside the mapped gen_ai.request.*, gen_ai.usage.*, gen_ai.prompt.*, gen_ai.completion.*, gen_ai.response.*, and gen_ai.system groups
  • •Events other than the prompt/completion events, such as custom or tool events
  • •Instrumentation scope metadata (library name and version)

For example, gen_ai.my_app.session_id is kept in extra_info.unhandled_attributes. Request attributes become model parameters. Inspect the saved trace when you need fields beyond the evaluation call's extracted text; retention does not imply every custom field is exposed as a search filter.

Cost calculation

If your spans include gen_ai.usage.cost, that value is used directly. Otherwise, the backend attempts a token-based price lookup, which can return fallback rates rather than the actual model price. When no cost can be obtained, the saved call uses zero. Include the measured source cost when available and validate imported totals before using them for budgeting.

Connecting your OTLP exporter

Create a Lovelaice tracing API key, choose its ingestion mode, and configure your OTLP HTTP exporter alongside any existing exporters. The endpoint is https://api.lovelaice.io/v1/traces; pass the key in X-API-Key without a Bearer prefix.

# Python (opentelemetry-sdk)
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.lovelaice.io/v1/traces",
    headers={"X-API-Key": "<your-api-key>"},
)
// Node.js (opentelemetry-sdk-node)
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'

const exporter = new OTLPTraceExporter({
  url: 'https://api.lovelaice.io/v1/traces',
  headers: { 'X-API-Key': '<your-api-key>' },
})

Both JSON (application/json) and Protobuf (application/x-protobuf) content types are accepted.

Protobuf support

If your library sends Content-Type: application/x-protobuf, the endpoint decodes the binary payload using the official opentelemetry.proto schema and converts it to the equivalent JSON shape before processing. No configuration change is needed on your end.

FAQ

Which instrumentation libraries produce gen_ai spans?

OpenLLMetry, Traceloop, Langfuse SDK (when OTel is configured), and any library following the OTel gen_ai semantic conventions. The OpenAI and Anthropic official SDKs do not produce OTel spans natively, but wrapper libraries like openai-otel do.

Can I send non-LLM spans?

Yes. The endpoint accepts traces containing a mix of spans. Spans carrying a gen_ai.* attribute or one of the recognised prompt/completion events are projected to call records. Other spans remain in the trace record.

What happens if the same trace arrives twice?

The trace record is saved under its trace ID, but each direct ingestion creates fresh call IDs. Matching span IDs do not prevent duplicate call records. Promotion also creates fresh call IDs each time, so promoting the same trace again can duplicate calls. Choose one ingestion path for each source and avoid repeating a promotion.

Does this require any changes to my existing OTel setup?

If your existing instrumentation already emits the supported fields, add Lovelaice as an additional exporter destination. Keep your existing exporters configured. You may still need to enable content capture or map fields when your instrumentation uses a different convention version.

What model families are supported for cost calculation?

The backend pricing tables include OpenAI, Anthropic, Google, Bedrock, and OpenRouter. The OTLP projection currently tries provider lookups in order, so a fallback rate may be used even for a recognised model from another provider. Prefer a source-supplied gen_ai.usage.cost and check the imported estimate against your own cost records.