Traces export directly toInsight— our AI observability platform →
Tracing
Overview

Tracing Overview

Mantis SDK tracing provides OpenTelemetry-based distributed tracing for AI agents. It enables you to capture the full execution flow of your agent, including LLM calls, tool executions, and custom logic.

Core Concepts

Traces

A trace represents a complete request or workflow through your system. It's the top-level container that holds all related operations.

with tracing.trace("my-workflow", input=user_query) as span:
    # Everything inside is part of this trace
    result = process(user_query)

Spans

A span represents a single operation within a trace. Spans can be nested to show parent-child relationships.

with tracing.trace("workflow") as root:
    with tracing.span("step_1") as s1:
        # Child of root
        pass
    with tracing.span("step_2") as s2:
        # Another child of root
        pass

Attributes

Attributes are key-value pairs attached to spans that provide context. Mantis SDK provides semantic conventions for common attributes.

span.set_attribute(tracing.semconv.USER_ID, "user-123")
span.set_attribute(tracing.semconv.SESSION_ID, "session-456")
span.set_attribute("custom_key", "custom_value")

Tracing API

Mantis SDK provides three main ways to create spans:

FunctionPurposeUse Case
trace()Create root spansMain workflow entry points
span()Create child spansSub-operations within a trace
tool()Create tool spansExternal calls, API requests

Decorators vs Context Managers

All three functions work as both decorators and context managers:

# Decorator - auto-captures input/output
@tracing.trace
def my_function(query: str) -> dict:
    return {"result": query.upper()}
 
# Context manager - explicit control
with tracing.trace("my-operation", input=query) as span:
    result = do_work()
    span.set_attribute(tracing.semconv.TRACE_OUTPUT, result)

Data Flow

Your Application
      │
      ▼
  tracing.trace() / span() / tool()
      │
      ▼
  OpenTelemetry SDK
      │
      ▼
  BatchSpanProcessor
      │
      ▼
  Insight Exporter (OTLP)
      │
      ▼
  Mantis Insight Backend

Module Structure

import mantisdk.tracing as tracing
 
# Initialization
tracing.init()           # Initialize tracing
tracing.instrument()     # Enable auto-instrumentation
tracing.shutdown()       # Graceful shutdown
tracing.flush()          # Force flush spans
 
# Span creation (sync)
tracing.trace            # Root spans (decorator/context manager)
tracing.span             # Child spans (context manager)
tracing.tool             # Tool spans (context manager)
 
# Span creation (async)
tracing.atrace           # Async root spans
tracing.aspan            # Async child spans
 
# Utilities
tracing.get_current_span()  # Get active span
tracing.insight_exporter()  # Create Insight exporter
 
# Semantic conventions
tracing.semconv.USER_ID
tracing.semconv.SESSION_ID
tracing.semconv.TRACE_INPUT
tracing.semconv.TRACE_OUTPUT
# ... and more

Next Steps

QuickstartInitialization