detectkit

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-claude sets 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/clean as a CI check or scheduled job and gates on detectkit's own exit-code contract, with the --json run 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.