nahiarhdlog

Embedded observability for FastAPI — searchable logs, error tracking, alerts, metrics, tracing, and a token-locked dashboard. Zero infrastructure: everything lives in one SQLite file.

Why nahiarhdlog?

• No infrastructure. No ELK, no agents, no SaaS — pip install and you have history, search, and a UI.
• Embedded dashboard. Your logs live at /admin/logs inside your own app, behind your own token.
• Negligible overhead. Requests enqueue a small dict (p95 ~0.04 ms); SQLite writes happen in batches on a background thread. The queue is bounded — when full, events drop with a visible counter instead of ever blocking a request.
• Framework-agnostic core. FastAPI first; the core imports no web framework, so Flask/Django adapters can follow without changing it.

Install

pip install nahiarhdlog
# or: uv add nahiarhdlog

Requires Python ≥ 3.10. Events are stored in .nahiarhdlog/nahiarhdlog.db (SQLite, WAL mode, FTS5 search).

Quickstart

from fastapi import FastAPI
from nahiarhdLOG import observe

app = FastAPI()
observe(app, dashboard_token="secret")  # logs + errors + metrics + dashboard

That's it. Every request, every stdlib log record, and every uncaught exception is now captured. Open /admin/logs and enter the token on the lock screen.

Features

# .env (never commit this file)
NAHILOG_DB=/var/lib/myapp/nahiarhdlog.db
NAHILOG_TOKEN=long-random-secret

import os
from fastapi import FastAPI
from nahiarhdLOG import observe

app = FastAPI()
observe(
    app,
    db_path=os.environ.get("NAHILOG_DB", ".nahiarhdlog/nahiarhdlog.db"),
    dashboard_token=os.environ.get("NAHILOG_TOKEN"),  # None = dashboard disabled
)

from nahiarhdLOG.alerter import Rule, SmtpSink, TelegramSink, WebhookSink

observe(
    app,
    rules=[Rule("api-errors", count=10, window_seconds=600, cooldown_seconds=1800)],
    sinks=[
        WebhookSink("https://hooks.example/deploy"),          # POSTs {"subject","body"} as JSON
        TelegramSink(bot_token="123:ABC", chat_id="-100..."),  # Bot API sendMessage
        SmtpSink("smtp.example.com", ["ops@example.com"], username="bot", password="..."),
    ],
    dashboard_token="secret",
)

pip install "nahiarhdlog[otel]"

from nahiarhdLOG.otel import export_trace
from nahiarhdLOG.query import get_trace

export_trace(get_trace(collector.storage, trace_id))  # keeps the original trace id

Example app

# terminal 1: run the demo
uv run python examples/basic_app.py serve

# terminal 2: generate traffic
uv run python examples/basic_app.py traffic --n 300

Open http://127.0.0.1:8000/admin/logs with token demo-token.

FAQ

Which Python versions? 3.10+ (3.10, 3.11, 3.12 tested in CI).

Where is data stored? One SQLite file (.nahiarhdlog/nahiarhdlog.db by default), WAL mode, FTS5 index for search. Delete the directory to wipe everything. Set retention_days for automatic purging.

Is the dashboard secure? It is mounted only when dashboard_token is set, and every page + API call requires the token (cookie set at login; old ?token= links migrate). Without it you get a lock screen (401). Use a long random token and HTTPS in production.

Why don't I see the dashboard's own requests in the logs? By design: the dashboard prefix is auto-excluded so its polling doesn't drown your signal. Add more with skip_paths.

What's the overhead? Requests only enqueue a small dict; SQLite writes happen in batches on a background thread. Run python scripts/probe_perf.py to measure on your machine.

Flask / Django / plain scripts? On the roadmap. The core (collector, storage, query, alerter, metrics) imports no web framework — only the thin adapters/ layer does, enforced by an automated boundary test.

How do I disable the dashboard? Omit dashboard_token (default): nothing is mounted.

Roadmap

• Core logging, SQLite+FTS5 storage, search API
• Error tracker + webhook alerts
• Metrics + tracing (+ optional OpenTelemetry export)
• Embedded dashboard UI
• Flask/Django adapters
• Postgres storage backend

Development

uv pip install -e ".[dev,otel]"
uv run --no-sync python -m pytest
uv run --no-sync python scripts/probe_perf.py --n 10000

Changelog

• 0.2.0 — Default database moved to .nahiarhdlog/nahiarhdlog.db (a dot-directory keeps project roots clean; missing parent dirs are auto-created). Note: apps on the old default start a fresh database here — the old nahiarhdlog.db is left untouched.
• 0.1.3 — Dashboard login persists via cookie: refresh and new tabs stay signed in; lock screen signs in without putting the token in the URL; old ?token= bookmarks keep working and migrate to a cookie. Added Lock button. Shutdown hook moved to lifespan composition (works alongside user-defined lifespans, Starlette 0.52–1.x).
• 0.1.2 — Requests capture client IP + user agent; detail dialog rebuilt (no empty rows, status chips, "view full trace" jump); log rows keyboard-accessible (Tab + Enter).
• 0.1.1 — NahiarhdHandler no longer appends a second traceback when the message already contains one (loguru-style pre-formatted records, manually formatted tracebacks).
• 0.1.0 — Initial release: searchable logs, error tracker + alerts, metrics, tracing, embedded dashboard.

License

MIT — see LICENSE.

By Raihan Hidayatullah Djunaedi · nahiarhd.com · PyPI @nahiarhd