Getting started

Know when your business silently breaks

Standard monitoring tells you when your server crashes. Heron tells you when your business flow quietly fails — when payment webhooks stop firing, email jobs silently stall, or background workers die without throwing an error.

Your system looks healthy. But revenue is stopped. Heron catches that.

Common events people monitor with Heron:

• →payment.completed — detect payment pipeline failures
• →user.signup — detect broken signup webhooks
• →email.sent — detect stalled email queues
• →job.processed — detect silent worker failures

How it works

Heron works in three phases: ingest, learn, and detect.

When you call heron.track("payment.completed"), Heron records that event with a timestamp. Over time, it computes the average interval between occurrences — for example, payment.completed fires every ~3 minutes.

The background monitor checks each event's last-seen timestamp against its learned interval. If the silence exceeds the expected interval by a meaningful margin, Heron opens an incident and fires a Slack alert. When the event resumes, it automatically closes the incident and reports the total downtime.

Quick start

Get Heron running locally in about 10 minutes.

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

pip install -r requirements.txt

python run.py

curl -X POST "https://heron-production.up.railway.app/v1/projects?name=MyApp"

# Response
{
  "project_id": 1,
  "api_key": "heron_xxxxx"
}

# In your application code
import sys
sys.path.append("/path/to/heron-sdk")

import heron

heron.init(api_key="heron_xxxxx")
heron.track("payment.completed")

Database setup

Heron requires a PostgreSQL database with four tables. Run the following SQL after creating your database:

-- Stores your projects and their Slack webhook URLs
CREATE TABLE projects (
    id              SERIAL PRIMARY KEY,
    name            TEXT NOT NULL,
    api_key         TEXT UNIQUE NOT NULL,
    slack_webhook_url TEXT,
    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Raw event log — every heron.track() call lands here
CREATE TABLE events (
    id          SERIAL PRIMARY KEY,
    api_key     TEXT,
    event_name  TEXT,
    service     TEXT,
    environment TEXT,
    metadata    JSONB,
    timestamp   BIGINT
);

-- Per-event statistics updated on each track() call
CREATE TABLE event_stats (
    api_key         TEXT,
    event_name      TEXT,
    service         TEXT,
    environment     TEXT,
    last_seen       BIGINT,
    avg_interval    FLOAT,
    event_count     INTEGER,
    incident_active BOOLEAN DEFAULT FALSE
);

-- One row per incident, open or resolved
CREATE TABLE incidents (
    id          SERIAL PRIMARY KEY,
    api_key     TEXT,
    event_name  TEXT,
    service     TEXT,
    environment TEXT,
    started_at  TIMESTAMP,
    resolved_at TIMESTAMP,
    duration    INTEGER
);

Running the server

Start the Heron server from the heron-server directory:

python run.py

The server starts at https://heron-production.up.railway.app. It runs a background monitor that periodically checks for silent events and opens or resolves incidents.

Creating a project

Each project gets its own API key. Use separate projects to isolate different apps or environments.

curl -X POST "https://heron-production.up.railway.app/v1/projects?name=MyApp"

{
  "project_id": 1,
  "api_key": "heron_xxxxx"
}

Store the api_key securely — it authenticates all SDK calls and API requests for this project.

Slack alerts

Heron sends incident alerts and recovery notifications to a Slack channel via an incoming webhook.

curl -X PATCH "https://heron-production.up.railway.app/v1/projects/1/slack" \
  -H "Content-Type: application/json" \
  -d '{"slack_webhook_url": "https://hooks.slack.com/..."}'

SDK installation

The Heron SDK is not yet published on PyPI. Install it by pointing Python to the local SDK directory:

import sys
sys.path.append("/path/to/heron-sdk")  # absolute path to the cloned repo's SDK folder

import heron

SDK reference

heron.init()

Call once at application startup to configure the SDK.

heron.init(
    api_key="heron_xxxxx",      # required
    service="payments-service",  # optional — tag events by service
    environment="production"     # optional — "production", "staging", etc.
)

heron.track()

Call this wherever a business event occurs. Each call records an event occurrence and updates the pattern data.

heron.track(
    event_name="payment.completed",  # required
    metadata={                          # optional
        "amount": 49.99,
        "currency": "USD",
        "user_id": "usr_123"
    }
)

API reference

All endpoints require your project's api_key as a query parameter.

curl "https://heron-production.up.railway.app/v1/incidents?api_key=heron_xxxxx"

[
  {
    "id": 1,
    "event_name": "payment.completed",
    "service": "payments-service",
    "environment": "production",
    "started_at": "2024-11-01T14:22:00Z",
    "resolved_at": "2024-11-01T14:40:00Z",
    "duration": 1080
  }
]

curl "https://heron-production.up.railway.app/v1/incidents/active?api_key=heron_xxxxx"

[
  {
    "id": 3,
    "event_name": "email.sent",
    "service": "notifications",
    "started_at": "2024-11-01T15:10:00Z",
    "resolved_at": null,
    "duration": null
  }
]

Alert format

Heron sends two types of Slack messages: incident alerts when an event stops, and recovery alerts when it resumes.

Incident alert

Recovery alert

Pattern learning

Heron does not require you to manually configure thresholds. Instead, it learns the natural cadence of each event from observed data.

On every heron.track() call, Heron computes a rolling average of the interval between consecutive events. This becomes the expected interval for that event. The silence detector runs periodically and compares the current gap (time since last_seen) against the expected interval.

Troubleshooting