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

# Profiling

> Configure PyInstrument profiling for detailed performance analysis of FastAPI requests

# Profiling

GAIA includes optional PyInstrument middleware for detailed call stack profiling of FastAPI requests. This provides deep insights into performance bottlenecks and function execution times.

## Overview

The profiling system uses [PyInstrument](https://pyinstrument.readthedocs.io/) to provide statistical profiling with:

* **Call stack visualization**: See exactly which functions consume the most time
* **Interactive HTML reports**: Drill down into performance bottlenecks
* **Minimal overhead**: Statistical sampling keeps performance impact low
* **Production ready**: Safe defaults and error resilience

## Configuration

Profiling is **completely optional** and **disabled by default**. All configuration is done via environment variables.

### Environment Variables

Add these to your `.env` file:

```bash theme={null}
# Required: Enable profiling (disabled by default)
ENABLE_PROFILING=true

# Optional: Configure profiling behavior
PROFILING_SAMPLE_RATE=0.1          # Profile 10% of requests automatically
```

### Configuration Options

#### `ENABLE_PROFILING`

* **Type**: `boolean`
* **Default**: `false`
* **Description**: Master switch for profiling functionality. Must be explicitly enabled.
* **Security**: Disabled by default for safety in all environments.

#### `PROFILING_SAMPLE_RATE`

* **Type**: `float` (0.0 to 1.0)
* **Default**: `0.1` (10%)
* **Description**: Fraction of requests to automatically profile in the background.
* **Examples**:
  * `0.0` = No automatic profiling (manual only)
  * `0.01` = Profile 1% of requests (recommended for high-traffic production)
  * `0.1` = Profile 10% of requests (good for development/staging)
  * `1.0` = Profile all requests (only for debugging, high overhead)

## Usage

### Manual Profiling

Add the `profile` query parameter to any request to get a detailed profiling report:

```bash theme={null}
# Profile specific requests
curl "http://localhost:8000/api/v1/users?profile=1"
curl "http://localhost:8000/api/v1/chat-stream?profile=true"
```

**Accepted values**: `1`, `true`, `yes` (case-insensitive)

When manual profiling is requested:

* You receive an **HTML profiling report** instead of the normal JSON response
* The report shows detailed call stacks, execution times, and bottlenecks
* Save the HTML and open in a browser for interactive analysis

### Automatic Sampling

When `PROFILING_SAMPLE_RATE > 0`, requests are automatically profiled in the background:

* Sampled requests are profiled transparently
* Normal JSON responses are returned to clients
* Profiling results are logged to the application logs
* No impact on client experience or API contracts

## Examples

### Development Setup

```bash theme={null}
# .env file for development
ENABLE_PROFILING=true
PROFILING_SAMPLE_RATE=0.2          # Profile 20% of requests
```

### Production Setup

```bash theme={null}
# .env file for production
ENABLE_PROFILING=true
PROFILING_SAMPLE_RATE=0.01         # Profile only 1% of requests
```

### Profiling API Requests

```bash theme={null}
# Profile a chat completion request
curl "http://localhost:8000/api/v1/chat-stream?profile=1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{"message": "Explain quantum computing", "history": []}'

# Profile user authentication
curl "http://localhost:8000/api/v1/users/me?profile=1" \
  -H "Authorization: Bearer your-token"

# Profile any endpoint
curl "http://localhost:8000/api/v1/conversations?profile=true" \
  -H "Authorization: Bearer your-token"
```

## Troubleshooting

### Profiling Not Working

1. Check that `ENABLE_PROFILING=true` in your `.env` file
2. Verify PyInstrument is installed: `pip install pyinstrument`
3. Look for profiling logs at application startup
4. Try manual profiling first: `?profile=1`

### High Performance Impact

1. Reduce `PROFILING_SAMPLE_RATE` (e.g., from `0.1` to `0.01`)

***

<Info>
  **Note**: Profiling adds computational overhead. Use judiciously in production
  environments and monitor the performance impact of your chosen sample rate.
</Info>