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 Type | Enum Value | Description | Use Case |
|---|
| Span | SpanType.SPAN | Default type for general operations | Function calls, business logic, generic operations |
| Generation | SpanType.GENERATION | LLM text or image generation | Chat completions, text generation, image generation |
| Embedding | SpanType.EMBEDDING | Vector embedding operations | Text-to-vector conversions, embedding API calls |
| Tool | SpanType.TOOL | Tool or function execution | Function calls, API requests, database queries |
| Agent | SpanType.AGENT | AI agent reasoning or decisions | Agent 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 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.
| Attribute | Description | Applies To |
|---|
library.name | Name of the tracing library | All |
library.version | Version of the tracing library | All |
sdk.name | Name of the SDK | All |
netra.session_id | Session identifier (if specified) | All |
netra.user_id | User identifier (if specified) | All |
netra.duration_ms | Duration of the operation in milliseconds | All |
netra.status | Success or error status | All |
span_type | Type of the span | All |
netra.instrumentation.name | LLM provider (e.g., “openai”, “anthropic”) | Generation |
gen_ai.request.model | Model used for the request | Generation |
gen_ai.response.model | Model returned in the response | Generation |
gen_ai.usage.prompt_tokens | Number of input tokens | Generation |
gen_ai.usage.completion_tokens | Number of output tokens | Generation |
llm.usage.total_tokens | Total tokens used | Generation |
llm.response.duration | Response time from the LLM | Generation |
gen_ai.performance.time_to_first_token | Time to receive the first token | Generation |
netra.model | The embedding model used | Embedding |
cost.total_usd | Total cost in USD | Agent |
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
