> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiler Module

> Standardized profiling for performance monitoring

# Profiler Module

The Profiler module provides standardized profiling for performance monitoring across praisonai and praisonai-agents.

## Features

* Import timing
* Function execution timing
* Flow tracking
* File/module usage tracking
* Memory usage (tracemalloc)
* API call profiling (wall-clock time)
* Streaming profiling (TTFT, total time)
* Statistics (p50, p95, p99)
* cProfile integration
* Flamegraph generation
* Line-level profiling
* JSON/HTML export

## Import

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import Profiler, profile, profile_imports
```

## Quick Examples

### Profile a Function

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import profile

@profile
def my_function():
    # Your code here
    pass
```

### Profile a Block

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import Profiler

with Profiler.block("my_operation"):
    do_something()
```

### Profile API Calls

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import Profiler
import requests

with Profiler.api_call("https://api.example.com") as call:
    response = requests.get("https://api.example.com/data")
```

### Profile Streaming

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import Profiler

with Profiler.streaming("chat") as tracker:
    tracker.first_token()
    for chunk in stream:
        tracker.chunk()
```

### Profile Imports

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import profile_imports

with profile_imports():
    import heavy_module
```

## Profiler Class

### Static Methods

#### `Profiler.block(name)`

Context manager for profiling a code block.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
with Profiler.block("database_query"):
    results = db.query(...)
```

#### `Profiler.api_call(url)`

Context manager for profiling API calls.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
with Profiler.api_call("https://api.openai.com/v1/chat") as call:
    response = openai.chat.completions.create(...)
```

#### `Profiler.streaming(name)`

Context manager for profiling streaming operations.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
with Profiler.streaming("llm_stream") as tracker:
    tracker.first_token()  # Call when first token arrives
    for chunk in stream:
        tracker.chunk()    # Call for each chunk
```

#### `Profiler.report()`

Print a profiling report to console.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Profiler.report()
```

#### `Profiler.get_statistics()`

Get profiling statistics.

**Returns:** `dict` with p50, p95, p99 percentiles

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
stats = Profiler.get_statistics()
print(f"p50: {stats['p50']}ms")
print(f"p95: {stats['p95']}ms")
print(f"p99: {stats['p99']}ms")
```

#### `Profiler.export_json(path)`

Export profiling data to JSON.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Profiler.export_json("profile_data.json")
```

#### `Profiler.export_html(path)`

Export profiling data to HTML report.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Profiler.export_html("profile_report.html")
```

#### `Profiler.reset()`

Reset all profiling data.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Profiler.reset()
```

## Decorators

### `@profile`

Decorator to profile a function.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import profile

@profile
def expensive_operation():
    # This function will be profiled
    pass

@profile
async def async_operation():
    # Async functions are also supported
    pass
```

## Context Managers

### `profile_imports()`

Profile import times for modules.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import profile_imports

with profile_imports():
    import pandas
    import numpy
    import tensorflow

# Check which imports were slow
Profiler.report()
```

## Example: Full Profiling Session

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.profiler import Profiler, profile, profile_imports

# Profile imports
with profile_imports():
    from praisonaiagents import Agent

# Profile function
@profile
def run_agent(prompt):
    agent = Agent(name="Test")
    return agent.start(prompt)

# Profile blocks
with Profiler.block("full_workflow"):
    with Profiler.block("setup"):
        # Setup code
        pass
    
    with Profiler.block("execution"):
        result = run_agent("Hello")
    
    with Profiler.block("cleanup"):
        # Cleanup code
        pass

# Get report
Profiler.report()

# Export data
Profiler.export_json("profile.json")
Profiler.export_html("profile.html")

# Get statistics
stats = Profiler.get_statistics()
print(f"Median execution time: {stats['p50']}ms")
```

## Related

* [CLI Profiling](/docs/cli/profiling) - CLI profiling commands
* [Telemetry Module](/docs/sdk/praisonaiagents/telemetry) - Telemetry and observability