From b35bf8527b999eab78f867e867871087ce4f314f Mon Sep 17 00:00:00 2001
From: Abel Luck <abel@guardianproject.info>
Date: Wed, 27 May 2026 09:07:51 +0200
Subject: [PATCH] Document Grafana queries

---
 README.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)

diff --git a/README.md b/README.md
index cf3219b..8c9b4cc 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,158 @@ include `asn`. Unmapped countries use `ZZ`; unmapped ASNs use `0`.
 - `dnstt_bytes_out_total`
 - `dnstt_sessions_total`
 
+## Grafana Queries
+
+Use `$domain` as a Grafana variable for the DNSTT domain, for example
+`t2.bypasscensorship.org`. Replace `$__rate_interval` with a fixed range such
+as `5m` if you are not using Grafana's built-in interval variables.
+
+- Title: Current active clients
+- Description: Current number of active DNSTT sessions for the selected domain.
+- Visualization: Stat or gauge.
+
+```promql
+sum(dnstt_active_clients{domain="$domain"})
+```
+
+- Title: Peak active clients
+- Description: Highest active DNSTT session count observed since the exporter
+started.
+- Visualization: Stat.
+
+```promql
+sum(dnstt_peak_clients{domain="$domain"})
+```
+
+- Title: Active clients by country
+- Description: Current active DNSTT sessions grouped by resolver country.
+- Visualization: Geomap, bar chart, or table. 
+
+```promql
+sum by (country) (dnstt_active_clients{domain="$domain"})
+```
+
+- Title: Top countries by active clients
+- Description: Countries with the most active DNSTT sessions right now.
+- Visualization: Bar chart.
+
+```promql
+topk(10, sum by (country) (dnstt_active_clients{domain="$domain"}))
+```
+
+- Title: Active clients by ASN
+- Description: Current active DNSTT sessions grouped by resolver ASN.
+- Visualization: Bar chart or table.
+
+```promql
+sum by (asn) (dnstt_active_clients{domain="$domain"})
+```
+
+- Title: Top ASNs by active clients
+- Description: Resolver ASNs with the most active DNSTT sessions right now.
+- Visualization: Bar chart.
+
+```promql
+topk(10, sum by (asn) (dnstt_active_clients{domain="$domain"}))
+```
+
+- Title: Active clients by country and ASN
+- Description: Current active DNSTT sessions split by both resolver country and
+resolver ASN.
+- Visualization: Table.
+
+```promql
+sum by (country, asn) (dnstt_active_clients{domain="$domain"})
+```
+
+- Title: Top country/ASN pairs by active clients
+- Description: Country and ASN combinations with the most active DNSTT sessions
+right now.
+- Visualization: Bar chart or table.
+
+```promql
+topk(20, sum by (country, asn) (dnstt_active_clients{domain="$domain"}))
+```
+
+- Title: DNS query rate
+- Description: Total observed DNSTT DNS queries per second for the selected
+domain.
+- Visualization: Time series.
+
+```promql
+sum(rate(dnstt_queries_total{domain="$domain"}[$__rate_interval]))
+```
+
+- Title: DNS query rate by country
+- Description: Observed DNSTT DNS queries per second grouped by resolver country.
+- Visualization: Stacked time series or bar chart. Use stacked time series for
+trends over time, and bar chart for current top countries.
+
+```promql
+sum by (country) (rate(dnstt_queries_total{domain="$domain"}[$__rate_interval]))
+```
+
+- Title: Top ASNs by DNS query rate
+- Description: Resolver ASNs producing the highest DNSTT DNS query rates.
+- Visualization: Bar chart.
+
+```promql
+topk(10, sum by (asn) (rate(dnstt_queries_total{domain="$domain"}[$__rate_interval])))
+```
+
+- Title: Inbound DNS traffic rate
+- Description: Bytes per second received in DNSTT DNS queries.
+- Visualization: Time series.
+
+```promql
+sum(rate(dnstt_bytes_in_total{domain="$domain"}[$__rate_interval]))
+```
+
+- Title: Outbound DNS traffic rate
+- Description: Bytes per second sent in DNSTT DNS responses.
+- Visualization: Time series.
+
+```promql
+sum(rate(dnstt_bytes_out_total{domain="$domain"}[$__rate_interval]))
+```
+
+- Title: DNS traffic rate by country
+- Description: Combined inbound and outbound DNSTT DNS bytes per second grouped
+by resolver country.
+- Visualization: Geomap, stacked time series, or bar chart.
+
+```promql
+sum by (country) (
+  rate(dnstt_bytes_in_total{domain="$domain"}[$__rate_interval])
+  +
+  rate(dnstt_bytes_out_total{domain="$domain"}[$__rate_interval])
+)
+```
+
+- Title: Total observed sessions
+- Description: Total unique DNSTT sessions observed since the exporter started.
+- Visualization: Stat.
+
+```promql
+sum(dnstt_sessions_total{domain="$domain"})
+```
+
+- Title: New session rate
+- Description: New DNSTT sessions observed per second.
+- Visualization: Time series.
+
+```promql
+sum(rate(dnstt_sessions_total{domain="$domain"}[$__rate_interval]))
+```
+
+- Title: New session rate by country
+- Description: New DNSTT sessions per second grouped by resolver country.
+- Visualization: Stacked time series, geomap, or bar chart.
+
+```promql
+sum by (country) (rate(dnstt_sessions_total{domain="$domain"}[$__rate_interval]))
+```
+
 ## Development
 
 ```sh