COREDNS-METRICS(7)

🎀 COREDNS-METRICS(7) — the prometheus plugin, explained 💅

okay so bestie, real talk: this is the manpage for the prometheus plugin, and its whole personality is enabling Prometheus ⟨https://prometheus.io/⟩ metrics. That's the NAME section, we're done, slay. ✨

---

🌸 DESCRIPTION 🌸

So with prometheus you export metrics from CoreDNS and, like, from any plugin that happens to have them. The default hangout spot for the metrics is localhost:9153, and the metrics path is fixed to /metrics — no negotiating, it's giving "my way or the highway". 🛣️

On top of the default Go metrics that the Prometheus Go client ⟨https://prometheus.io/docs/guides/go-application/⟩ exports on its own, you also get these absolute icons: 👑

• coredns_build_info{version, revision, goversion} — info about CoreDNS itself. the lore.
• coredns_panics_total{} — total number of panics. screaming, crying, throwing up counter 😭
• coredns_dns_requests_total{server, zone, view, proto, family, type} — total query count.
• coredns_dns_request_duration_seconds{server, zone, view, type} — duration to process each query.
• coredns_dns_request_size_bytes{server, zone, view, proto} — size of the request in bytes. Uses the original size before any plugin rewrites — pre-glow-up measurements only, bestie.
• coredns_dns_do_requests_total{server, view, zone} — queries that have the DO bit set.
• coredns_dns_response_size_bytes{server, zone, view, proto} — response size in bytes.
• coredns_dns_responses_total{server, zone, view, rcode, plugin} — response per zone, rcode and plugin.
• coredns_dns_https_responses_total{server, status} — responses per server and http status code.
• coredns_dns_quic_responses_total{server, status} — responses per server and QUIC application code.
• coredns_plugin_enabled{server, zone, view, name} — indicates whether a plugin is enabled on per server, zone and view basis.

Almost every counter carries a zone label, and that's just the zonename used for the request/response. 🗺️

✨ the extra labels, decoded ✨

• server identifies the server responsible for the request. It's a string formatted as the server's listening address: <scheme>://[<bind>]:<port>. So for a "normal" DNS server this is dns://:53. And if you're using the bind plugin, an IP address gets included too, e.g. dns://127.0.0.53:53. 🫶
• proto holds the transport of the response ("udp" or "tcp").
• family is the address family of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6)).
• type holds the query type. It covers the most common types (A, AAAA, MX, SOA, CNAME, PTR, TXT, NS, SRV, DS, DNSKEY, RRSIG, NSEC, NSEC3, HTTPS, IXFR, AXFR and ANY) plus "other", which is the group-chat where all the remaining types get lumped together. 🙈
• status holds the https status code. possible values are:
  • 200 — request is processed,
  • 404 — request has been rejected on validation,
  • 400 — request to dns message conversion failed,
  • 500 — processing ended up with no response.
• plugin holds the name of the plugin that made the write to the client. And if the server did the write (on error for instance), the value is empty. ghosted. 💀

If monitoring is enabled, queries that do not enter the plugin chain get exported under the fake name "dropped" — and note there's no closing dot on it, because this is never a valid domain name. it's a fake name, it's cosplaying, we love it.

Other plugins may export additional stats whenever the prometheus plugin is enabled — those stats are documented in each plugin's own README, so go read those, iykyk. 📚

🚨 big one, bestie: this plugin can only be used once per Server Block. one. uno. don't push it.

---

💖 SYNTAX 💖

prometheus [ADDRESS] {
    runtime_metrics
}

For each zone that you want to see metrics for. 🎯

It optionally takes a bind address to which the metrics are exported; the default listens on localhost:9153. And again — the metrics path is fixed to /metrics.

• runtime_metrics — exports the full Go runtime/metrics ⟨https://pkg.go.dev/runtime/metrics⟩ set, notably go_cpu_classes_* for CPU attribution (GC mark/assist/pause vs user code) and go_sched_latencies_seconds for goroutine scheduling delay. Adds roughly 100 scalars and 8 histograms. 🧮

⚠️ heads up: this is a process-wide latch — enabling it in any server block enables it for all of them, and it stays enabled across reloads until restart. it's not a phase, it's a lifestyle. 🔒

---

🦋 EXAMPLES 🦋

Use an alternative listening address, like the main character you are:

. {
    prometheus localhost:9253
}

Or via an environment variable (this is supported throughout the Corefile): export PORT=9253, and then:

. {
    prometheus localhost:{$PORT}
}

look at that variable interpolation go. obsessed. ✨

---

🌈 BUGS 🌈 (yes we have lore, unfortunately)

When reloading, the Prometheus handler is stopped before the new server instance is started. And if that new server fails to start? then the initial server instance is still available and DNS queries still get served, but the Prometheus handler stays down. 😭 Prometheus will not reply to HTTP requests until a successful reload or a complete restart of CoreDNS. so basically it's sitting there like "no thoughts, head empty" until you fix it. 🔥

Also: only the plugins that register as Handler are visible in coredns_plugin_enabled{server, zone, name}. As of today the plugins reload and bind will not be reported. they're lowkey invisible. 🙈

---

and that's the whole page, bestie, you ate. 💅 this was CoreDNS — October 2026 — manual page COREDNS-METRICS(7). go forth and scrape responsibly. 🍓🧚💜