Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getnetra.ai/llms.txt

Use this file to discover all available pages before exploring further.

A span represents a single unit of execution within a trace. Each span captures a discrete operation performed during a request lifecycle, such as an API call, model invocation, or tool execution, along with its timing, cost, and execution context. Spans are organized hierarchically within a trace, allowing you to understand how individual operations contribute to overall latency, cost, and system behavior.

​
Span Types

Netra supports five span types, each designed to categorize specific kinds of operations:
Span TypeEnum ValueDescriptionUse Case
SpanSpanType.SPANDefault type for general operationsFunction calls, business logic, generic operations
GenerationSpanType.GENERATIONLLM text or image generationChat completions, text generation, image generation
EmbeddingSpanType.EMBEDDINGVector embedding operationsText-to-vector conversions, embedding API calls
ToolSpanType.TOOLTool or function executionFunction calls, API requests, database queries
AgentSpanType.AGENTAI agent reasoning or decisionsAgent orchestration, multi-step reasoning, autonomous tasks

​
When to Use Each Type

Span (Default)
  • General-purpose operations that don’t fit other categories
  • Business logic and data processing
  • Workflow orchestration steps
Generation
  • OpenAI, Anthropic, or other LLM completions
  • Image generation (DALL-E, Stable Diffusion)
  • Text-to-speech or speech-to-text operations
Embedding
  • Converting text to vectors for similarity search
  • Embedding API calls (OpenAI embeddings, Cohere embed)
  • Document embedding pipelines
Tool
  • External API calls
  • Database operations
  • File system operations
  • Any function that performs a specific action
Agent
  • AI agents making autonomous decisions
  • ReAct-style reasoning loops
  • Multi-step task execution
  • Agent frameworks (LangGraph, CrewAI, AutoGen)

​
Specifying Span Types

When creating manual spans, specify the type using the as_type parameter: 
from netra import Netra, SpanType

# Generation span for LLM calls
with Netra.start_span("chat-completion", as_type=SpanType.GENERATION) as span:
    pass

# Embedding span for vector operations
with Netra.start_span("generate-embedding", as_type=SpanType.EMBEDDING) as span:
    pass

# Tool span for function calls
with Netra.start_span("search-database", as_type=SpanType.TOOL) as span:
    pass

# Agent span for AI agents
with Netra.start_span("research-agent", as_type=SpanType.AGENT) as span:
    pass
Auto-instrumentation automatically assigns the correct span type based on the operation. For example, OpenAI chat completions are automatically marked as GENERATION spans.

​
Viewing Spans in Netra

Netra displays spans within the Trace Timeline as a hierarchical view of all operations executed during a request. Selecting a span highlights it in the timeline and surfaces its details in the Metadata panel, allowing you to inspect execution context without leaving the trace. Different span types are visually distinguished to help you quickly identify agent execution, model generations, and tool calls. Span

​
Span Attributes

Each span in Netra captures attributes in the Metadata panel. Some attributes are common across all span types, while others are specific to certain types.
AttributeDescriptionApplies To
library.nameName of the tracing libraryAll
library.versionVersion of the tracing libraryAll
sdk.nameName of the SDKAll
netra.session_idSession identifier (if specified)All
netra.user_idUser identifier (if specified)All
netra.duration_msDuration of the operation in millisecondsAll
netra.statusSuccess or error statusAll
span_typeType of the spanAll
netra.instrumentation.nameLLM provider (e.g., “openai”, “anthropic”)Generation
gen_ai.request.modelModel used for the requestGeneration
gen_ai.response.modelModel returned in the responseGeneration
gen_ai.usage.prompt_tokensNumber of input tokensGeneration
gen_ai.usage.completion_tokensNumber of output tokensGeneration
llm.usage.total_tokensTotal tokens usedGeneration
llm.response.durationResponse time from the LLMGeneration
gen_ai.performance.time_to_first_tokenTime to receive the first tokenGeneration
netra.modelThe embedding model usedEmbedding
cost.total_usdTotal cost in USDAgent
Generation spans also show additional data in Chat Preview including system prompt, user input, and assistant response.

​
Custom Attributes

You can add custom attributes to any span for additional context using set_attribute() / setAttribute(). See Manual Tracing for detailed examples of working with span attributes.

​
Adding Spans to Datasets

Spans can be added to a dataset using Add to Dataset for reuse in evaluations and testing workflows. This is useful for:
  • Building evaluation datasets from production data
  • Creating test cases for regression testing
  • Analyzing specific types of operations
See Evaluations for more details.

​
Learn More

Last modified on March 17, 2026