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.
Netra’s manual tracing capabilities allow you to track external API calls and custom operations with detailed observability. This section covers how to use the custom span tracking utility to monitor your application’s behavior at a granular level.
Getting Started with Manual Tracing
To start manual tracing, you’ll need to:
- Import the required classes
- Create a new span
- Track your operations
- Add relevant attributes and events
Here’s a basic example:
Start a New Span
from netra import Netra, UsageModel, ActionModel
from netra.instrumentation.instruments import InstrumentSet
# Initialize the SDK (if not already initialized)
Netra.init(app_name="Your Application Name", instruments={InstrumentSet.OPENAI})
# Start a new span
with Netra.start_span("image_generation") as span:
# Your API calls or operations here
# ...
Span Type Specification
You can specify the type of span while using the utility. Currently, we support the following types:
from netra import Netra, SpanType
from netra.instrumentation.instruments import InstrumentSet
# Initialize the SDK (if not already initialized)
Netra.init(app_name="Your Application Name", instruments={InstrumentSet.OPENAI})
# Start a new span
with Netra.start_span("tool_call", as_type=SpanType.TOOL) as tool_span:
# Denotes a tool span
# ...
with Netra.start_span("vectordb_embedding", as_type=SpanType.EMBEDDING) as embedding_span:
# Denotes an embedding span
# ...
with Netra.start_span("image_generation", as_type=SpanType.GENERATION) as generation_span:
# Denotes a generation span
# ...
with Netra.start_span("status_tracking", as_type=SpanType.SPAN) as span:
# Denotes a normal span
# ...
Local Span Blocking
You can block spans locally within a particular span-scope:
from netra import Netra, UsageModel, ActionModel
from netra.instrumentation.instruments import InstrumentSet
# Initialize the SDK (if not already initialized)
Netra.init(app_name="Your Application Name", instruments={InstrumentSet.OPENAI})
# Start a new span
with Netra.start_span("image_generation", attributes={"blocked_spans": ["POST"]}) as span:
# Your API calls or operations here
# ...
Setting Span Attributes
You can add various attributes to your spans to provide more context about the operation:
# Set span attributes
span.set_prompt("A beautiful sunset over mountains")
span.set_negative_prompt("blurry, low quality")
span.set_model("dall-e-3")
span.set_llm_system("openai")
Tracking Usage Data
Use the UsageModel to track resource usage and costs:
# Create usage data
usage_data = [
UsageModel(
model="dall-e-3",
usage_type="image_generation",
units_used=1,
cost_in_usd=0.02
)
]
# Set usage data on span
span.set_usage(usage_data)
Adding Custom Attributes
Add custom attributes to provide additional context about your operation:
# Add custom attributes
span.set_attribute("image_size", "1024x1024")
span.set_attribute("processing_time", 2.5) # in seconds
span.set_attribute("retry_count", 0)
Adding Action Tracking
Enable custom action tracking in your application using our action tracking utility. The action tracking utility in Netra follows the given schema:
[
{
"action": str, # Type of action (e.g., "DB", "API", "CACHE")
"action_type": str, # Action subtype (e.g., "INSERT", "SELECT", "CALL")
"affected_records": [ # Optional: List of records affected
{
"record_id": str, # ID of the affected record
"record_type": str # Type of the record
}
],
"metadata": Dict[str, str], # Additional metadata as key-value pairs
"success": bool # Whether the action succeeded
}
]
# Track database operations and other actions
action = ActionModel(
action="DB",
action_type="INSERT",
affected_records=[
{"record_id": "user_123", "record_type": "user"},
{"record_id": "profile_456", "record_type": "profile"}
],
metadata={
"table": "users",
"operation_id": "tx_789",
"duration_ms": "45"
},
success=True
)
span.set_action([action])
Recording Events
Track important events during the span’s lifecycle:
# Add events
span.add_event("generation_started", {"step": "1", "status": "processing"})
span.add_event("processing_completed", {"step": "rendering"})
span.add_event("image_generated", {"status": "success", "output_format": "png"})
Real-world Examples
1. Image Generation Workflow
from netra import Netra, UsageModel
# Start span for image generation
with Netra.start_span("image_generation") as span:
# Set initial attributes
span.set_prompt("A futuristic cityscape")
span.set_model("dall-e-3")
span.set_llm_system("openai")
# Track usage
usage_data = [
UsageModel(
model="dall-e-3",
usage_type="image_generation",
units_used=1,
cost_in_usd=0.02
)
]
span.set_usage(usage_data)
# Record workflow events
span.add_event("generation_started", {"status": "processing"})
# Your actual image generation code here
# ...
span.add_event("image_generated", {"status": "success"})
# Record API calls
api_action = ActionModel(
action="API",
action_type="CALL",
metadata={
"endpoint": "/api/v1/process",
"method": "POST",
"status_code": 200,
"duration_ms": "120"
},
success=True
)
span.set_action([api_action])
2. API Request Processing
from netra import Netra, UsageModel
# Start span for API request
with Netra.start_span("api_request") as span:
# Set request attributes
span.set_attribute("endpoint", "/v1/images/generate")
span.set_attribute("method", "POST")
span.set_attribute("request_id", "req_123")
# Track request processing
span.add_event("request_received", {"timestamp": "2024-01-15T10:30:00Z"})
# Process request
# ...
span.add_event("request_processed", {"status": "success", "duration_ms": 150})
3. Batch Processing
from netra import Netra, UsageModel
# Start span for batch processing
with Netra.start_span("batch_processing") as span:
# Set batch attributes
span.set_attribute("batch_size", 100)
span.set_attribute("batch_id", "batch_123")
span.set_attribute("operation", "image_enhancement")
# Track batch processing
span.add_event("batch_started", {"total_items": 100})
# Process items in batch
processed_count = 0
for item in batch_items:
# Process item
# ...
processed_count += 1
if processed_count % 10 == 0:
span.add_event("progress_update", {
"processed": processed_count,
"percentage": (processed_count / len(batch_items)) * 100
})
span.add_event("batch_completed", {
"status": "success",
"total_time_ms": 2500
})
Common Use Cases
- API Request/Response Tracking
- Track HTTP requests and responses
- Monitor response times
- Track error rates
- Record request parameters
- Batch Processing
- Track batch operations
- Monitor progress
- Record processing times
- Track success/failure rates
- Image/Video Processing
- Track media processing operations
- Monitor resource usage
- Record processing times
- Track quality metrics
- Data Processing Pipelines
- Track data transformation steps
- Monitor processing stages
- Record data volumes
- Track error rates
- Machine Learning Operations
- Track model inference
- Monitor resource usage
- Record processing times
- Track model performance metricstitle: “Manual Tracking” description: “Welcome to the home of your new documentation”
