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); 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
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
detectkit-0.65.0.tar.gz
(492.1 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
detectkit-0.65.0-py3-none-any.whl
(578.5 kB
view details)
File details
Details for the file detectkit-0.65.0.tar.gz.
File metadata
- Download URL: detectkit-0.65.0.tar.gz
- Upload date:
- Size: 492.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6903ed51530d4c37299be3335400820e53e6a051acacc1241f9c25db571d5932
|
|
| MD5 |
ebc721228a0556fe315f1fb5f5c6bafe
|
|
| BLAKE2b-256 |
da9d752724180cf279661fd1f6987f04e0b3a9d74546b4bfe4c5f3cad84fd18b
|
Provenance
The following attestation bundles were made for detectkit-0.65.0.tar.gz:
Publisher:
publish.yml on alexeiveselov92/detectkit
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
detectkit-0.65.0.tar.gz -
Subject digest:
6903ed51530d4c37299be3335400820e53e6a051acacc1241f9c25db571d5932 - Sigstore transparency entry: 2153906230
- Sigstore integration time:
-
Permalink:
alexeiveselov92/detectkit@38c6e5c347228f490aa4d335b97731d009a73991 -
Branch / Tag:
refs/tags/v0.65.0 - Owner: https://github.com/alexeiveselov92
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@38c6e5c347228f490aa4d335b97731d009a73991 -
Trigger Event:
push
-
Statement type:
File details
Details for the file detectkit-0.65.0-py3-none-any.whl.
File metadata
- Download URL: detectkit-0.65.0-py3-none-any.whl
- Upload date:
- Size: 578.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a4dc0ad1fe8b4c578bf82e2b8be3a3f0c38f443797e897c35dc985cf4ed67847
|
|
| MD5 |
440d273bc2b5e990de5f8bf2b7b46842
|
|
| BLAKE2b-256 |
d453151d2f59bd064a97c41f81ea085fc3515a4e7ed556e2b2d4c4d22a0d5a89
|
Provenance
The following attestation bundles were made for detectkit-0.65.0-py3-none-any.whl:
Publisher:
publish.yml on alexeiveselov92/detectkit
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
detectkit-0.65.0-py3-none-any.whl -
Subject digest:
a4dc0ad1fe8b4c578bf82e2b8be3a3f0c38f443797e897c35dc985cf4ed67847 - Sigstore transparency entry: 2153906412
- Sigstore integration time:
-
Permalink:
alexeiveselov92/detectkit@38c6e5c347228f490aa4d335b97731d009a73991 -
Branch / Tag:
refs/tags/v0.65.0 - Owner: https://github.com/alexeiveselov92
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@38c6e5c347228f490aa4d335b97731d009a73991 -
Trigger Event:
push
-
Statement type:
