Document how to use export Prometheus metrics (folbricht#386)

cmd/routedns/example-config/prometheus-exporter/README.md

@@ -0,0 +1,3 @@
+# prometheus-exporter
+
+Example showing how to use an RouteDNS admin listener and [prometheus-expvar-exporter](https://github.com/albertito/prometheus-expvar-exporter) to make expvar metrics available in Prometheus.

cmd/routedns/example-config/prometheus-exporter/config.prom-expvar-exporter.toml

@@ -0,0 +1,94 @@
+# Address to listen on. Prometheus should be told to scrape this.
+listen_addr = ":8000"
+
+# Expvar target
+[server]
+url = "127.0.0.1:443/routedns/vars"
+insecure = true
+
+## Notes
+# Everythingwith a "#" gets automatically converted. 
+# You must specify the expvar metrics that are a map.
+#
+# For expvar lines like this:
+# "routedns.listener.local-udp.response": {"NOERROR": 776, "NXDOMAIN": 19}
+#
+# The result will look like this:
+# HELP routedns_listener_local_udp_response Various DNS response codes
+# TYPE routedns_listener_local_udp_response untyped
+# routedns_listener_local_udp_response{RCODE="NOERROR"} 776
+# routedns_listener_local_udp_response{RCODE="NXDOMAIN"} 19
+
+## Metrics mappings
+
+m.routedns_client_bootstrap_resolver_error.expvar = "routedns.client.bootstrap-resolver.error"
+m.routedns_client_bootstrap_resolver_error.help = "Amount of dropped requests"
+m.routedns_client_bootstrap_resolver_error.label_name = "REASON"
+m.routedns_client_bootstrap_resolver_response.expvar = "routedns.client.bootstrap-resolver.response"
+m.routedns_client_bootstrap_resolver_response.label_name = "RCODE"
+
+m.routedns_client_1001_doh_quic_error.expvar = "routedns.client.1001-doh-quic.error"
+m.routedns_client_1001_doh_quic_error.label_name = "REASON"
+m.routedns_client_1001_doh_quic_response.expvar = "routedns.client.1001-doh-quic.response"
+m.routedns_client_1001_doh_quic_response.label_name = "RCODE"
+
+m.routedns_client_1111_doh_quic_error.expvar = "routedns.client.1111-doh-quic.error"
+m.routedns_client_1111_doh_quic_error.label_name = "REASON"
+m.routedns_client_1111_doh_quic_response.expvar = "routedns.client.1111-doh-quic.response"
+m.routedns_client_1111_doh_quic_response.label_name = "RCODE"
+
+m.routedns_client_adguard_doh_quic_error.expvar = "routedns.client.adguard-doh-quic.error"
+m.routedns_client_adguard_doh_quic_error.label_name = "REASON"
+m.routedns_client_adguard_doh_quic_response.expvar = "routedns.client.adguard-doh-quic.response"
+m.routedns_client_adguard_doh_quic_response.label_name = "RCODE"
+
+m.routedns_client_adguard_doq_quic_error.expvar = "routedns.client.adguard-doq-quic.error"
+m.routedns_client_adguard_doq_quic_error.label_name = "REASON"
+m.routedns_client_adguard_doq_quic_response.expvar = "routedns.client.adguard-doq-quic.response"
+m.routedns_client_adguard_doq_quic_response.label_name = "RCODE"
+
+m.routedns_client_cloudflare_1001_doh_error.expvar = "routedns.client.cloudflare-1001-doh.error"
+m.routedns_client_cloudflare_1001_doh_error.label_name = "REASON"
+m.routedns_client_cloudflare_1001_doh_response.expvar = "routedns.client.cloudflare-1001-doh.response"
+m.routedns_client_cloudflare_1001_doh_response.label_name = "RCODE"
+
+m.routedns_client_cloudflare_1111_doh_error.expvar = "routedns.client.cloudflare_1111_doh.error"
+m.routedns_client_cloudflare_1111_doh_error.label_name = "REASON"
+m.routedns_client_cloudflare_1111_doh_response.expvar = "routedns.client.cloudflare_1111_doh.response"
+m.routedns_client_cloudflare_1111_doh_response.label_name = "RCODE"
+
+m.routedns_client_cloudflare_doh_quic_error.expvar = "routedns.client.cloudflare_doh-quic.error"
+m.routedns_client_cloudflare_doh_quic_error.label_name = "REASON"
+m.routedns_client_cloudflare_doh_quic_response.expvar = "routedns.client.cloudflare_doh-quic.response"
+m.routedns_client_cloudflare_doh_quic_response.label_name = "RCODE"
+
+m.routedns_client_cloudflare_dot_1_error.expvar = "routedns.client.cloudflare_dot-1.error"
+m.routedns_client_cloudflare_dot_1_error.label_name = "REASON"
+m.routedns_client_cloudflare_dot_1_response.expvar = "routedns.client.cloudflare_dot-1.response"
+m.routedns_client_cloudflare_dot_1_response.label_name = "RCODE"
+
+m.routedns_client_cloudflare_dot_2_error.expvar = "routedns.client.cloudflare_dot-2.error"
+m.routedns_client_cloudflare_dot_2_error.label_name = "REASON"
+m.routedns_client_cloudflare_dot_2_response.expvar = "routedns.client.cloudflare_dot-2.response"
+m.routedns_client_cloudflare_dot_2_response.label_name = "RCODE"
+
+m.routedns_client_controld_doh_quic_error.expvar = "routedns.client.controld-doh-quic.error"
+m.routedns_client_controld_doh_quic_error.label_name = "REASON"
+m.routedns_client_controld_doh_quic_response.expvar = "routedns.client.controld-doh-quic.response"
+m.routedns_client_controld_doh_quic_response.label_name = "RCODE"
+
+m.routedns_client_controld_doq_error.expvar = "routedns.client.controld-doq.error"
+m.routedns_client_controld_doq_error.label_name = "REASON"
+m.routedns_client_controld_doq_response.expvar = "routedns.client.controld-doq.response"
+m.routedns_client_controld_doq_response.label_name = "RCODE"
+
+m.routedns_listener_local_tcp_error.expvar = "routedns.listener.local-tcp.error"
+m.routedns_listener_local_tcp_error.label_name = "REASON"
+m.routedns_listener_local_tcp_response.expvar = "routedns.listener.local-tcp.response"
+m.routedns_listener_local_tcp_response.label_name = "RCODE"
+
+m.routedns_listener_local_udp_error.expvar = "routedns.listener.local-udp.error"
+m.routedns_listener_local_udp_error.label_name = "REASON"
+m.routedns_listener_local_udp_response.expvar = "routedns.listener.local-udp.response"
+m.routedns_listener_local_udp_response.help = "Various DNS response codes"
+m.routedns_listener_local_udp_response.label_name = "RCODE"

cmd/routedns/example-config/prometheus-exporter/config.routedns.toml

@@ -0,0 +1,114 @@
+#### BOOTSTRAP ####
+
+[bootstrap-resolver]
+protocol = "doh"
+address = "https://dns9.quad9.net:443/dns-query"
+bootstrap-address = "9.9.9.9"
+
+#### LISTENERS ####
+
+[listeners.local_udp]
+address = ":53"
+protocol = "udp"
+resolver = "ecs"
+
+[listeners.local_tcp]
+address = ":53"
+protocol = "tcp"
+resolver = "ecs"
+
+[listeners.local_admin]
+address = ":443"
+protocol = "admin"
+server-crt = "/app/server.crt"
+server-key = "/app/server.key"
+
+#### GROUPS ####
+
+# ECS
+[groups.ecs]
+type = "ecs-modifier"
+resolvers = ["edns0"]
+ecs-op = "delete"
+
+# EDNS0
+[groups.edns0]
+type = "edns0-modifier"
+resolvers = ["cache"]
+edns0-op = "delete"
+
+# Cache
+[groups.cache]
+type = "cache"
+resolvers = ["fastest"]
+cache-negative-ttl = 120
+cache-prefetch-trigger = 10
+cache-prefetch-eligible = 20
+cache-answer-shuffle = "round-robin"
+cache-harden-below-nxdomain = true
+backend = {type = "memory"}
+
+[groups.fastest]
+type   = "fastest"
+resolvers = ["cloudflare-1111-doh", "cloudflare-1001-doh", "cloudflare-doh-quic", "1111-doh-quic", "1001-doh-quic", "controld-doh-quic", "adguard-doh-quic", "controld-doq", "adguard-doq", "cloudflare-dot-1", "cloudflare-dot-2",]
+
+#### RESOLVERS ####
+
+## DoH ##
+
+[resolvers.cloudflare_1111_doh]
+address = "https://1.1.1.1/dns-query"
+protocol = "doh"
+
+[resolvers.cloudflare-1001-doh]
+address = "https://1.0.0.1/dns-query"
+protocol = "doh"
+
+# ## DoH3 ##
+
+[resolvers.cloudflare-doh-quic]
+address = "https://cloudflare-dns.com/dns-query"
+protocol = "doh"
+transport = "quic"
+
+[resolvers.1111-doh-quic]
+address = "https://1.1.1.1/dns-query"
+protocol = "doh"
+transport = "quic"
+
+[resolvers.1001-doh-quic]
+address = "https://1.0.0.1/dns-query"
+protocol = "doh"
+transport = "quic"
+
+[resolvers.controld-doh-quic]
+address = "https://freedns.controld.com/p0"
+protocol = "doh"
+transport = "quic"
+
+[resolvers.adguard-doh-quic]
+address = "https://unfiltered.adguard-dns.com/dns-query"
+protocol = "doh"
+transport = "quic"
+
+# ## DoQ ##
+
+[resolvers.controld-doq]
+address = "p0.freedns.controld.com:853"
+protocol = "doq"
+
+[resolvers.adguard-doq]
+address = "dns-unfiltered.adguard.com:853"
+protocol = "doq"
+
+# ## DoT ##
+
+[resolvers.cloudflare-dot-1]
+address = "1.1.1.1:853"
+protocol = "dot"
+
+[resolvers.cloudflare-dot-2]
+address = "1.0.0.1:853"
+protocol = "dot"
+
+

doc/configuration.md

@@ -269,7 +269,7 @@ Example config files: [doq-listener.toml](../cmd/routedns/example-config/doq-lis
 
 ### Admin
 
-The Admin listener provides metrics on RouteDNS usage and performance at https://{address}/routedns/vars/.
+The Admin listener provides metrics on RouteDNS usage and performance at https://{address}/routedns/vars/ in [expvar](https://pkg.go.dev/expvar) format. These metrics can be exported to be usable by Prometheus using [prometheus-expvar-exporter](https://github.com/albertito/prometheus-expvar-exporter). An example configuration is provided below.
 
 Examples:
 
@@ -281,7 +281,7 @@ server-crt = "example-config/server.crt"
 server-key = "example-config/server.key"
 ```
 
-Example config files: [admin.toml](../cmd/routedns/example-config/admin.toml)
+Example config files: [admin.toml](../cmd/routedns/example-config/admin.toml), [prometheus-exporter](../cmd/routedns/example-config/prometheus-exporter/)
 
 ## Modifiers, Groups and Routers