📊 Event Analyzer

A production-style Python system for real-time event stream generation, processing, and burst detection, inspired by modern monitoring and observability platforms.

This project focuses on stream processing, sliding time windows, and stateful alerting, rather than CRUD-style applications.

---

🚀 Features

• Infinite real-time event stream using generators
• Sliding time window processing
• Efficient event storage with deque
• Live counters by event type and source
• Burst detection for critical events
• Edge-triggered alerts to prevent alert spam
• Clean, modular architecture
• Graceful shutdown handling

---

🧠 Core Concepts

• Generators (yield)
• Sliding time windows
• Temporal correctness (event time vs system time)
• Stateful stream processing
• Burst vs sustained event detection
• Memory-efficient data structures
• Separation of concerns

---

🏗️ Project Structure

event-analyzer/
    │
    ├── main.py
    ├── README.md
    ├── requirements.txt
    │
    └── event_analyzer/
        ├── __init__.py
        ├── models.py
        ├── generator.py
        ├── processor.py
        └── detector.py

---

📂 Module Overview

models.py

Defines the Event data model.

Each event contains:

• timestamp
• event_type
• source
• value (optional)
• metadata

---

generator.py

Produces an infinite stream of system events.

• Uses yield for lazy evaluation
• Simulates real-world telemetry
• Configurable emission rate

---

processor.py

Maintains system state using a sliding time window.

• Stores recent events in a deque
• Expires old events automatically
• Tracks:
  • Event counts by type
  • Event counts by source

---

detector.py

Implements burst detection logic.

• Detects sustained spikes
• Prevents repeated alerts
• Designed for extensibility

---

main.py

Application entry point.

• Wires generator, processor, and detector
• Runs the event loop
• Handles graceful shutdown

---

🔁 Data Flow

Event Generator
↓
Event Processor (sliding window)
↓
Counters & State
↓
Burst Detector
↓
Alerts

---

▶️ How to Run

1. Create and activate virtual environment

python3 -m venv venv
source venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

3. Run the system

python3 main.py 

Stop the program with CTRL+C.

📈 Example Output

[HIGH] ERROR_BURST: 7 ERROR events in sliding window

🔮 Future Improvements

• Multi-window analysis (short vs long windows)
• Rate-based anomaly detection
• JSON persistence and replay
• Config-driven thresholds
• Unit and integration tests
• Async / multiprocessing support
• Visualization dashboards

🧑‍💻 Author

Built by Vishal Dsouza as part of a deep Python and systems engineering learning journey.