Insight OTel Ingestion Semantic Conventions

Insight accepts OpenTelemetry (OTLP) trace data and converts it into traces and observations. This page documents every span attribute the ingestion endpoint recognizes, how attributes are resolved across frameworks, and how observation types, usage, and costs are extracted.

How It Works

When you send OTLP spans to Insight, the ingestion processor:

1. Extracts resource attributes (set once per exporter, e.g. service.name, deployment.environment)
2. Extracts span attributes (set per span)
3. Resolves each concept (input, output, model name, etc.) by checking multiple attribute keys in priority order -- the first non-empty value wins
4. Maps the span to an observation type (GENERATION, TOOL, AGENT, etc.) using a priority-ordered mapper registry
5. Extracts usage details (token counts) and cost details from framework-specific attributes
6. Produces a trace event (from the root span or spans with trace-level attributes) and an observation event (from every span)

Attribute Priority

For each concept, the processor checks attribute keys in a defined order. For example, to resolve the model name it checks insight.observation.model.name first, then langfuse.observation.model.name, then gen_ai.response.model, and so on. The first non-empty value found is used.

Span attributes are checked before resource attributes. If a value is not found on the span, certain attributes (environment, session ID, run ID, tags) fall back to resource attributes.

Supported Frameworks

Insight recognizes attributes from the following SDKs and frameworks out of the box. You do not need to do any special configuration -- just send OTLP spans and the processor will detect the format automatically.

Attribute Reference

The tables below list every attribute key that Insight recognizes, grouped by category. Within each group, keys are listed in priority order -- earlier entries take precedence.

Trace-Level Attributes

These attributes are extracted from the root span (or any span that sets them) and applied to the trace.

Trace Name

Falls back to the OTel span name if neither is set.

Trace Input

Trace Output

Trace System Prompt

Stored in trace metadata under the system_prompt key.

Trace Metadata

Accepts a JSON string. Nested metadata keys are also supported via the langfuse.trace.metadata.* prefix pattern (e.g. langfuse.trace.metadata.myKey).

Trace Public

Boolean. Accepts true, "true", or truthy values.

Trace Tags

Accepts a JSON array string (e.g. '["prod", "v2"]') or an array value. Also checked on resource attributes as a fallback.

User and Session

User ID

Session ID

Also checked on resource attributes as a fallback.

Run ID

Also checked on resource attributes as a fallback. Automatically set when traces are created within a mantisdk.run context.

Environment and Version

Environment

Checked on both span and resource attributes. Defaults to "default" if not set.

Version

Release

Observation-Level Attributes

These attributes are extracted from every span and applied to the observation.

Observation Type

See Observation Type Mapping below for the full mapping rules.

Observation Input

Additional input sources via span events and prefix-based patterns are documented in Span Events and Prefix-Based Input/Output.

Observation Output

Vercel AI SDK special case: When both ai.response.text and ai.response.toolCalls are present, the output is combined into a structured object with role, content, and tool_calls fields.

Observation Metadata

Accepts a JSON string. Nested keys via the langfuse.observation.metadata.* prefix are also supported.

Observation Level

Valid values: DEBUG, DEFAULT, WARNING, ERROR.

If not set, defaults to ERROR when the OTel span status code is 2 (ERROR), otherwise DEFAULT.

Observation Status Message

Falls back to the OTel span status.message field.

Model and Generation

Model Name

Model Parameters

Additionally, any attributes matching the gen_ai.request.* prefix (excluding gen_ai.request.model) are collected as model parameters.

Vercel AI SDK special case: When the instrumentation scope is ai, the following attributes are extracted into model parameters:

Completion Start Time

For Vercel AI SDK, computed from ai.response.msToFirstChunk or ai.stream.msToFirstChunk added to the span start time.

Prompt Management

Prompt Name

Also extracted from Vercel AI SDK's ai.telemetry.metadata.langfusePrompt JSON field.

Prompt Version

Also extracted from Vercel AI SDK's ai.telemetry.metadata.langfusePrompt JSON field.

Observation Type Mapping

Every span is mapped to an observation type using a priority-ordered registry. Mappers are evaluated from lowest priority number (highest precedence) to highest. The first mapper that both matches and returns a type wins.

Valid Observation Types

SPAN, GENERATION, EVENT, EMBEDDING, AGENT, TOOL, CHAIN, RETRIEVER, GUARDRAIL, EVALUATOR

If no mapper matches, the span defaults to type SPAN.

Mapper Priority Order

Priority 0 -- Python SDK v3.3.0 and Earlier Override

Handles a known bug in older Langfuse Python SDK versions where generation-like spans were incorrectly labeled as span. If the scope name is langfuse-sdk, the SDK language is python, and version is 3.3.0 or earlier, the presence of generation attributes (model, usage, cost, etc.) overrides the type to GENERATION.

Priority 1 -- Direct Type Attribute

Reads langfuse.observation.type or insight.observation.type and maps directly:

Priority 2 -- OpenInference

Reads openinference.span.kind:

Priority 3 -- OTel GenAI Operation

Reads gen_ai.operation.name:

Priority 4 -- Vercel AI SDK (Generation / Embedding)

Matches when model information is present (ai.model.id, gen_ai.request.model, etc.) and the operation name matches one of:

Checked via both operation.name (prefix match) and ai.operationId (exact match).

Priority 5 -- Vercel AI SDK (Tool Calls)

Matches any ai.* operation that is not a generation or embedding:

Priority 6 -- GenAI Tool Call Detection

Matches when gen_ai.tool.name or gen_ai.tool.call.id is present. Used by Pydantic AI and other frameworks that set GenAI tool attributes without setting gen_ai.operation.name.

Result: TOOL

Priority 7 -- Model-Based Fallback

If any model-related attribute is present (langfuse.observation.model.name, gen_ai.request.model, gen_ai.response.model, llm.model_name, or model), the span is classified as a GENERATION.

Usage and Cost Extraction

Token Usage

Token usage is extracted differently depending on the instrumentation source. The processor normalizes all formats into a standard usageDetails object with keys like input, output, total, input_cached_tokens, output_reasoning_tokens, etc.

Langfuse / Insight SDK

Vercel AI SDK (scope name: ai)

Provider metadata fallback: If the extended usage attributes are not present, the processor reads ai.response.providerMetadata (a JSON string) and extracts provider-specific details:

• OpenAI: cachedPromptTokens, acceptedPredictionTokens, rejectedPredictionTokens, reasoningTokens
• Anthropic: cacheCreationInputTokens, cacheReadInputTokens
• Bedrock: usage.cacheReadInputTokens, usage.cacheWriteInputTokens, usage.cacheCreationInputTokens

Cached token counts are subtracted from the total input count to avoid double-counting.

Pydantic AI (scope name: pydantic-ai)

Generic (all other frameworks)

Any attributes matching gen_ai.usage.* or llm.token_count.* are collected. Standard key mappings:

All other suffixes are kept as-is (e.g. gen_ai.usage.reasoning_tokens becomes reasoning_tokens).

Cost

Span Events

In addition to span attributes, the processor extracts input and output from OTel span events (the events array on a span). This is used by frameworks that follow the OTel GenAI event-based conventions.

GenAI Message Events

These events are collected as the input to the observation:

Each event's attributes are included in the message object.

GenAI Choice Events

If a single choice event exists, it is returned as the output directly. Multiple choice events are returned as an array.

Legacy Semantic Kernel Events

Logfire Events Array

Logfire sends a stringified events attribute containing GenAI events. The processor parses this and extracts gen_ai.choice events as output and all other events as input.

Prefix-Based Input/Output

Some frameworks use flattened attribute keys with numeric indices to represent structured messages. The processor reassembles these into nested objects:

GenAI Prompt/Completion Prefix

Attributes starting with gen_ai.prompt.* are reassembled into an input object. Attributes starting with gen_ai.completion.* are reassembled into an output object. Used by TraceLoop and similar frameworks.

Example: gen_ai.prompt.0.content + gen_ai.prompt.0.role becomes [{ content: "...", role: "..." }]

OpenInference LLM Messages Prefix

Attributes starting with llm.input_messages.* are reassembled into input. Attributes starting with llm.output_messages.* are reassembled into output. Used by Agno, BeeAI, and OpenInference instrumentors.

Observation Name Extraction

The observation name is determined by this priority:

1. gen_ai.tool.name -- for tool-type observations
2. logfire.msg -- for Pydantic AI / Logfire spans
3. ai.toolCall.name -- for Vercel AI SDK tool calls
4. ai.telemetry.functionId + ai.operationId -- for Vercel AI SDK operations (formatted as functionId:operationId)
5. The OTel span name -- default fallback

Resource Attributes

Resource attributes are set once per exporter instance and apply to all spans in the batch. The following attributes are checked on resource attributes as a fallback when not found on span attributes:

• environment (deployment.environment.name, deployment.environment)
• session.id
• run.id
• tags
• version (service.version)
• release

Resource attributes are also stored in the observation and trace metadata under the resourceAttributes key for debugging purposes.

Quick Reference

Insight SDK Attributes (Primary Namespace)

These are the recommended attributes when instrumenting with the Mantis Insight SDK:

insight.trace.name
insight.trace.input
insight.trace.output
insight.trace.system_prompt
insight.trace.metadata
insight.trace.tags
insight.trace.public
insight.user.id
insight.session.id
insight.run.id
insight.environment
insight.release
insight.version
insight.observation.type
insight.observation.input
insight.observation.output
insight.observation.metadata
insight.observation.level
insight.observation.status_message
insight.observation.model.name
insight.observation.model.parameters

Using with MantisDK

If you are using the MantisDK Python SDK, these attributes are available as constants:

import mantisdk.tracing as tracing
 
with tracing.trace("my-workflow", input=query) as span:
    span.set_attribute(tracing.semconv.USER_ID, "user-123")
    span.set_attribute(tracing.semconv.SESSION_ID, "session-456")
    span.set_attribute(tracing.semconv.TRACE_OUTPUT, result)

See the MantisDK Semantic Conventions page for the full SDK constant reference.