v0.1.0 · Open source · GPL-3.0

API monitoring
that doesn't
get in your way

Add one call to your FastAPI or Flask app. Get latency percentiles, per-route error rates, status distribution, and weekly AI-generated anomaly reports — self-hosted, no agents, no SaaS bill.

Live Demo View on GitHub

reqly.instrument(app, service_name="checkout-api") — that's it

reqly / checkout-api ● live

Latency

p50

42 ms

p95

187 ms

p99

312 ms

Error rate

0.8%

↓ within baseline

Requests / min

247

p50 · p95 · p99

Latency percentiles per route, per minute

Per-route

Error rates with z-score anomaly baseline

2xx – 5xx

Status distribution per service per hour

Weekly AI

Anomaly reports via Groq (Llama 3.3-70b)

Features

Everything you need. Nothing you don't.

Built specifically for FastAPI and Flask — not a generic agent that ships 50 MB of overhead and a $400/month bill.

Zero-code instrumentation

One instrument() call. No decorators, no manual spans, no config files. Auto-detects FastAPI vs Flask.

import reqly from fastapi import FastAPI app = FastAPI() reqly.instrument( app, service_name="checkout-api", collector_url="http://localhost:8000", api_key="your_key" ) # Every route is now tracked.

Fail-open SDK

SDK errors never reach your app. Instrumentation disables itself on failure. A dead collector adds zero latency — all shipping is on a background thread with strict timeouts.

✓ Background thread shipping

✓ Queue capped at 2 000 events

✓ Route templates, never raw paths

Latency percentiles

p50, p95, p99 per route per minute via TimescaleDB continuous aggregates.

p50

42ms

p95

187ms

p99

312ms

Error rate tracking

Per-route hourly error rates. 5xx responses and unhandled exceptions both captured.

0.8%

error rate · /checkout · last hour

Weekly AI anomaly reports

Z-score anomaly detection first — Groq writes the narrative last. The LLM never sees raw events; only the structured anomaly JSON.

"route": "/auth", "day_of_week": "Monday", "hour_range": "08:00–10:00", "observed_error_rate": 0.18, "baseline_error_rate": 0.02, "z_score": 3.4

"Your /auth endpoint degrades every Monday morning — error rate 18% vs. 2% baseline, p95 at 1850ms vs. 320ms."

No Groq key? Plain-text statistical summary generated instead.

Self-hostable

One docker compose up. TimescaleDB + Collector + Dashboard. Your data, your infra.

Status distribution

2xx / 3xx / 4xx / 5xx breakdown per service, per hour.

Architecture

How data flows

Every component is yours — no phone-home, no shared infrastructure.

data flow

[Your FastAPI / Flask app]
  + Reqly SDK  ──►  POST /v1/ingest  (batched, background thread)
                             │  X-Reqly-Key auth · rate-limited
                     [Collector — FastAPI + asyncpg]
                             │  bulk insert
                     [TimescaleDB]
                      ├── request_events      (hypertable · 14-day retention)
                      └── continuous aggregates (no cron — auto-refresh):
                           ├── route_latency_1min      (p50 / p95 / p99 per minute)
                           ├── route_errors_1hour      (error rate per hour)
                           └── route_status_dist_1hour (status codes per hour)
                             │
             ┌──────────────┴──────────────────────┐
             │                                     │
      [Dashboard]                  [APScheduler / Lambda]
   React 19 reads               Sunday 23:00 UTC:
   GET /v1/metrics/*             1. Pull 8w route_errors_1hour
                                2. Build dow × hour baseline
                                3. Z-score flag top anomalies
                                4. POST anomaly JSON → Groq
                                5. Store report → dashboard

Stack

Deliberate technology choices

Every layer has a reason. No bloat, no magic.

Layer	Technology & reason
SDK	Python — threading, httpx, pure ASGI middleware (no Starlette BaseHTTPMiddleware overhead)
Collector	FastAPI + asyncpg + APScheduler + slowapi — async throughout, no ORM overhead
Database	TimescaleDB — hypertables + continuous aggregates auto-refresh; sub-ms dashboard queries
Dashboard	React 19, Vite 8, Tailwind CSS 4, recharts 3, TanStack Query 5
AI	Groq API · Llama 3.3-70b-versatile — statistics first, LLM writes narrative only
AWS (optional)	Lambda + EventBridge + S3, deployed via SAM — same job as APScheduler, cloud-native cron

Live Demo

See Reqly in the wild

EventFlow — a real Flask event management app — is instrumented with Reqly. Browse the live metrics or explore the source.

Try EventFlow Live Metrics Dashboard EventFlow Source

To view metrics: login as Administrator on EventFlow (admin@eventhub.com / Admin@123) → click Metrics in the nav.

Developer docs

Get Reqly running locally

Clone to dashboard in under 5 minutes. Includes SDK usage, config reference, and architecture notes.

Contents

1. Prerequisites 2. Clone & configure 3. Start the stack 4. Instrument your app 5. SDK configuration 6. How the pipeline works 7. Project structure 8. Running tests

1 Prerequisites

Docker Desktop

Docker + Compose — required for all services

Git

To clone the repo

Python 3.9+

Only for local SDK dev or running tests

Optional: a free Groq API key — needed for AI insights. Without it, a plain statistical summary is shown instead.

2 Clone & configure

terminal
git clone https://github.com/tanisheesh/reqly
cd reqly
cp .env.example .env

Open .env and fill in:

.env
# Database
POSTGRES_PASSWORD=your_secure_password

# API keys (any string — auth for SDK → collector, dashboard → collector)
REQLY_INGEST_KEY=your_ingest_key
REQLY_READ_KEY=your_read_key

# Optional — AI insights (free key at console.groq.com/keys)
GROQ_API_KEY=gsk_your_key_here

3 Start the stack

terminal
docker compose up -d

Starts 3 containers. First build takes ~2 minutes; subsequent starts are fast.

Container	URL	Role
timescaledb	:5432	Time-series database
collector	:8000 · /docs	FastAPI ingest + query + AI insights
dashboard	http://localhost:5173	React dashboard — open this

Tip: Point your app at http://localhost:8000, then open the dashboard. The AI Insights panel appears at the bottom — click "Regenerate now" to trigger on-demand.

stop
# stop, keep data
docker compose down

# stop + wipe database
docker compose down -v

4 Instrument your app

install
pip install reqly

FastAPI
import reqly
from fastapi import FastAPI

app = FastAPI()
reqly.instrument(
    app,
    service_name="my-api",
    collector_url="http://localhost:8000",
    api_key="your_ingest_key"
)

Flask
import reqly
from flask import Flask

app = Flask(__name__)
reqly.instrument(
    app,
    service_name="my-api",
    collector_url="http://localhost:8000",
    api_key="your_ingest_key"
)

Same call for both — instrument() auto-detects FastAPI vs Flask.

trigger AI insights on-demand
curl -X POST "http://localhost:8000/v1/insights/generate?service_name=my-api" \
  -H "X-Reqly-Key: your_ingest_key"

5 SDK configuration reference

Every option can be passed as a kwarg or set via env var. Resolution order: kwarg → env var → default.

kwarg	env var	default
service_name	REQLY_SERVICE_NAME	argv[0] basename
collector_url	REQLY_COLLECTOR_URL	http://localhost:8000
api_key	REQLY_API_KEY	None
sample_rate	REQLY_SAMPLE_RATE	1.0
flush_interval_seconds	REQLY_FLUSH_INTERVAL_SECONDS	5.0
max_batch_size	REQLY_MAX_BATCH_SIZE	200
max_queue_size	REQLY_MAX_QUEUE_SIZE	2000
ignore_routes	REQLY_IGNORE_ROUTES	/health,/metrics
capture_request_body	REQLY_CAPTURE_REQUEST_BODY	False

6 How the pipeline works

full data flow

[Your app + Reqly SDK]
  ──► POST /v1/ingest  (batched, background thread, X-Reqly-Key auth)
                       [Collector] writes raw events
                       [TimescaleDB]
                        ├── request_events      (14-day retention)
                        ├── route_latency_1min  (p50/p95/p99)
                        ├── route_errors_1hour  (error rate)
                        └── route_status_dist   (status codes)
                               │
               ┌──────────────┴──────────────────────┐
        [Dashboard]                   [Weekly job]
     GET /v1/metrics/*             z-score → Groq → report

Why pure ASGI middleware?

Avoids Starlette's BaseHTTPMiddleware stream-buffering issues. Direct ASGI callables are both simpler and faster.

Why a background thread, not asyncio?

Flask is not async. A thread makes the same SDK work in both FastAPI and Flask with zero framework-specific shipping logic.

Why continuous aggregates?

TimescaleDB refreshes them automatically. Dashboard queries hit pre-rolled materializations — sub-millisecond, no manual cron jobs.

Why z-score before LLM?

Statistics are deterministic and cheap. The LLM only writes narrative — it never hallucinates numbers because it never sees raw data.

7 Project structure

repo layout
sdk/                    # pip install reqly
  reqly/
    __init__.py         # reqly.instrument() — public API
    core/               # client, config, buffer, shipper, sampling
    integrations/       # fastapi.py, flask.py

collector/              # FastAPI backend
  app/
    routers/            # ingest, metrics, insights
    insights/           # anomaly_detection, groq_client, scheduler
    db/                 # asyncpg pool + queries
  migrations/
    001_init.sql        # hypertable + aggregates + retention

dashboard/              # React 19 + Vite 8 SPA

infra/
  ec2-userdata.sh       # Amazon Linux 2023 bootstrap
  DEPLOY.md             # AWS production guide
  sam/                  # Lambda + EventBridge + S3

docker-compose.yml
.env.example

8 Running tests

SDK — 13 tests
cd sdk
pip install -e ".[dev]"
pytest tests -v

Collector (needs TimescaleDB running)
docker compose up timescaledb -d
cd collector
pip install -e ".[dev]"
pytest tests -v

Dashboard type-check
cd dashboard
npm install
npx tsc --noEmit

CI runs all three on every push — .github/workflows/ci.yml

View on GitHub Full CONTRIBUTING.md AWS Deploy guide

API monitoringthat doesn'tget in your way

Everything you need. Nothing you don't.

How data flows

Deliberate technology choices

See Reqly in the wild

Get Reqly running locally

1 Prerequisites

2 Clone & configure

3 Start the stack

4 Instrument your app

5 SDK configuration reference

6 How the pipeline works

7 Project structure

8 Running tests

API monitoring
that doesn't
get in your way