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
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.66.5.tar.gz
(494.7 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.66.5-py3-none-any.whl
(581.2 kB
view details)
File details
Details for the file detectkit-0.66.5.tar.gz.
File metadata
- Download URL: detectkit-0.66.5.tar.gz
- Upload date:
- Size: 494.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fdd6d22eeec1b963065a416d911816c9b66ac13858778a6f6e4af790044173fc
|
|
| MD5 |
2b66883b6fd198de8ba0b96690d038d3
|
|
| BLAKE2b-256 |
ad4ea20ebc0ce2daff82d12b1c50839d67151f57a7ddf98202c1f81392b7f125
|
Provenance
The following attestation bundles were made for detectkit-0.66.5.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.66.5.tar.gz -
Subject digest:
fdd6d22eeec1b963065a416d911816c9b66ac13858778a6f6e4af790044173fc - Sigstore transparency entry: 2186573261
- Sigstore integration time:
-
Permalink:
alexeiveselov92/detectkit@995d8377df6b67fba8d63dd724da154b1cb3764a -
Branch / Tag:
refs/tags/v0.66.5 - Owner: https://github.com/alexeiveselov92
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@995d8377df6b67fba8d63dd724da154b1cb3764a -
Trigger Event:
push
-
Statement type:
File details
Details for the file detectkit-0.66.5-py3-none-any.whl.
File metadata
- Download URL: detectkit-0.66.5-py3-none-any.whl
- Upload date:
- Size: 581.2 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 |
6ea1286fa378c13565b314ae6eb71cb9a7a98478fc9628a441979d1a6ed45f13
|
|
| MD5 |
07422496c0c13d906333c910d3518a9b
|
|
| BLAKE2b-256 |
f6aa6f8b5bab8afbb3f55114b5a3bb944ad57d0f45eb7b235d2bebf57f29c758
|
Provenance
The following attestation bundles were made for detectkit-0.66.5-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.66.5-py3-none-any.whl -
Subject digest:
6ea1286fa378c13565b314ae6eb71cb9a7a98478fc9628a441979d1a6ed45f13 - Sigstore transparency entry: 2186573359
- Sigstore integration time:
-
Permalink:
alexeiveselov92/detectkit@995d8377df6b67fba8d63dd724da154b1cb3764a -
Branch / Tag:
refs/tags/v0.66.5 - Owner: https://github.com/alexeiveselov92
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@995d8377df6b67fba8d63dd724da154b1cb3764a -
Trigger Event:
push
-
Statement type:
