Quickstart - PyMAAP

Skip to content

# Quickstart

## 🚀 Getting Started with PyMAAP

PyMAAP helps you monitor, log, and analyze the performance and behavior of your Python functions. It includes two main tools:

- `monitoring.py`: Decorators and tools to track performance, log errors, and save metrics.
- `analysis.py`: CLI script to analyze log files and generate insightful plots.

## 📦 Installation

    uv pip install pymaap

## 🔍 1. Monitoring Functions

Import the decorators and wrap your functions:

    from pymaap.monitoring import Timer, ErrorCatcher, sanitizer

    timer = Timer(results_format="csv", max_arg_length=200, sanitize_func=sanitizer)
    error_handler = ErrorCatcher(results_format="csv", sanitize_func=sanitizer)

    @error_handler
    @timer
    def my_function(x, y):
        return x + y

### ✅ Options

- `results_format`: `"csv"` or `"parquet"`
- `sanitize_func`: Custom sanitizer for sensitive args/logs
- `log_to_console`: Print logs to console (default `True`)
- `use_multiprocessing`: Use locks/log queues in multi-process apps

This creates: - `logs/timing_results.csv` or `.parquet` - `logs/error_results.csv` or `.parquet` - `logs/timing.log` - `logs/error.log`

### 📏 Manual Metrics

You can also log timing manually using:

    from pymaap.monitoring import get_metrics_start, get_metrics_end

    start_metrics = get_metrics_start("my_custom_block")
    # ... your code ...
    end_metrics = get_metrics_end(start_metrics)

## 📊 2. Analyzing Logs

Once you’ve collected logs, analyze them via CLI:

    python -m pymaap.analysis \
      --logdir logs \
      --subtitle "Post-deployment test" \
      --tag run1

### CLI Options

- `--logdir`: Folder with `timing.log` files
- `--subtitle`: Subtitle for all plots (or `"none"` to disable)
- `--tag`: Folder name suffix for outputs (default: `"run"`)
- `--start-time` / `--end-time`: Optional override of time window

Outputs go to `figs/YYYY-MM-DD_HH-MM-SS_run1/`: - Execution plots - Histograms - Aggregate CSVs - Metadata

## 📁 Example Output Structure

    figs/
    └── 2025-04-01_14-00-01_run1/
        ├── execution_time_per_function.png
        ├── function_calls_over_time.png
        ├── memory_change_per_function_call.png
        ├── top10_functions_by_total_time.png
        ├── hist_*.png
        ├── results.csv
        ├── results_aggregate.csv
        └── README.txt