evolvishub-alertmanager 0.2.0
A flexible alert management system with SQLite backend
License: MIT
Requires Python: >=3.8

# AlertManager

<div align="center">
  <img src="assets/png/eviesales.png" alt="Evolvis Logo" width="200"/>
</div>

A flexible alert management system with SQLite backend that can be used as a library in Python applications.

## About

AlertManager is developed by [Evolvis](https://evolvis.ai), a company specializing in intelligent automation and monitoring solutions. This library provides a robust foundation for managing alerts in any Python application, with a focus on flexibility, performance, and ease of use.

## Author

**Alban Maxhuni, PhD**  
Email: a.maxhuni@evolvis.ai

## Features

- SQLite-based alert storage with connection pooling
- Configurable through YAML files
- Support for different alert types and severities
- Alert acknowledgment and resolution tracking
- Metadata support for additional information
- Automatic cleanup of old alerts
- Configurable logging with enable/disable option
- Advanced statistics and metrics
- Trend analysis and reporting
- Generic BaseManager for extensible data management
- Automatic timestamp handling
- JSON field serialization/deserialization
- Bulk operations support
- Migration support for database schema

## Installation

```bash
pip install alertmanager
```

## Usage

### Basic Usage

```python
from alertmanager import AlertManager

# Initialize with default configuration
alert_manager = AlertManager()

# Create an alert
alert_id = alert_manager.create_alert(
    title="Disk space is running low",
    description="Disk usage is above 85%",
    severity="warning"
)

# Get active alerts
alerts = alert_manager.get_alerts(status="active")

# Acknowledge an alert
alert_manager.acknowledge_alert(alert_id, "admin")

# Resolve an alert
alert_manager.resolve_alert(alert_id, "admin")
```

### Advanced Usage

```python
# Get comprehensive statistics
stats = alert_manager.get_alert_statistics()
print(f"Total alerts by status: {stats['by_status']}")
print(f"Alerts by severity: {stats['by_severity']}")
print(f"Average resolution time: {stats['avg_resolution_days']} days")

# Get alert trends
trends = alert_manager.get_alert_trends(days=30)
print(f"Daily alert counts: {trends['daily']}")
print(f"Resolution time trends: {trends['resolution_time']}")

# Get source statistics
source_stats = alert_manager.get_source_statistics()
print(f"Statistics by source: {source_stats}")

# Get key performance metrics
metrics = alert_manager.get_alert_metrics(time_period='24h')
print(f"Total alerts in last 24h: {metrics['total_alerts']}")
print(f"Resolution rate: {metrics['resolution_rate']}%")
print(f"Critical alerts percentage: {metrics['critical_percentage']}%")

# Bulk operations
alerts = [
    {
        'title': 'Alert 1',
        'description': 'Description 1',
        'severity': 'warning'
    },
    {
        'title': 'Alert 2',
        'description': 'Description 2',
        'severity': 'critical'
    }
]
alert_manager.bulk_insert(alerts)

# Search alerts
search_results = alert_manager.search_records(
    search_term='disk',
    search_columns=['title', 'description']
)
```

### Configuration

AlertManager requires a configuration file to be provided by the application that uses it. The library includes a default configuration template that you can use as a starting point.

#### Configuration File Location

The configuration file should be placed in your application's configuration directory. By default, AlertManager will look for:
- `config.yaml` or `config.yml`

in the current working directory. You can also specify a custom path when initializing AlertManager:

```python
alert_manager = AlertManager(config_path="/path/to/your/config.yaml")
```

#### Configuration Template

Here's an example configuration file (`config.yaml`):

```yaml
database:
  # Path to SQLite database file (use ":memory:" for in-memory database)
  path: alertmanager.sql
  # Directory containing database migrations
  migrations_dir: migrations
  # Connection pool settings
  pool_size: 5
  max_overflow: 10
  # Enable SQL query logging (for debugging)
  echo: false

logging:
  # Enable or disable logging
  enabled: true
  # Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  level: INFO
  # Log message format
  format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
  # Log file path
  file: alertmanager.log

alerts:
  # Number of days to keep alerts before automatic deletion
  retention_days: 30
  # Default severity for new alerts if not specified
  default_severity: info
  # Default source for new alerts if not specified
  default_source: system
  # Maximum number of alerts to return in a single query
  max_alerts_per_page: 100
  # Page size for pagination
  page_size: 20
  # Default type for new alerts if not specified
  default_type: system
```

#### Configuration Options

| Section | Option | Description | Default |
|---------|--------|-------------|---------|
| database | path | Path to SQLite database file | alertmanager.sql |
| database | migrations_dir | Directory containing migrations | migrations |
| database | pool_size | Connection pool size | 5 |
| database | max_overflow | Maximum overflow connections | 10 |
| database | echo | Enable SQL query logging | false |
| logging | enabled | Enable or disable logging | true |
| logging | level | Logging level | INFO |
| logging | format | Log message format | '%(asctime)s - %(name)s - %(levelname)s - %(message)s' |
| logging | file | Log file path | alertmanager.log |
| alerts | retention_days | Days to keep alerts | 30 |
| alerts | default_severity | Default alert severity | info |
| alerts | default_source | Default alert source | system |
| alerts | max_alerts_per_page | Max alerts per query | 100 |
| alerts | page_size | Page size for pagination | 20 |
| alerts | default_type | Default alert type | system |

## API Reference

### AlertManager

#### Core Methods

- `create_alert(title, description, severity=None)`: Create a new alert
- `get_alerts(status=None, limit=None, offset=0)`: Get alerts with optional filtering
- `acknowledge_alert(alert_id, acknowledged_by)`: Acknowledge an alert
- `resolve_alert(alert_id, resolved_by)`: Resolve an alert
- `get_active_alerts_count()`: Get count of active alerts by severity
- `delete_old_alerts(days=None)`: Delete alerts older than specified days
- `query_alerts(columns=None, filters=None, order_by=None, limit=None, offset=None)`: Generic query function
- `bulk_insert(records, auto_timestamps=True)`: Insert multiple alerts
- `search_records(search_term, search_columns)`: Search alerts across multiple columns
- `get_latest_records(limit=10, date_column='created_at_evie')`: Get most recent alerts

#### Statistical Methods

- `get_alert_statistics()`: Get comprehensive statistics about alerts
- `get_alert_trends(days=30)`: Get alert trends over time
- `get_source_statistics()`: Get statistics about alert sources
- `get_alert_metrics(time_period='24h')`: Get key performance metrics for alerts

## Development

### Running Tests

```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/ -v
```

### Building

```bash
# Build the package
python setup.py build

# Build and upload to PyPI
./build_and_upload.sh
```

## License

MIT License