metrics

README

prometheus

Name

prometheus - enables Prometheus metrics.

Description

With prometheus you export metrics from CoreDNS and any plugin that has them. The default location for the metrics is localhost:9153. The metrics path is fixed to /metrics.

In addition to the default Go metrics exported by the Prometheus Go client, the following metrics are exported:

• coredns_build_info{version, revision, goversion} - info about CoreDNS itself.
• coredns_panics_total{} - total number of panics.
• coredns_dns_requests_total{server, zone, proto, family, type} - total query count.
• coredns_dns_request_duration_seconds{server, zone, type} - duration to process each query.
• coredns_dns_request_size_bytes{server, zone, proto} - size of the request in bytes.
• coredns_dns_do_requests_total{server, zone} - queries that have the DO bit set
• coredns_dns_response_size_bytes{server, zone, proto} - response size in bytes.
• coredns_dns_responses_total{server, zone, rcode, plugin} - response per zone, rcode and plugin.
• coredns_dns_https_responses_total{server, status} - responses per server and http status code.
• coredns_plugin_enabled{server, zone, name} - indicates whether a plugin is enabled on per server and zone basis.

Almost each counter has a label zone which is the zonename used for the request/response.

Extra labels used are:

• server is identifying the server responsible for the request. This is a string formatted as the server's listening address: <scheme>://[<bind>]:<port>. I.e. for a "normal" DNS server this is dns://:53. If you are using the bind plugin an IP address is included, e.g.: dns://127.0.0.53:53.
• proto which holds the transport of the response ("udp" or "tcp")
• The address family (family) of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6)).
• type which holds the query type. It holds most common types (A, AAAA, MX, SOA, CNAME, PTR, TXT, NS, SRV, DS, DNSKEY, RRSIG, NSEC, NSEC3, HTTPS, IXFR, AXFR and ANY) and "other" which lumps together all other types.
• status which 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.
• the plugin label holds the name of the plugin that made the write to the client. If the server did the write (on error for instance), the value is empty.

If monitoring is enabled, queries that do not enter the plugin chain are exported under the fake name "dropped" (without a closing dot - this is never a valid domain name).

Other plugins may export additional stats when the prometheus plugin is enabled. Those stats are documented in each plugin's README.

This plugin can only be used once per Server Block.

Syntax

prometheus [ADDRESS]

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. The metrics path is fixed to /metrics.

Examples

Use an alternative listening address:

. {
    prometheus localhost:9253
}

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

. {
    prometheus localhost:{$PORT}
}

Bugs

When reloading, the Prometheus handler is stopped before the new server instance is started. If that new server fails to start, then the initial server instance is still available and DNS queries still served, but Prometheus handler stays down. Prometheus will not reply HTTP request until a successful reload or a complete restart of CoreDNS. 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.

Documentation

Overview

Package metrics implement a handler and plugin that provides Prometheus metrics.

Index

• Variables
• func WithServer(ctx context.Context) string
• type Metrics
  • func New(addr string) *Metrics
  • func (m *Metrics) AddZone(z string)
  • func (m *Metrics) MustRegister(c prometheus.Collector)
  • func (m *Metrics) Name() string
  • func (m *Metrics) OnFinalShutdown() error
  • func (m *Metrics) OnRestart() error
  • func (m *Metrics) OnStartup() error
  • func (m *Metrics) RemoveZone(z string)
  • func (m *Metrics) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
  • func (m *Metrics) ZoneNames() []string
• type Recorder
  • func NewRecorder(w dns.ResponseWriter) *Recorder
  • func (r *Recorder) WriteMsg(res *dns.Msg) error

Variables

var ListenAddr string

ListenAddr is assigned the address of the prometheus listener. Its use is mainly in tests where we listen on "localhost:0" and need to retrieve the actual address.

Functions

func WithServer

func WithServer(ctx context.Context) string

WithServer returns the current server handling the request. It returns the server listening address: <scheme>://[<bind>]:<port> Normally this is something like "dns://:53", but if the bind plugin is used, i.e. "bind 127.0.0.53", it will be "dns://127.0.0.53:53", etc. If not address is found the empty string is returned.

Basic usage with a metric:

<metric>.WithLabelValues(metrics.WithServer(ctx), labels..).Add(1)

Types

type Metrics

type Metrics struct {
	Next plugin.Handler
	Addr string
	Reg  *prometheus.Registry
	// contains filtered or unexported fields
}

Metrics holds the prometheus configuration. The metrics' path is fixed to be /metrics .

func New

func New(addr string) *Metrics

New returns a new instance of Metrics with the given address.

func (*Metrics) AddZone

func (m *Metrics) AddZone(z string)

AddZone adds zone z to m.

func (*Metrics) MustRegister

func (m *Metrics) MustRegister(c prometheus.Collector)

MustRegister wraps m.Reg.MustRegister.

func (*Metrics) Name

func (m *Metrics) Name() string

Name implements the Handler interface.

func (*Metrics) OnFinalShutdown

func (m *Metrics) OnFinalShutdown() error

OnFinalShutdown tears down the metrics listener on shutdown and restart.

func (*Metrics) OnRestart

func (m *Metrics) OnRestart() error

OnRestart stops the listener on reload.

func (*Metrics) OnStartup

func (m *Metrics) OnStartup() error

OnStartup sets up the metrics on startup.

func (*Metrics) RemoveZone

func (m *Metrics) RemoveZone(z string)

RemoveZone remove zone z from m.

func (*Metrics) ServeDNS

func (m *Metrics) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the Handler interface.

func (*Metrics) ZoneNames

func (m *Metrics) ZoneNames() []string

ZoneNames returns the zones of m.

type Recorder

type Recorder struct {
	*dnstest.Recorder
	// CallerN holds the string return value of the call to runtime.Caller(N+1)
	Caller [3]string
}

Recorder is a dnstest.Recorder specific to the metrics plugin.

func NewRecorder

func NewRecorder(w dns.ResponseWriter) *Recorder

NewRecorder makes and returns a new Recorder.

func (*Recorder) WriteMsg

func (r *Recorder) WriteMsg(res *dns.Msg) error

WriteMsg records the status code and calls the underlying ResponseWriter's WriteMsg method.