> ## 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.

# Manual Tracing

> Track external API calls and custom operations with Netra manual tracing. Add detailed observability to any function using SpanWrapper in Python.

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:

1. Import the required classes
2. Create a new span
3. Track your operations
4. Add relevant attributes and events

Here's a basic example:

## Start a New Span

Set your Netra endpoint and API key before you call `Netra.init()`. Without `NETRA_OTLP_ENDPOINT`, the SDK prints spans to the console instead of sending them to Netra, and your dashboard stays empty.

```bash US Region theme={null}
export NETRA_OTLP_ENDPOINT="https://api.getnetra.ai/telemetry"
export NETRA_API_KEY="your-api-key-here"
```

```bash EU Region theme={null}
export NETRA_OTLP_ENDPOINT="https://api.eu.getnetra.ai/telemetry"
export NETRA_API_KEY="your-api-key-here"
```

Set these wherever your app runs, including Docker containers and CI jobs.

```python python theme={null}
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:

```python Python theme={null}
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:

```python python theme={null}
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:

```python python theme={null}
# 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:

```python python theme={null}
# 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:

```python python theme={null}
# 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:

```python theme={null}
[
    {
        "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
    }
]
```

Refer the sample code given to understand how to implement action tracking utility in your application.

```python python theme={null}
# 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:

```python python theme={null}
# 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

```python python theme={null}
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

```python python theme={null}
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

```python python theme={null}
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

1. **API Request/Response Tracking**
   * Track HTTP requests and responses
   * Monitor response times
   * Track error rates
   * Record request parameters
2. **Batch Processing**
   * Track batch operations
   * Monitor progress
   * Record processing times
   * Track success/failure rates
3. **Image/Video Processing**
   * Track media processing operations
   * Monitor resource usage
   * Record processing times
   * Track quality metrics
4. **Data Processing Pipelines**
   * Track data transformation steps
   * Monitor processing stages
   * Record data volumes
   * Track error rates
5. **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"

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.