ding.yaml.example

# ding.yaml.example — copy to ding.yaml and customize.
#
# Two ways DING uses this config:
#   ding run -- <cmd>     wraps a command; rules below evaluate against
#                         events the command emits + the synthetic run.exit
#   ding serve            long-running HTTP daemon; rules evaluate against
#                         events POSTed to /ingest or piped via stdin
#
# Preview rules without sending notifications:
#   echo '{"metric":"name","value":42}' | ding test-rule --config ding.yaml
#   ding run --dry-run --config ding.yaml -- ./your-script.sh
# See: docs/configuration.md#testing-rules-without-a-workload

server:
  port: 8080
  format: auto          # json | prometheus | auto
  # JQ transform (optional): transform arbitrary inbound JSON before parsing.
  # The expression must produce an object or array of objects, each with
  # "metric" (string) and "value" (number) fields. Extra fields become labels.
  # Example: accept Datadog-style batched events:
  # jq: '.series[] | {metric: .metric, value: (.points[0][1]), host: .tags[0]}'
  max_buffer_size: 10000
  # HTTP server timeouts (optional, secure defaults applied if omitted)
  # read_timeout: 5s
  # write_timeout: 10s
  # idle_timeout: 60s
  # Max request body size for /ingest (optional, default 1 MB)
  # max_body_bytes: 1048576
  # How long ding run waits for notifier queues to flush on exit (default 5s).
  # Must be longer than your total retry window (initial_backoff * 2^max_attempts)
  # or later retry attempts will be silently truncated.
  # drain_timeout: 5s

# State persistence (optional — omit entire section to disable)
# Only meaningful in `ding serve` mode; `ding run` is intrinsically per-run.
# persistence:
#   state_file: /var/lib/ding/state.json
#   flush_interval: 30s

# Alert log (optional — append every fired alert as a JSON line to a file)
# Useful for debugging: "did DING fire? when? for which rule?"
# alert_log:
#   path: /var/log/ding/alerts.jsonl

# Environment variable substitution
# DING expands env-var references in this file at startup, so secrets like
# webhook URLs and tokens can live in environment variables rather than in
# source. Hard error if any referenced var is unset; empty string is allowed.
# See docs/configuration.md#environment-variable-substitution for syntax and
# the full behavior table.

notifiers:
  # Built-in notifiers (no declaration needed): stdout, github_actions.
  #
  # Slack (Block Kit — run-context fields surfaced automatically):
  # alert-slack:
  #   type: slack
  #   url: https://hooks.slack.com/services/T.../B.../...
  #   max_attempts: 3
  #   initial_backoff: 1s
  #
  # Discord (Embeds — run-context fields surfaced automatically):
  # alert-discord:
  #   type: discord
  #   url: https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN
  #   max_attempts: 3
  #   initial_backoff: 1s
  #
  # Microsoft Teams (Adaptive Card via Workflows incoming webhook):
  # Get the webhook URL from Teams: channel > Workflows app >
  # "Post to a channel when a webhook request is received".
  # alert-teams:
  #   type: teams
  #   url: https://prod-XX.westus.logic.azure.com:443/workflows/...
  #   max_attempts: 3
  #   initial_backoff: 1s
  #
  # Generic webhook (flat JSON payload):
  # alert-webhook:
  #   type: webhook
  #   url: https://hooks.slack.com/services/T.../...
  #   max_attempts: 3
  #   initial_backoff: 1s
  #
  # Native K8s Events — visible to `kubectl describe pod` / `kubectl get events`.
  # Requires DING running in-cluster (ServiceAccount auth) + RBAC for events.create.
  # See docs/recipes/kubernetes-jobs.md for the manifest fragment + RBAC example.
  # alert-k8s:
  #   type: kubernetes_event
  #   # event_reason: DingAlertFired   # default
  #   # event_type: Warning            # "Normal" or "Warning"; default Warning
  #   # namespace: ""                  # override POD_NAMESPACE downward API
  #   max_attempts: 3
  #   initial_backoff: 1s
  #
  # GitLab CI artifact (writes alert Markdown to a file; user declares the path
  # in .gitlab-ci.yml `artifacts:` to surface it as a pipeline artifact):
  # alert-gitlab:
  #   type: gitlab_artifact
  #   # path: ding-alerts.md      # default; relative to CWD ($CI_PROJECT_DIR in GitLab CI)
  #
  # Buildkite annotation (publishes alerts as Buildkite build annotations via
  # `buildkite-agent annotate`; visible at the top of the build UI):
  # alert-buildkite:
  #   type: buildkite_annotate
  #   # style: error              # default; success | info | warning | error

rules:
  # Event-per-event: fires on a single reading above threshold.
  - name: cpu_spike
    match:
      metric: cpu_usage
    condition: value > 95
    cooldown: 1m
    message: "CPU spike: {{ .value }}% on {{ .host }}"
    alert:
      - notifier: stdout

  # Windowed: fires on sustained high CPU (avg over 5 minutes).
  - name: cpu_sustained
    match:
      metric: cpu_usage
    condition: avg(value) over 5m > 80
    cooldown: 10m
    message: "Sustained high CPU: avg {{ .avg }}% on {{ .host }}"
    alert:
      - notifier: stdout

  # End-of-run: fires once when `ding run` exits, against accumulated state.
  # Inert in `ding serve` mode (no run boundary). Useful for job summaries.
  # - name: regression
  #   match:
  #     metric: test.duration
  #   mode: end-of-run
  #   condition: avg(value) over 1h > 1
  #   message: "p50 test latency was {{ .avg }}s (count={{ .count }})"
  #   alert:
  #     - notifier: github_actions

  # Match the synthetic run.exit event for job-level outcome alerts.
  # `ding run` emits this event when the wrapped command exits.
  # - name: nonzero_exit
  #   match:
  #     metric: run.exit
  #   condition: value > 0
  #   message: "job failed: exit code {{ .value }} after {{ .duration_seconds | humanize_duration }}"
  #   alert:
  #     - notifier: github_actions

  # Whole-run aggregate alert — fires once at run exit if avg memory across
  # the entire run exceeded 80%. The "over run" window is bounded by the
  # ding run subprocess lifetime; no events are evicted by wall-clock time.
  # - name: high_avg_mem
  #   match:
  #     metric: mem_pct
  #   condition: avg(value) over run > 80
  #   mode: end-of-run
  #   message: "avg memory was {{ .avg }}% across the run"
  #   alert:
  #     - notifier: slack