getheron 0.1.0

Heron Python SDK for Business Event Monitoring

Heron — Business Event Monitoring for SaaS

Detect when your business workflows silently break.

---

What is Heron

Heron makes sure your critical business events are actually happening. Unlike traditional monitoring that tells you when your servers crash, Heron learns the usual frequency of your events and immediately alerts you when they stop unexpectedly.

---

The Problem

Most monitoring tools tell you about infrastructure failures. They do NOT tell you when your business stops working.

Examples of silent failures:

• Signup webhooks stop firing
• Payment events stop being produced
• Email jobs stop running
• Background workers silently fail

Your app looks perfectly healthy, but your business flow is broken. You usually only find out when a user complains. Heron fixes this gap.

---

How It Works

Your App → Heron SDK → Heron Server → Pattern Learning → Silence Detection → Slack Alerts

---

Quick Start

Getting started with Heron is designed to be completely frictionless.

1. Clone the repository:

   git clone https://github.com/pranavkp71/Heron.git
   cd Heron/heron-server
   

2. Install dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

3. Start the backend: Once your PostgreSQL database logic is connected via .env, simply boot the server:

   python run.py
   

   The backend will be live at http://localhost:8000.

---

Example

Instrumenting a business event only takes a single line of code!

import heron

# Initialize the SDK with your project key
heron.init(api_key="YOUR_API_KEY")

# Track an event
heron.track("payment.completed")

Heron learns that payment.completed happens every ~3 minutes.

If the event silently stops:

🚨 Heron Alert

Event: payment.completed
Last seen: 18 minutes ago
Expected interval: ~3 minutes

When the event resumes:

✅ Heron Recovery

Event: payment.completed
Downtime: 18 minutes

---

API

Heron provides simple REST endpoints to query and consume your own incident data.

Get all incidents:

GET /v1/incidents?api_key=YOUR_KEY

Get active incidents only:

GET /v1/incidents/active?api_key=YOUR_KEY

---

Contributing

We welcome contributions from everyone! Whether it's fixing bugs, improving docs, or adding new features, we'd love your help.

Please read our Contributing Guide for full instructions on how to get started, branch expectations, and how to run our backend test suite.