detectkit

PyPI version Python Docs & playground

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, Webhook
  • @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
  • 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 + three 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[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}")

Documentation

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.

Project links

Data verified by PyPI on Jul 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.67.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for alexeiveselov from gravatar.com alexeiveselov

Credits

Author: detectkit team

GitHub Statistics

Data verified by PyPI on Jul 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

clickhouse postgres mysql all-db prophet timesfm advanced-detectors osi all dev integration

Tags

monitoring anomaly-detection metrics timeseries alerting

Classifiers

Report project as malware

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.52.1.tar.gz (381.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

detectkit-0.52.1-py3-none-any.whl (454.8 kB view details)

Uploaded Python 3

File details

Details for the file detectkit-0.52.1.tar.gz.

File metadata

  • Download URL: detectkit-0.52.1.tar.gz
  • Upload date:
  • Size: 381.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for detectkit-0.52.1.tar.gz
Algorithm Hash digest
SHA256 f05bdd89800764fe1582623a8cecdf38e797284f6354a8698fd3b23c3de99b4a
MD5 8ee2a5ea2f047068b9cafd91bc66def8
BLAKE2b-256 be25021a1c208e8f2d08c0c24f15b95d140c665cef4de513b19be6a7550da7ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for detectkit-0.52.1.tar.gz:

Publisher: publish.yml on alexeiveselov92/detectkit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file detectkit-0.52.1-py3-none-any.whl.

File metadata

  • Download URL: detectkit-0.52.1-py3-none-any.whl
  • Upload date:
  • Size: 454.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for detectkit-0.52.1-py3-none-any.whl
Algorithm Hash digest
SHA256 79e8f1b489d1e58142ffd4ad7e713bd46ce25d41795e7c2b4017a31286192eee
MD5 36f7e52917cd7d97ed2c33aadc8e1fcd
BLAKE2b-256 c83f2eb02c0ddecc890f4d6e994ddcd13d0806178b895a0a42eec0932404072c

See more details on using hashes here.

Provenance

The following attestation bundles were made for detectkit-0.52.1-py3-none-any.whl:

Publisher: publish.yml on alexeiveselov92/detectkit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.67.1

0.67.0

0.66.5

0.66.4

0.66.3

0.66.2

0.66.1

0.66.0

0.65.0

0.64.0

0.63.0

0.62.1

0.62.0

0.61.0

0.60.0

0.59.0

0.58.0

0.57.0

0.56.2

0.56.1

0.56.0

0.55.2

0.55.1

0.55.0

0.54.0

0.53.3

0.53.2

0.53.1

0.53.0

This release

0.52.1

0.52.0

0.51.0

0.50.0

0.49.2

0.49.1

0.49.0

0.48.0

0.47.0

0.46.0

0.45.1

0.45.0

0.44.1

0.44.0

0.43.0

0.42.0

0.41.0

0.40.0

0.39.2

0.39.1

0.39.0

0.38.0

0.37.0

0.36.2

0.36.1

0.36.0

0.35.0

0.34.0

0.33.0

0.32.0

0.31.1

0.31.0

0.30.1

0.30.0

0.29.0

0.28.0

0.27.0

0.26.1

0.26.0

0.25.0

0.24.2

0.24.1

0.24.0

0.23.2

0.23.1

0.23.0

0.22.0

0.21.0

0.20.0

0.19.0

0.18.0

0.17.0

0.16.4

0.16.3

0.16.2

0.16.1

0.16.0

0.15.0

0.14.0

0.13.1

0.13.0

0.12.0

0.11.0

0.10.0

0.9.0

0.8.2

0.8.1

0.8.0

0.7.0

0.6.0

0.5.3

0.5.2

0.5.1

0.5.0

0.4.1

0.4.0

0.3.17

0.3.16

0.3.15

0.3.14

0.3.13

0.3.12

0.3.11

0.3.10

0.3.9

0.3.8

0.3.7

0.3.6

0.3.5

0.3.4

0.3.3

0.3.2

0.3.1

0.3.0

0.2.8

0.2.7

0.2.6

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

0.1.2

0.1.1

0.1.0

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page