Traces export directly toInsight— our AI observability platform →
Tracing
Semantic Conventions

Semantic Conventions

Mantis SDK provides semantic conventions for consistent attribute naming across traces.

Overview

Semantic conventions are standardized attribute names that ensure consistent data across your traces. Use tracing.semconv to access all available conventions.

import mantisdk.tracing as tracing
 
with tracing.trace("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)

Constants are organized by namespace:

NamespacePrefixPurpose
Insightinsight.*Primary attributes for the Insight UI
Langfuse compatlangfuse.*Compatibility with Langfuse SDK spans
GenAIgen_ai.*OpenTelemetry GenAI semantic conventions
OpenInferenceopeninference.*, llm.*, input.*, output.*, tool.*Arize OpenInference conventions
MantisDKmantis.*Custom attributes added by MantisDK
Claudeclaude.*Claude Agent SDK-specific attributes

For most use cases, the Insight namespace is all you need. The other namespaces are populated automatically by auto-instrumentation or are useful when integrating with third-party tooling.

Insight Namespace

Trace-Level Attributes

For root spans (traces):

ConstantValueDescription
TRACE_NAMEinsight.trace.nameName of the trace
TRACE_INPUTinsight.trace.inputInput to the trace
TRACE_OUTPUTinsight.trace.outputOutput from the trace
TRACE_METADATAinsight.trace.metadataAdditional metadata (JSON)
TRACE_TAGSinsight.trace.tagsTags for filtering
TRACE_PUBLICinsight.trace.publicWhether trace is public
with tracing.trace("my-workflow", input=query) as span:
    # These are for root traces
    span.set_attribute(tracing.semconv.TRACE_INPUT, query)
    span.set_attribute(tracing.semconv.TRACE_OUTPUT, result)
    span.set_attribute(tracing.semconv.TRACE_METADATA, '{"source": "api"}')
    span.set_attribute(tracing.semconv.TRACE_TAGS, '["production", "v2"]')

User & Session

For tracking users and sessions:

ConstantValueDescription
USER_IDinsight.user.idUnique user identifier
SESSION_IDinsight.session.idSession identifier
with tracing.trace("workflow") as span:
    span.set_attribute(tracing.semconv.USER_ID, "user-123")
    span.set_attribute(tracing.semconv.SESSION_ID, "session-456")

Run Tracking

For linking traces to Mantis Runs (experiments):

ConstantValueDescription
RUN_IDinsight.run.idRun/experiment identifier
RUN_NAMEinsight.run.nameRun name

These attributes are automatically set when traces are created within a mantisdk.run context:

from mantisdk import run
 
with run("my-experiment") as r:
    # All traces created here automatically have RUN_ID set
    with tracing.trace("workflow") as span:
        # RUN_ID is injected automatically
        pass

Environment & Version

For deployment context:

ConstantValueDescription
ENVIRONMENTinsight.environmentDeployment environment
RELEASEinsight.releaseRelease identifier
VERSIONinsight.versionVersion string
tracing.init()
with tracing.trace("workflow") as span:
    span.set_attribute(tracing.semconv.ENVIRONMENT, "production")
    span.set_attribute(tracing.semconv.RELEASE, "v1.2.3")
    span.set_attribute(tracing.semconv.VERSION, "1.2.3")

Observation-Level Attributes

For child spans (observations):

ConstantValueDescription
OBSERVATION_TYPEinsight.observation.typeType of observation
OBSERVATION_INPUTinsight.observation.inputInput to the operation
OBSERVATION_OUTPUTinsight.observation.outputOutput from the operation
OBSERVATION_METADATAinsight.observation.metadataAdditional metadata
OBSERVATION_LEVELinsight.observation.levelLog level
OBSERVATION_STATUS_MESSAGEinsight.observation.status_messageStatus message
with tracing.span("process_data", input=data) as span:
    result = process(data)
    span.set_attribute(tracing.semconv.OBSERVATION_OUTPUT, str(result))
    span.set_attribute(tracing.semconv.OBSERVATION_METADATA, '{"items": 5}')

Model & Generation

For LLM-specific attributes:

ConstantValueDescription
MODEL_NAMEinsight.observation.model.nameModel identifier
MODEL_PARAMETERSinsight.observation.model.parametersModel parameters (JSON)
with tracing.span("llm_call") as span:
    span.set_attribute(tracing.semconv.MODEL_NAME, "gpt-4o-mini")
    span.set_attribute(tracing.semconv.MODEL_PARAMETERS, '{"temperature": 0.7}')

Observation Types

Use ObservationType for the OBSERVATION_TYPE attribute:

from mantisdk.tracing.semconv import ObservationType
 
with tracing.span("my_span") as span:
    span.set_attribute(
        tracing.semconv.OBSERVATION_TYPE,
        ObservationType.SPAN       # or "span"
    )
 
# Available types:
# ObservationType.SPAN       = "span"
# ObservationType.GENERATION = "generation"
# ObservationType.EVENT      = "event"

Observation Levels

Use ObservationLevel for log-level-like severity:

from mantisdk.tracing.semconv import ObservationLevel
 
with tracing.span("warning_case") as span:
    span.set_attribute(
        tracing.semconv.OBSERVATION_LEVEL,
        ObservationLevel.WARNING   # or "WARNING"
    )
 
# Available levels:
# ObservationLevel.DEBUG   = "DEBUG"
# ObservationLevel.DEFAULT = "DEFAULT"
# ObservationLevel.WARNING = "WARNING"
# ObservationLevel.ERROR   = "ERROR"

Langfuse Compatibility

These constants let you emit attributes that Langfuse SDK consumers already expect. If you are migrating from the Langfuse Python SDK, or need traces that are readable by both Insight and Langfuse, use these alongside (or instead of) the Insight equivalents.

Trace Attributes

ConstantValueDescription
LANGFUSE_TRACE_NAMElangfuse.trace.nameTrace name
LANGFUSE_TRACE_USER_IDuser.idUser identifier
LANGFUSE_TRACE_SESSION_IDsession.idSession identifier
LANGFUSE_TRACE_TAGSlangfuse.trace.tagsTags for filtering
LANGFUSE_TRACE_PUBLIClangfuse.trace.publicWhether trace is public
LANGFUSE_TRACE_METADATAlangfuse.trace.metadataAdditional metadata
LANGFUSE_TRACE_INPUTlangfuse.trace.inputTrace input
LANGFUSE_TRACE_OUTPUTlangfuse.trace.outputTrace output

Observation Attributes

ConstantValueDescription
LANGFUSE_OBSERVATION_TYPElangfuse.observation.typeObservation type
LANGFUSE_OBSERVATION_METADATAlangfuse.observation.metadataObservation metadata
LANGFUSE_OBSERVATION_LEVELlangfuse.observation.levelObservation log level
LANGFUSE_OBSERVATION_STATUS_MESSAGElangfuse.observation.status_messageStatus message
LANGFUSE_OBSERVATION_INPUTlangfuse.observation.inputObservation input
LANGFUSE_OBSERVATION_OUTPUTlangfuse.observation.outputObservation output

Generation Attributes

ConstantValueDescription
LANGFUSE_OBSERVATION_COMPLETION_START_TIMElangfuse.observation.completion_start_timeTime-to-first-token
LANGFUSE_OBSERVATION_MODELlangfuse.observation.model.nameModel name
LANGFUSE_OBSERVATION_MODEL_PARAMETERSlangfuse.observation.model.parametersModel parameters
LANGFUSE_OBSERVATION_USAGE_DETAILSlangfuse.observation.usage_detailsToken usage details
LANGFUSE_OBSERVATION_COST_DETAILSlangfuse.observation.cost_detailsCost details
LANGFUSE_OBSERVATION_PROMPT_NAMElangfuse.observation.prompt.namePrompt template name
LANGFUSE_OBSERVATION_PROMPT_VERSIONlangfuse.observation.prompt.versionPrompt template version

Environment

ConstantValueDescription
LANGFUSE_ENVIRONMENTlangfuse.environmentDeployment environment
LANGFUSE_RELEASElangfuse.releaseRelease identifier
LANGFUSE_VERSIONlangfuse.versionVersion string

OpenTelemetry GenAI

Standard OpenTelemetry GenAI semantic conventions (opens in a new tab). These are set automatically by OpenTelemetry-based instrumentors and can be read by any OTel-compatible backend.

Request & Response

ConstantValueDescription
GEN_AI_OPERATION_NAMEgen_ai.operation.nameOperation name (e.g. "chat")
GEN_AI_SYSTEMgen_ai.systemAI system (e.g. "openai")
GEN_AI_REQUEST_MODELgen_ai.request.modelRequested model name
GEN_AI_RESPONSE_MODELgen_ai.response.modelModel that actually responded
GEN_AI_REQUEST_TEMPERATUREgen_ai.request.temperatureSampling temperature
GEN_AI_REQUEST_MAX_TOKENSgen_ai.request.max_tokensMaximum tokens requested
GEN_AI_RESPONSE_FINISH_REASONSgen_ai.response.finish_reasonsWhy the model stopped
GEN_AI_CONVERSATION_IDgen_ai.conversation.idConversation identifier

Messages

ConstantValueDescription
GEN_AI_INPUT_MESSAGESgen_ai.input.messagesInput messages (JSON)
GEN_AI_OUTPUT_MESSAGESgen_ai.output.messagesOutput messages (JSON)

Usage

ConstantValueDescription
GEN_AI_USAGE_INPUT_TOKENSgen_ai.usage.input_tokensInput token count
GEN_AI_USAGE_OUTPUT_TOKENSgen_ai.usage.output_tokensOutput token count
GEN_AI_USAGE_COSTgen_ai.usage.costEstimated cost

Tool Attributes

ConstantValueDescription
GEN_AI_TOOL_NAMEgen_ai.tool.nameTool name
GEN_AI_TOOL_CALL_ARGUMENTSgen_ai.tool.call.argumentsTool call arguments (JSON)
GEN_AI_TOOL_CALL_RESULTgen_ai.tool.call.resultTool call result

OpenInference

OpenInference (opens in a new tab) conventions from Arize AI. These are populated by OpenInference instrumentors (e.g. openinference-instrumentation-openai).

Span Kind

ConstantValueDescription
OPENINFERENCE_SPAN_KINDopeninference.span.kindKind of span (see values below)

Span kind values are available as top-level constants:

ConstantValue
SPAN_KIND_LLMLLM
SPAN_KIND_TOOLTOOL
SPAN_KIND_AGENTAGENT
SPAN_KIND_CHAINCHAIN
SPAN_KIND_EMBEDDINGEMBEDDING
SPAN_KIND_RETRIEVERRETRIEVER
SPAN_KIND_RERANKERRERANKER
SPAN_KIND_GUARDRAILGUARDRAIL
SPAN_KIND_EVALUATOREVALUATOR
from mantisdk.tracing import semconv
 
span.set_attribute(semconv.OPENINFERENCE_SPAN_KIND, semconv.SPAN_KIND_AGENT)

LLM Attributes

ConstantValueDescription
LLM_MODEL_NAMEllm.model_nameModel name
LLM_INVOCATION_PARAMETERSllm.invocation_parametersParameters as JSON
LLM_INPUT_MESSAGESllm.input_messagesInput messages
LLM_OUTPUT_MESSAGESllm.output_messagesOutput messages
LLM_TOKEN_COUNT_PROMPTllm.token_count.promptPrompt token count
LLM_TOKEN_COUNT_COMPLETIONllm.token_count.completionCompletion token count
LLM_TOKEN_COUNT_TOTALllm.token_count.totalTotal token count
LLM_SYSTEMllm.systemLLM provider system
LLM_PROVIDERllm.providerLLM provider name

Input / Output

ConstantValueDescription
INPUT_VALUEinput.valueGeneral input value
OUTPUT_VALUEoutput.valueGeneral output value
INPUT_MIME_TYPEinput.mime_typeMIME type of the input
OUTPUT_MIME_TYPEoutput.mime_typeMIME type of the output

MIME type constants for convenience:

ConstantValue
MIME_TYPE_TEXTtext/plain
MIME_TYPE_JSONapplication/json

Tool Attributes

ConstantValueDescription
TOOL_NAMEtool.nameTool name
TOOL_DESCRIPTIONtool.descriptionTool description
TOOL_PARAMETERStool.parametersTool parameters (JSON)

MantisDK Custom

Attributes specific to MantisDK. These are set automatically by SDK instrumentation and capture data not covered by the standard namespaces.

ConstantValueDescription
MANTIS_LLM_THINKINGmantis.llm.thinkingModel thinking/reasoning content
MANTIS_LLM_COST_USDmantis.llm.cost_usdLLM call cost in USD
MANTIS_DURATION_MSmantis.duration_msTotal duration in milliseconds
MANTIS_DURATION_API_MSmantis.duration_api_msAPI call duration in milliseconds
MANTIS_NUM_TURNSmantis.num_turnsNumber of conversational turns
MANTIS_TOOL_IS_ERRORmantis.tool.is_errorWhether a tool call errored
from mantisdk.tracing import semconv
 
with tracing.span("llm_call") as span:
    span.set_attribute(semconv.MANTIS_LLM_COST_USD, 0.0032)
    span.set_attribute(semconv.MANTIS_DURATION_API_MS, 1250)

Claude-Specific

Attributes for traces produced by the Claude Agent SDK. These are populated automatically when using Claude as the underlying model.

ConstantValueDescription
CLAUDE_API_ERRORclaude.api_errorAPI error from Claude
CLAUDE_PARENT_TOOL_USE_IDclaude.parent_tool_use_idParent tool-use ID
CLAUDE_STRUCTURED_OUTPUTclaude.structured_outputStructured output content
CLAUDE_THINKING_SIGNATUREclaude.thinking.signatureThinking block signature
CLAUDE_MESSAGE_UUIDclaude.message.uuidMessage UUID
CLAUDE_SYSTEM_SUBTYPEclaude.system.subtypeSystem message subtype
CLAUDE_SYSTEM_DATAclaude.system.dataSystem message data

Complete Example

import mantisdk.tracing as tracing
from mantisdk.tracing.semconv import ObservationType, ObservationLevel
 
def agent_workflow(user_id: str, session_id: str, query: str):
    with tracing.trace("agent_session", input=query) as root:
        # User & session context
        root.set_attribute(tracing.semconv.USER_ID, user_id)
        root.set_attribute(tracing.semconv.SESSION_ID, session_id)
 
        # Environment context
        root.set_attribute(tracing.semconv.ENVIRONMENT, "production")
        root.set_attribute(tracing.semconv.VERSION, "1.0.0")
 
        # Child operation with observation attributes
        with tracing.span("llm_generation") as gen_span:
            gen_span.set_attribute(
                tracing.semconv.OBSERVATION_TYPE,
                ObservationType.GENERATION
            )
            gen_span.set_attribute(tracing.semconv.MODEL_NAME, "gpt-4o-mini")
            gen_span.set_attribute(
                tracing.semconv.MODEL_PARAMETERS,
                '{"temperature": 0.7, "max_tokens": 1000}'
            )
 
            result = call_llm(query)
 
            gen_span.set_attribute(
                tracing.semconv.OBSERVATION_OUTPUT,
                result
            )
 
        # Set trace output
        root.set_attribute(tracing.semconv.TRACE_OUTPUT, result)
 
        return result

All Constants Reference

from mantisdk.tracing import semconv
 
# --- Insight namespace ---
 
# Trace-level
semconv.TRACE_NAME
semconv.TRACE_INPUT
semconv.TRACE_OUTPUT
semconv.TRACE_METADATA
semconv.TRACE_TAGS
semconv.TRACE_PUBLIC
 
# User & Session
semconv.USER_ID
semconv.SESSION_ID
 
# Run Tracking
semconv.RUN_ID
semconv.RUN_NAME
 
# Environment
semconv.ENVIRONMENT
semconv.RELEASE
semconv.VERSION
 
# Observation-level
semconv.OBSERVATION_TYPE
semconv.OBSERVATION_INPUT
semconv.OBSERVATION_OUTPUT
semconv.OBSERVATION_METADATA
semconv.OBSERVATION_LEVEL
semconv.OBSERVATION_STATUS_MESSAGE
 
# Model
semconv.MODEL_NAME
semconv.MODEL_PARAMETERS
 
# --- Langfuse compat namespace ---
 
semconv.LANGFUSE_TRACE_NAME
semconv.LANGFUSE_TRACE_USER_ID
semconv.LANGFUSE_TRACE_SESSION_ID
semconv.LANGFUSE_TRACE_TAGS
semconv.LANGFUSE_TRACE_PUBLIC
semconv.LANGFUSE_TRACE_METADATA
semconv.LANGFUSE_TRACE_INPUT
semconv.LANGFUSE_TRACE_OUTPUT
semconv.LANGFUSE_OBSERVATION_TYPE
semconv.LANGFUSE_OBSERVATION_METADATA
semconv.LANGFUSE_OBSERVATION_LEVEL
semconv.LANGFUSE_OBSERVATION_STATUS_MESSAGE
semconv.LANGFUSE_OBSERVATION_INPUT
semconv.LANGFUSE_OBSERVATION_OUTPUT
semconv.LANGFUSE_OBSERVATION_COMPLETION_START_TIME
semconv.LANGFUSE_OBSERVATION_MODEL
semconv.LANGFUSE_OBSERVATION_MODEL_PARAMETERS
semconv.LANGFUSE_OBSERVATION_USAGE_DETAILS
semconv.LANGFUSE_OBSERVATION_COST_DETAILS
semconv.LANGFUSE_OBSERVATION_PROMPT_NAME
semconv.LANGFUSE_OBSERVATION_PROMPT_VERSION
semconv.LANGFUSE_ENVIRONMENT
semconv.LANGFUSE_RELEASE
semconv.LANGFUSE_VERSION
 
# --- GenAI namespace ---
 
semconv.GEN_AI_OPERATION_NAME
semconv.GEN_AI_SYSTEM
semconv.GEN_AI_REQUEST_MODEL
semconv.GEN_AI_RESPONSE_MODEL
semconv.GEN_AI_REQUEST_TEMPERATURE
semconv.GEN_AI_REQUEST_MAX_TOKENS
semconv.GEN_AI_RESPONSE_FINISH_REASONS
semconv.GEN_AI_CONVERSATION_ID
semconv.GEN_AI_INPUT_MESSAGES
semconv.GEN_AI_OUTPUT_MESSAGES
semconv.GEN_AI_USAGE_INPUT_TOKENS
semconv.GEN_AI_USAGE_OUTPUT_TOKENS
semconv.GEN_AI_USAGE_COST
semconv.GEN_AI_TOOL_NAME
semconv.GEN_AI_TOOL_CALL_ARGUMENTS
semconv.GEN_AI_TOOL_CALL_RESULT
 
# --- OpenInference namespace ---
 
semconv.OPENINFERENCE_SPAN_KIND
semconv.LLM_MODEL_NAME
semconv.LLM_INVOCATION_PARAMETERS
semconv.LLM_INPUT_MESSAGES
semconv.LLM_OUTPUT_MESSAGES
semconv.LLM_TOKEN_COUNT_PROMPT
semconv.LLM_TOKEN_COUNT_COMPLETION
semconv.LLM_TOKEN_COUNT_TOTAL
semconv.LLM_SYSTEM
semconv.LLM_PROVIDER
semconv.INPUT_VALUE
semconv.OUTPUT_VALUE
semconv.INPUT_MIME_TYPE
semconv.OUTPUT_MIME_TYPE
semconv.TOOL_NAME
semconv.TOOL_DESCRIPTION
semconv.TOOL_PARAMETERS
 
# Span kind values
semconv.SPAN_KIND_LLM
semconv.SPAN_KIND_TOOL
semconv.SPAN_KIND_AGENT
semconv.SPAN_KIND_CHAIN
semconv.SPAN_KIND_EMBEDDING
semconv.SPAN_KIND_RETRIEVER
semconv.SPAN_KIND_RERANKER
semconv.SPAN_KIND_GUARDRAIL
semconv.SPAN_KIND_EVALUATOR
 
# MIME types
semconv.MIME_TYPE_TEXT
semconv.MIME_TYPE_JSON
 
# --- MantisDK namespace ---
 
semconv.MANTIS_LLM_THINKING
semconv.MANTIS_LLM_COST_USD
semconv.MANTIS_DURATION_MS
semconv.MANTIS_DURATION_API_MS
semconv.MANTIS_NUM_TURNS
semconv.MANTIS_TOOL_IS_ERROR
 
# --- Claude namespace ---
 
semconv.CLAUDE_API_ERROR
semconv.CLAUDE_PARENT_TOOL_USE_ID
semconv.CLAUDE_STRUCTURED_OUTPUT
semconv.CLAUDE_THINKING_SIGNATURE
semconv.CLAUDE_MESSAGE_UUID
semconv.CLAUDE_SYSTEM_SUBTYPE
semconv.CLAUDE_SYSTEM_DATA
 
# --- Classes ---
 
# from mantisdk.tracing.semconv import ObservationType
# ObservationType.SPAN, ObservationType.GENERATION, ObservationType.EVENT
 
# from mantisdk.tracing.semconv import ObservationLevel
# ObservationLevel.DEBUG, ObservationLevel.DEFAULT,
# ObservationLevel.WARNING, ObservationLevel.ERROR

Next Steps

Context TaggingAsync Support