Python Tracing The mutagent.tracing module provides OTel-aligned span instrumentation with no external collector required. It ships as part of mutagent-sdk.
Install Initialize Call init_tracing once at application startup:
from mutagent.tracing import init_tracing init_tracing( api_key = "mt_xxxxxxxxxxxx" )
Or use the MUTAGENT_API_KEY environment variable and skip the argument:
import os from mutagent.tracing import init_tracing init_tracing( api_key = os.environ[ "MUTAGENT_API_KEY" ])
Decorate Functions The @trace decorator is the simplest way to add tracing. It captures the function’s input arguments, return value, duration, and any exceptions:
from mutagent.tracing import init_tracing, trace init_tracing( api_key = "mt_xxxxxxxxxxxx" ) @trace ( kind = "agent" ) def run_support_agent ( query : str ) -> str : # All inputs, outputs, and timing are captured automatically response = call_llm(query) return response
Works with async functions too:
@trace ( kind = "agent" ) async def run_async_agent ( query : str ) -> str : response = await call_llm_async(query) return response
@trace ParametersParameter Type Default Description kindSpanKind"custom"Span kind — see table below namestr | Nonefunction name Override the span name
Span Kinds Kind Value Use Case llm.chat"llm.chat"Chat completions llm.completion"llm.completion"Text completions llm.embedding"llm.embedding"Embedding generation chain"chain"Sequential pipelines agent"agent"Agent execution graph"graph"Graph workflows node"node"Graph nodes tool"tool"Tool invocations retrieval"retrieval"RAG retrieval guardrail"guardrail"Safety checks custom"custom"Any other use case
Low-Level API For fine-grained control, use start_span and end_span directly:
from mutagent.tracing import ( init_tracing, start_span, end_span, SpanOptions, SpanEndOptions, SpanIO, SpanMetrics, SpanKind, SpanStatus, ) init_tracing( api_key = "mt_xxxxxxxxxxxx" ) span = start_span(SpanOptions( kind = "chain" , name = "my-pipeline" , input = SpanIO( text = "user query here" ), )) # ... do work ... if span: end_span(span, SpanEndOptions( status = "ok" , output = SpanIO( text = "pipeline result" ), metrics = SpanMetrics( model = "gpt-4o" , provider = "openai" , input_tokens = 150 , output_tokens = 50 , total_tokens = 200 , ), ))
Shutdown For scripts or short-lived applications, flush remaining buffered spans before exit:
import asyncio from mutagent.tracing import shutdown_tracing # shutdown_tracing is a coroutine — must be awaited asyncio.run(shutdown_tracing()) # or, inside an async function: # await shutdown_tracing()
The SDK registers an atexit handler that flushes remaining spans automatically. Calling shutdown_tracing() explicitly is recommended for serverless functions or any process that exits quickly after the last traced call.
init_tracing OptionsParameter Type Default Description api_keystrRequired MutagenT API key (mt_ prefix) endpointstrhttps://api.mutagent.ioAPI endpoint URL environmentstr | NoneNoneEnvironment name (e.g., production) batch_sizeint10Spans buffered before flush batch_interval_msint5000Flush interval in milliseconds debugboolFalseLog span events to stdout
Framework Integrations For automatic tracing without any code changes to your LLM calls, use the Python integration packages:
Anthropic wrap_anthropic(client) — zero-change tracing for Claude
OpenAI MutagentOpenAI — drop-in OpenAI client replacement
LangChain MutagentCallbackHandler — traces chains, tools, and retrievers
LangGraph MutagentCallbackHandler — automatic graph node tracing
TypeScript Equivalent The TypeScript tracing module (@mutagent/sdk/tracing) provides the same concepts: initTracing, shutdownTracing, @trace() decorator, and startSpan/endSpan. See the TypeScript tracing guide . 
