# Performance Monitoring Plugin

Automatic execution time tracking for inference workflows.

## Overview

**Enabled by Default**: Tracks execution time for all inference workflows with zero configuration. Provides timing information in logs and saves detailed metrics to the result pickle file.

## How It Works

The plugin registers hooks at workflow start and completion:

```python
INFERENCE_START_HOOK   # Records start timestamp
INFERENCE_COMPLETE_HOOK # Calculates and stores execution time
```

**Process:**
1. Records timestamp when inference begins
2. Calculates total execution time at completion  
3. Stores timing data in `DataCollector.batch_metadata['performance']`
4. Logs human-readable timing information

## Usage

### Automatic Logging

Performance metrics are automatically logged for every inference:

```bash
vipr --config config.yaml inference run
```

**Console Output:**
```
[INFO] Inference workflow started at: 2025-11-21 15:30:45.123456
[INFO] Inference execution time: 2.34 seconds
```

### Accessing Timing Data

Performance data is saved to the pickle file in `batch_metadata`:

```python
import pickle

with open('storage/results/<result_id>/result.pkl', 'rb') as f:
    result_data = pickle.load(f)
    
performance = result_data['batch_metadata']['performance']
print(f"Execution time: {performance['execution_time_formatted']}")
print(f"Started: {performance['start_datetime']}")
```

### Available Fields

The `batch_metadata['performance']` dictionary contains:

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `execution_time` | `float` | Total time in seconds | `2.34` |
| `execution_time_formatted` | `str` | Human-readable time | `"2.34 seconds"` |
| `start_time` | `float` | Unix timestamp (start) | `1700581845.123` |
| `end_time` | `float` | Unix timestamp (end) | `1700581847.463` |
| `start_datetime` | `str` | ISO format start | `"2025-11-21T15:30:45.123456"` |
| `end_datetime` | `str` | ISO format end | `"2025-11-21T15:30:47.463456"` |

## Measurement Scope

- Includes all 6 inference steps (Load Data → Load Model → Normalize → Preprocess → Predict → Postprocess)
- Includes hook/filter execution time
- Uses Python's `time.time()` with ~1 microsecond precision

## Configuration

The plugin is enabled by default. To disable it, create a plugin configuration file:

**Default location** (automatically loaded):
```yaml
# vipr-plugins.yaml (in your working directory)
plugin.performance:
  enabled: false
```

**Custom location** (via environment variable):
```bash
export VIPR_PLUGIN_CONFIG=/path/to/my-custom-plugins.yaml
```

This configuration overrides the default settings from `vipr-core/vipr/config/plugins.yaml`.

## See Also

- [Inference Plugin](inference.md) - 6-step inference workflow
- [API Plugin](api/) - REST API integration
- `vipr-core/vipr/plugins/performance/performance.py` - Source code