# grafana/promql-anomaly-detection architecture

> Architecture diagram of the GitHub repository grafana/promql-anomaly-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grafana/promql-anomaly-detection
- Repository: https://github.com/grafana/promql-anomaly-detection

## Overview

This repository is a PromQL anomaly-detection framework, primarily implemented as Prometheus recording and alerting rules. Users tag metrics with anomaly labels, configure Prometheus to load the rules, and use the resulting anomaly bands and alerts; Grafana dashboards provide visualization. The README documents adaptive and robust strategies and a demo stack. Source excerpts were unavailable, so relationships below are limited to those explicitly described in the README.

Main entry points: [`demo/docker-compose.yml`](https://github.com/grafana/promql-anomaly-detection/blob/main/demo/docker-compose.yml) (Demo services), [`demo/src/grafana`](https://github.com/grafana/promql-anomaly-detection/tree/main/demo/src/grafana) (Grafana), [`rules/adaptive.yml`](https://github.com/grafana/promql-anomaly-detection/blob/main/rules/adaptive.yml) (Adaptive bands), [`rules/robust.yml`](https://github.com/grafana/promql-anomaly-detection/blob/main/rules/robust.yml) (Robust bands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rules["Detection rules"]
  node_rule_config["Rule configuration"]
  node_adaptive["Adaptive bands<br/>[adaptive.yml]"]
  node_robust["Robust bands<br/>[robust.yml]"]
  node_examples["Metric selection examples"]
  node_extra["Extra rules"]
  node_alerts["Band crossing alerts"]
end

subgraph group_demo["Demo and visualization"]
  node_demo_prom_config["Demo Prometheus config"]
  node_grafana["Grafana"]
  node_anomaly_dashboards["Anomaly dashboards"]
  node_demo_stack["Demo services<br/>[docker-compose.yml]"]
  node_otel_config["OTel Collector config<br/>[otelcol-config.yml]"]
  node_frontend_proxy["Frontend proxy<br/>[envoy.tmpl.yaml]"]
end

node_user(("Metric operator"))
node_metrics[("Tagged metrics")]
node_prometheus["Prometheus"]
node_operator(("Dashboard user"))

node_user -->|"tags for detection"| node_metrics
node_metrics -->|"provides time series"| node_prometheus
node_prometheus -->|"loads configured rules"| node_rule_config
node_adaptive -->|"generates bands"| node_prometheus
node_robust -->|"generates bands"| node_prometheus
node_examples -->|"guides metric selection"| node_user
node_prometheus -->|"detects band crossings"| node_alerts
node_demo_stack -->|"starts demo services"| node_demo_prom_config
node_demo_stack -->|"starts demo services"| node_grafana
node_demo_stack -->|"starts demo services"| node_otel_config
node_grafana -->|"displays anomalies"| node_anomaly_dashboards
node_operator -->|"views dashboards"| node_grafana

click node_rule_config "https://github.com/grafana/promql-anomaly-detection/tree/main/rules"
click node_adaptive "https://github.com/grafana/promql-anomaly-detection/blob/main/rules/adaptive.yml"
click node_robust "https://github.com/grafana/promql-anomaly-detection/blob/main/rules/robust.yml"
click node_examples "https://github.com/grafana/promql-anomaly-detection/tree/main/rules/examples"
click node_extra "https://github.com/grafana/promql-anomaly-detection/tree/main/rules/extra"
click node_alerts "https://github.com/grafana/promql-anomaly-detection/tree/main/rules"
click node_demo_prom_config "https://github.com/grafana/promql-anomaly-detection/blob/main/demo/src/prometheus/prometheus-config.yaml"
click node_grafana "https://github.com/grafana/promql-anomaly-detection/tree/main/demo/src/grafana"
click node_anomaly_dashboards "https://github.com/grafana/promql-anomaly-detection/tree/main/demo/src/grafana/provisioning/dashboards/anomalies"
click node_demo_stack "https://github.com/grafana/promql-anomaly-detection/blob/main/demo/docker-compose.yml"
click node_otel_config "https://github.com/grafana/promql-anomaly-detection/blob/main/demo/src/otelcollector/otelcol-config.yml"
click node_frontend_proxy "https://github.com/grafana/promql-anomaly-detection/blob/main/demo/src/frontendproxy/envoy.tmpl.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rule_config,node_adaptive,node_robust,node_examples,node_extra,node_alerts,node_operator toneBlue
class node_demo_prom_config,node_grafana,node_anomaly_dashboards,node_demo_stack,node_otel_config,node_frontend_proxy,node_metrics toneAmber
class node_user,node_prometheus toneIndigo
```

## Components

### Detection rules

- [Rule configuration](https://github.com/grafana/promql-anomaly-detection/tree/main/rules): `rules`
- [Adaptive bands](https://github.com/grafana/promql-anomaly-detection/blob/main/rules/adaptive.yml): `rules/adaptive.yml`
- [Robust bands](https://github.com/grafana/promql-anomaly-detection/blob/main/rules/robust.yml): `rules/robust.yml`
- [Metric selection examples](https://github.com/grafana/promql-anomaly-detection/tree/main/rules/examples): `rules/examples`
- [Extra rules](https://github.com/grafana/promql-anomaly-detection/tree/main/rules/extra): `rules/extra`
- [Band crossing alerts](https://github.com/grafana/promql-anomaly-detection/tree/main/rules): `rules`

### Demo and visualization

- [Demo Prometheus config](https://github.com/grafana/promql-anomaly-detection/blob/main/demo/src/prometheus/prometheus-config.yaml): `demo/src/prometheus/prometheus-config.yaml`
- [Grafana](https://github.com/grafana/promql-anomaly-detection/tree/main/demo/src/grafana): `demo/src/grafana`
- [Anomaly dashboards](https://github.com/grafana/promql-anomaly-detection/tree/main/demo/src/grafana/provisioning/dashboards/anomalies): `demo/src/grafana/provisioning/dashboards/anomalies`
- [Demo services](https://github.com/grafana/promql-anomaly-detection/blob/main/demo/docker-compose.yml): `demo/docker-compose.yml`
- [OTel Collector config](https://github.com/grafana/promql-anomaly-detection/blob/main/demo/src/otelcollector/otelcol-config.yml): `demo/src/otelcollector/otelcol-config.yml`
- [Frontend proxy](https://github.com/grafana/promql-anomaly-detection/blob/main/demo/src/frontendproxy/envoy.tmpl.yaml): `demo/src/frontendproxy/envoy.tmpl.yaml`

### Other components

- **Metric operator**
- **Tagged metrics**
- **Prometheus**
- **Dashboard user**

## Connections

- Metric operator → Tagged metrics: tags for detection (evidence: `README.md`)
- Tagged metrics → Prometheus: provides time series (evidence: `README.md`)
- Prometheus → Rule configuration: loads configured rules (evidence: `README.md`)
- Adaptive bands → Prometheus: generates bands (evidence: `README.md`)
- Robust bands → Prometheus: generates bands (evidence: `README.md`)
- Metric selection examples → Metric operator: guides metric selection (evidence: `README.md`)
- Prometheus → Band crossing alerts: detects band crossings (evidence: `README.md`)
- Demo services → Demo Prometheus config: starts demo services (evidence: `README.md`)
- Demo services → Grafana: starts demo services (evidence: `README.md`)
- Demo services → OTel Collector config: starts demo services (evidence: `README.md`)
- Grafana → Anomaly dashboards: displays anomalies (evidence: `README.md`)
- Dashboard user → Grafana: views dashboards (evidence: `README.md`)
