EvolvisHub Alerting Library

A comprehensive, professional asynchronous multi-channel alerting library for Python applications. Send alerts and notifications through Microsoft Teams, Email, Slack, Discord, SMS, and custom webhooks with advanced features like filtering, rate limiting, and retry mechanisms.

Author: Alban Maxhuni, PhD (a.maxhuni@evolvis.ai) Company: Evolvis AI License: Commercial License

🚀 Features

• 🔄 Fully Asynchronous: Built with async/await for high performance and scalability
• Multi-Channel Support: Teams, Email, Slack, Discord, SMS (Twilio), Custom Webhooks
• Multiple Configurations: Support multiple channels of the same type (e.g., different Teams channels)
• Alert Categories: Software issues, Performance, Security, Business logic, Infrastructure, Data quality
• Advanced Filtering: Route alerts to specific channels based on level, category, or keywords
• Rate Limiting: Prevent spam with configurable rate limits per channel
• Retry Mechanism: Automatic retry with exponential backoff for failed deliveries
• Multiple Config Formats: Support for .ini, .json, and .yaml configuration files
• Environment Variables: Override config with environment variables
• Concurrent Sending: Send alerts to multiple channels simultaneously
• Comprehensive Testing: Full test suite with 95%+ coverage

📦 Installation

pip install evolvishub-alerting

Optional Dependencies

For SMS support (Twilio):

pip install evolvishub-alerting[sms]
# or
pip install twilio

For YAML configuration support:

pip install evolvishub-alerting[yaml]
# or
pip install pyyaml

🔧 Quick Start

1. Create Configuration File

Create an alert_config.ini file:

[teams]
webhook_url = https://outlook.office.com/webhook/YOUR_WEBHOOK_URL
enabled = true

[email]
smtp_server = smtp.gmail.com
smtp_port = 587
username = your-email@gmail.com
password = your-app-password
from_email = alerts@yourcompany.com
to_emails = admin@yourcompany.com,dev@yourcompany.com
enabled = true

[slack]
webhook_url = https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
channel = #alerts
username = AlertBot
enabled = true

2. Send Your First Alert

import asyncio
from alerting import AlertManager, AlertLevel

async def main():
    # Initialize the alert manager
    alert_manager = AlertManager("alert_config.ini")

    # Send a simple alert
    await alert_manager.send_alert(
        message="Application started successfully",
        level=AlertLevel.INFO,
        title="Application Startup"
    )

    # Send an alert with metadata
    await alert_manager.send_alert(
        message="High memory usage detected",
        level=AlertLevel.WARNING,
        title="Performance Alert",
        metadata={
            "memory_usage": "85%",
            "server": "web-01"
        }
    )

# Run the async function
asyncio.run(main())

📋 Alert Types

Software Issues

async def handle_error():
    try:
        # Your code here
        result = risky_operation()
    except Exception as e:
        await alert_manager.send_software_issue(
            error=e,
            context={"user_id": 123, "function": "risky_operation"}
        )

Performance Alerts

async def monitor_performance():
    await alert_manager.send_performance_alert(
        metric="cpu_usage",
        value=92.5,
        threshold=80.0,
        context={"server": "web-01"}
    )

Security Alerts

async def security_monitoring():
    await alert_manager.send_security_alert(
        event="Multiple failed login attempts",
        severity="high",
        context={"ip": "192.168.1.100", "attempts": 5}
    )

Business Alerts

async def business_monitoring():
    await alert_manager.send_business_alert(
        event="Payment processing down",
        impact="critical",
        context={"affected_customers": 150}
    )

🎯 Advanced Features

Multiple Channel Configurations

Configure multiple channels of the same type:

# Primary Teams channel
[teams]
webhook_url = https://outlook.office.com/webhook/primary
enabled = true

# Development Teams channel
[teams_dev]
webhook_url = https://outlook.office.com/webhook/dev
enabled = true

# Critical email alerts
[email_critical]
smtp_server = smtp.gmail.com
username = critical@company.com
to_emails = ceo@company.com,cto@company.com
enabled = true

Alert Filtering and Routing

from alerting.core import AlertFilter

# Create filters for conditional routing
critical_filter = AlertFilter(
    level=AlertLevel.CRITICAL,
    channels=['teams', 'email', 'sms']
)

security_filter = AlertFilter(
    category=AlertCategory.SECURITY,
    channels=['email_critical', 'teams_security']
)

database_filter = AlertFilter(
    keywords=['database', 'db', 'sql'],
    channels=['slack_dba']
)

# Add filters to alert manager
alert_manager.add_filter(critical_filter)
alert_manager.add_filter(security_filter)
alert_manager.add_filter(database_filter)

Targeted Channel Alerts

async def send_targeted_alert():
    # Send to specific channels only
    await alert_manager.send_alert(
        message="Database server is down",
        level=AlertLevel.CRITICAL,
        target_channels=["email", "sms"],
        metadata={"server": "db-primary"}
    )

Concurrent Alert Sending

async def send_multiple_alerts():
    # Send multiple alerts concurrently
    tasks = [
        alert_manager.send_alert("Alert 1", AlertLevel.INFO),
        alert_manager.send_alert("Alert 2", AlertLevel.WARNING),
        alert_manager.send_alert("Alert 3", AlertLevel.ERROR)
    ]

    # Wait for all alerts to complete
    await asyncio.gather(*tasks)

📁 Configuration Formats

INI Format (alert_config.ini)

[teams]
webhook_url = https://outlook.office.com/webhook/test
enabled = true

[email]
smtp_server = smtp.gmail.com
smtp_port = 587
username = alerts@company.com
password = app-password
from_email = alerts@company.com
to_emails = admin@company.com
enabled = true

JSON Format (alert_config.json)

{
  "teams": {
    "webhook_url": "https://outlook.office.com/webhook/test",
    "enabled": "true"
  },
  "email": {
    "smtp_server": "smtp.gmail.com",
    "smtp_port": "587",
    "username": "alerts@company.com",
    "password": "app-password",
    "from_email": "alerts@company.com",
    "to_emails": "admin@company.com",
    "enabled": "true"
  }
}

YAML Format (alert_config.yaml)

teams:
  webhook_url: "https://outlook.office.com/webhook/test"
  enabled: "true"

email:
  smtp_server: "smtp.gmail.com"
  smtp_port: "587"
  username: "alerts@company.com"
  password: "app-password"
  from_email: "alerts@company.com"
  to_emails: "admin@company.com"
  enabled: "true"

Environment Variables

Override any configuration with environment variables:

export ALERT_TEAMS_WEBHOOK_URL="https://outlook.office.com/webhook/env"
export ALERT_EMAIL_PASSWORD="env-password"

🔌 Supported Channels

Microsoft Teams

[teams]
webhook_url = https://outlook.office.com/webhook/YOUR_WEBHOOK
enabled = true

Email (SMTP)

[email]
smtp_server = smtp.gmail.com
smtp_port = 587
username = your-email@gmail.com
password = your-app-password
from_email = alerts@yourcompany.com
to_emails = admin@company.com,dev@company.com
use_tls = true
enabled = true

Slack

[slack]
webhook_url = https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
channel = #alerts
username = AlertBot
enabled = true

Discord

[discord]
webhook_url = https://discord.com/api/webhooks/YOUR_DISCORD_WEBHOOK
username = AlertBot
avatar_url = https://company.com/bot-avatar.png
enabled = true

SMS (Twilio)

[sms]
service = twilio
account_sid = YOUR_TWILIO_ACCOUNT_SID
auth_token = YOUR_TWILIO_AUTH_TOKEN
from_number = +1234567890
to_numbers = +1111111111,+2222222222
enabled = true

Custom Webhook

[webhook]
webhook_url = https://your-api.com/webhooks/alerts
method = POST
headers = {"Authorization": "Bearer TOKEN"}
timeout = 30
enabled = true

🧪 Testing

Run the test suite:

# Install test dependencies
pip install -e .[test]

# Run tests
pytest

# Run tests with coverage
pytest --cov=alerting --cov-report=html

# Run specific test file
pytest tests/test_core.py

📚 Examples

Check the examples/ directory for comprehensive usage examples:

• basic_usage.py - Basic alert sending examples
• advanced_usage.py - Advanced features like filtering and rate limiting
• alert_config.*.example - Example configuration files

🔒 Security Best Practices

1. Use App Passwords: For email, use app-specific passwords instead of your main password
2. Environment Variables: Store sensitive credentials in environment variables
3. Webhook Security: Use HTTPS webhooks and validate webhook signatures when possible
4. Rate Limiting: Configure appropriate rate limits to prevent abuse
5. Access Control: Limit who can modify alert configurations

🚀 Production Deployment

Docker Example

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "your_app.py"]

Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: alert-config
data:
  alert_config.ini: |
    [teams]
    webhook_url = https://outlook.office.com/webhook/prod
    enabled = true

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

� PyPI Statistics

�📄 License

This project is licensed under a Commercial License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the examples and this README
• Issues: Report bugs on GitHub Issues
• Discussions: Ask questions in GitHub Discussions
• Commercial Support: Contact a.maxhuni@evolvis.ai

🗺️ Roadmap

• PagerDuty integration
• Telegram bot support
• Alert templates and formatting
• Metrics and monitoring dashboard
• Alert acknowledgment system
• Integration with popular monitoring tools (Prometheus, Grafana)

👨‍💼 Author & Company

Author: Alban Maxhuni, PhD Email: a.maxhuni@evolvis.ai Company: Evolvis AI

About Evolvis AI: Evolvis AI is a cutting-edge technology company specializing in artificial intelligence solutions and advanced software development. We create innovative tools and libraries that empower developers and organizations to build robust, scalable applications.

Visit us at https://evolvis.ai to learn more about our products and services.

Made with ❤️ by Evolvis AI