Dravyn Sentinel, end to end

What Dravyn Sentinel is

A small SDK in your app, an ingestion API that stores everything it sends, and a dashboard that turns that stream into request-rate, error-rate, and latency charts — plus automatic flagging of SQL-injection, XSS, and brute-force patterns.

Instead of wiring up separate error tracking, APM, and log search tools, one SDK call captures all three: capture() for arbitrary log events, an auto-instrumented middleware for request timing, and uncaught-exception hooks for errors. Every event lands in the same store and is searchable from the same dashboard.

It's not a wrapper around a third-party SaaS. The ingestion API is a plain FastAPI service backed by your own ClickHouse instance (or SQLite for local dev), with Resend for alert email and an optional Slack webhook — both swappable via environment variables.

Core concepts

Event

The one row shape everything becomes: request, error, security, or log. Always carries a project_id, a type, and a timestamp; other fields depend on the type.

Project

A string ID you choose ("my-app") that every event is scoped to. There's no project-registration step — the first event ingested for a new project_id just starts showing up.

API key

A bearer token in SENTINEL_API_KEYS (comma-separated on the server). Any valid key can read or write any project — there's no per-key project scoping yet.

Security event

A request or log event that the rule engine re-tagged as type: "security" after matching a SQLi/XSS pattern or a brute-force login streak.

Stats window

A one-minute bucket of aggregated request count, error count, and p50/p95/p99 latency — what the dashboard's charts are built from.

Alert cooldown

Once an error-rate alert fires for a project, it won't fire again for that project for 10 minutes, even if the error rate stays high.

Feature matrix

What's actually running today versus what still needs rolling-baseline anomaly detection or WebSocket push to feel complete.

Getting started

Full stack (Docker)

cd "Dravyn Sentinel"
docker compose up --build
# dashboard:  http://localhost:3000
# ingestion:  http://localhost:8000

Starts ClickHouse, the ingestion API, and the dashboard together — reads a .env file next to docker-compose.yml automatically.

Ingestion API only, no Docker

cd ingestion
python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Falls back to a local SQLite file (dev/test only) and loads ingestion/.env automatically via python-dotenv.

Self-serve API keys

No admin required — generate your own scoped key from the dashboard.

The dashboard logs you in via Dravyn Auth on any page you visit (Sentinel is registered as its own Dravyn Auth project, separate from Dravyn Auth's own accounts). Head to /keys once logged in, create a project, and generate a key for it in a few clicks.

1. Open /keys, create an account (first/last name, email + password with a strength meter, OTP-verified) or log in
2. Name a project and pick a platform (Node.js, Python, or Other/REST) — the name is slugified into the project_id your SDK will use, e.g. "My App" → my-app; the platform just decides which quickstart snippet you're shown next, it doesn't restrict what actually calls the ingest API
3. Click Generate key — the raw key is shown once, alongside a ready-to-paste quickstart snippet for the platform you picked

Signup can ask for more than name, email, and password — Dravyn Auth projects (including this one) can define extra registration fields from its portal. If Sentinel's project has any defined, they render automatically on this form via getCustomFields()/register(email, password, profile, customFields), and the values come back on the account like any other profile data.

Node.js SDK — @dravyn/sentinel

import { init } from "@dravyn/sentinel";

init({
  apiKey: process.env.SENTINEL_API_KEY!,
  projectId: "my-app",
  ingestUrl: "https://dravyn-sentinel-ingestion.onrender.com", // or http://localhost:8000
  service: "api",
  captureUncaught: true, // hooks process uncaughtException / unhandledRejection
});

import { sentinelMiddleware, sentinelErrorHandler } from "@dravyn/sentinel/express";

app.use(sentinelMiddleware());     // records one `request` event per response
// ...your routes...
app.use(sentinelErrorHandler());   // captures thrown errors before your handler

import { capture, captureError } from "@dravyn/sentinel";

try {
  await chargeCard(order);
} catch (err) {
  captureError(err, { orderId: order.id });
  throw err;
}

Delivery is best-effort and non-blocking — if the ingestion API is unreachable, flush() swallows the error rather than crashing your app.

Python SDK — dravyn-sentinel

import dravyn_sentinel as sentinel

sentinel.init(
    api_key=os.environ["SENTINEL_API_KEY"],
    project_id="my-app",
    ingest_url="https://dravyn-sentinel-ingestion.onrender.com",
    service="api",
)

from dravyn_sentinel.fastapi import SentinelMiddleware

app.add_middleware(SentinelMiddleware)   # captures requests + unhandled exceptions

from dravyn_sentinel import capture, capture_exception

try:
    process_payout(batch)
except Exception as exc:
    capture_exception(exc, {"batch_id": batch.id})
    raise

The client flushes on a background daemon thread and registers an atexit hook — a final flush runs on normal interpreter shutdown, but not on SIGKILL or a hard crash.

Security event detection

Every ingested request or log event is scanned before storage. A match re-tags the event type: "security" and bumps its level to at least warn.

Find flagged events with GET /v1/logs?project_id=…&level=warn, or filter the dashboard's Logs page by level and look at the Type column.

Alerting

After every ingest call, a background task checks the last 5 minutes of stats for that project. If the error rate crosses SENTINEL_ERROR_RATE_THRESHOLD (default 5%) with at least SENTINEL_ALERT_MIN_SAMPLES requests (default 20), it fires once via Resend email and/or a Slack webhook, then goes quiet for a 10-minute cooldown.

Uptime monitoring

A background loop pings every URL in SENTINEL_UPTIME_TARGETS (comma-separated project_id=url pairs) on an interval and records the result as a log event with service: "uptime-monitor" — no separate status-page UI, it shows up in the same stats/search surface as everything else.

SENTINEL_UPTIME_TARGETS=dravyn-web=https://dravyn.it.com,dravyn-auth=https://auth.dravyn.it.com
SENTINEL_UPTIME_INTERVAL_SECONDS=60

Dashboard

A Next.js app at apps/dashboard, entirely gated behind Dravyn Auth login — every page, not just §06's key management. There's no server-side admin key or hardcoded default project anymore; after logging in you see only your own projects, picked from a switcher in the nav, and every request goes straight from your browser to Dravyn Auth or the ingestion API using your own session.

• Overview (/) — stat tiles, requests-vs-errors chart, latency-percentile chart for the selected project, polling every 5s.
• Logs (/logs) — free-text search, level filter, table with time/level/type/service/message/route/status/duration, polling every 5s. Which project you're looking at is an explicit selector at the top of the page (not just the one in the nav bar) — the heading names it too, so it's never ambiguous which project's logs are on screen.
• Projects & Keys (/keys) — create projects (name + platform), generate/revoke API keys, see a platform-specific quickstart snippet right after generating a key.

Viewing your own stats and logs needs no API key at all — /v1/stats and /v1/logs accept your Dravyn Auth session directly, checked against project ownership. A raw key is only for your own SDK integration code.

Deploying

Lock allow_origins in main.py down to the dashboard's real origin before production — it's wide open by default for local dev. Move the rate limiter and alert cooldown to Redis before running more than one ingestion replica; both hold state in-process today.

What's left

Everything in the feature matrix marked partial or not built, plus:

• A custom domain for the ingestion API — it's live on Render today at dravyn-sentinel-ingestion.onrender.com; sentinel.dravyn.it.com ended up pointed at the dashboard instead, so the API still needs its own hostname (a subdomain like ingest.sentinel.dravyn.it.com CNAME'd at it).
• ClickHouse for real scale — the Postgres event store (SENTINEL_STORE=postgres) is real persistence, but it's a single table with bucketing/percentiles computed in Python, not a columnar store with query-time aggregation. Fine for self-serve/early-stage volume; switch to SENTINEL_STORE=clickhouse once that stops being true.