Metric monitoring with automatic anomaly detection.
detectkit is a Python library for data analysts and engineers to monitor time-series metrics with automatic anomaly detection and alerting. dbt-like project structure and CLI.
Website, docs & live playground → dtk.pipelab.dev
Features
- Pure numpy arrays — no pandas dependency in core logic
- Statistical detectors — Z-Score, MAD, IQR, Manual Bounds, and a prediction-based Autoreg (AR) detector for fast-moving, non-seasonal metrics
- Trend & seasonality handling — seasonality grouping, recency weighting (
half_life), robust linear detrending for slowly drifting metrics - Multi-channel alerting — Mattermost, Slack, Telegram, Email, Discord, Microsoft Teams, Google Chat, ntfy, Webhook (incl. a Rocket.Chat recipe)
- @mentions — tag users/groups in alerts, each channel formats natively
- Alert lifecycle — consecutive anomalies, fraction-of-window rule (
anomaly_window+min_anomaly_share), cooldown, recovery notifications, no-data alerts - Project-level error alerts — catch DB outages and pipeline crashes once per run
- Database agnostic — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed, incl. MotherDuck cloud paths); Snowflake and BigQuery as hybrid-mode sources
- Hybrid mode — read metric SQL from a billed-per-query warehouse while all pipeline state lives in a cheap local database
- Idempotent — resume from interruptions, no duplicate processing
- CLI —
dtk init,dtk run --select,dtk unlock,dtk clean, tag-based selectors - AI-native onboarding —
dtk init-claudesets up Claude Code context (CLAUDE.md + rules + five skills) so an assistant can scaffold metrics, configure databases, and file feedback upstream
Installation
pip install detectkit
With database drivers:
pip install detectkit[clickhouse] # ClickHouse
pip install detectkit[duckdb] # DuckDB - single file, no server (also MotherDuck md: paths)
pip install detectkit[snowflake] # Snowflake - source-only (hybrid mode)
pip install detectkit[bigquery] # BigQuery - source-only (hybrid mode)
pip install detectkit[all-db] # All databases
Quick Start
CLI (Recommended)
# Create project
dtk init my_monitoring
cd my_monitoring
# Optional: set up Claude Code context so an AI assistant can help you
# write metrics, tune detectors and configure alerts (re-run after upgrades)
dtk init-claude
# Configure database in profiles.yml, then:
dtk run --select cpu_usage
dtk run --select tag:critical
dtk run --select cpu_usage --steps load,detect
dtk run --select cpu_usage --from 2024-01-01
# Clear a stuck lock left by a crashed run (e.g. DB restarted mid-run)
dtk unlock --select cpu_usage
# Prune data orphaned by config edits (dry-run; add --execute to apply)
dtk clean --select cpu_usage
Metric Configuration
# metrics/api_errors.yml
name: api_error_rate
interval: "5min"
query: |
SELECT
toStartOfInterval(timestamp, INTERVAL 5 MINUTE) AS timestamp,
countIf(status_code >= 500) / count() * 100 AS value
FROM http_requests
WHERE timestamp >= '{{ dtk_start_time }}' AND timestamp < '{{ dtk_end_time }}'
GROUP BY timestamp ORDER BY timestamp
detectors:
- type: mad
params:
threshold: 3.0 # in sigma-equivalents
window_size: 2016 # 7 days of 5-min points
window_weights: exponential # optional: favor recent data
half_life: "1d" # weight halves every day of age
alerting:
enabled: true
channels: [mattermost_ops]
consecutive_anomalies: 3
direction: "up"
mentions: [oncall_engineer, here]
alert_cooldown: "30min"
notify_on_recovery: true
suppress_until: "2026-04-11 18:00:00" # Suppress alerts until this UTC time
Python API
import numpy as np
from detectkit.detectors.statistical import ZScoreDetector
detector = ZScoreDetector(threshold=3.0, window_size=100)
results = detector.detect({
'timestamp': np.array([...], dtype='datetime64[ms]'),
'value': np.array([1.0, 2.0, 1.5, 10.0, 1.8]),
})
for r in results:
if r.is_anomaly:
print(f"Anomaly at {r.timestamp}: {r.value}")
AI & automation
- MCP server (
dtk mcp) — a read-only Model Context Protocol server so an AI assistant (Claude Code, Claude Desktop, any MCP client) can query a project's metric configs, loaded data, detector results, replayed alert history and autotune runs directly — no write access to the pipeline. - GitHub Action — a composite action that
runs
dtk run/autotune/cleanas a CI check or scheduled job and gates on detectkit's own exit-code contract, with the--jsonrun summary wired to step outputs.
Documentation
- dtk.pipelab.dev — full docs site, guides, reference, and a live in-browser playground
- Getting Started — 5-minute quickstart
- Configuration Guide — all config options
- Detectors Guide — choosing the right detector
- Alerting Guide — channels, mentions, cooldown, recovery
- Reading Alerts — what a received alert means (for stakeholders)
- MCP Guide — read-only AI-assistant access with
dtk mcp - GitHub Action Guide — run the pipeline in CI
- CLI Reference — command-line documentation
- Examples — real-world monitoring scenarios
- Changelog — version history
Requirements
- Python 3.10+
- numpy >= 1.24.0
- pydantic >= 2.0.0
- click >= 8.0
- PyYAML >= 6.0
- Jinja2 >= 3.0
License
MIT License — see LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for detectkit 0.67.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| detectkit-0.67.2.tar.gz | 500.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| detectkit-0.67.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.1 MB
Release files / detectkit-0.67.2.tar.gz
| Download URL | detectkit-0.67.2.tar.gz |
|---|---|
| Size | 500.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ed0dd42f7c81fe787eda535bf53d0e7f9e901133d4617c6832de21ec416d6e01
|
|
BLAKE2b-256 checksum How to use checksums |
92bc67d2b10cc455f0bdbcf76da6470bef13362bfb6c46053685011aab69aaf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logRelease files / detectkit-0.67.2-py3-none-any.whl
| Download URL | detectkit-0.67.2-py3-none-any.whl |
|---|---|
| Size | 586.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82609946c2c6875639d7d65406ef48c182f54b376b6ab6a871af4e6f15036757
|
|
BLAKE2b-256 checksum How to use checksums |
30eca982418bb5f4acd5fb5dd93bb0b92f5bf97fb48bb59a8431243a03aa810a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency log
