mirror of
https://github.com/coredns/coredns.git
synced 2026-04-05 11:45:33 -04:00
177 lines
3.7 KiB
Groff
177 lines
3.7 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-TRACE" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fItrace\fP - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
With \fItrace\fP you enable OpenTracing of how a request flows through CoreDNS. Enable the \fIdebug\fP
|
|
plugin to get logs from the trace plugin.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
The simplest form is just:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
trace [ENDPOINT\-TYPE] [ENDPOINT]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBENDPOINT-TYPE\fP is the type of tracing destination. Currently only \fB\fCzipkin\fR and \fB\fCdatadog\fR are supported.
|
|
Defaults to \fB\fCzipkin\fR.
|
|
.IP \(bu 4
|
|
\fBENDPOINT\fP is the tracing destination, and defaults to \fB\fClocalhost:9411\fR. For Zipkin, if
|
|
\fBENDPOINT\fP does not begin with \fB\fChttp\fR, then it will be transformed to \fB\fChttp://ENDPOINT/api/v1/spans\fR.
|
|
|
|
|
|
.PP
|
|
With this form, all queries will be traced.
|
|
|
|
.PP
|
|
Additional features can be enabled with this syntax:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
trace [ENDPOINT\-TYPE] [ENDPOINT] {
|
|
every AMOUNT
|
|
service NAME
|
|
client\_server
|
|
datadog\_analytics\_rate RATE
|
|
zipkin\_max\_backlog\_size SIZE
|
|
zipkin\_max\_batch\_size SIZE
|
|
zipkin\_max\_batch\_interval DURATION
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fB\fCevery\fR \fBAMOUNT\fP will only trace one query of each AMOUNT queries. For example, to trace 1 in every
|
|
100 queries, use AMOUNT of 100. The default is 1.
|
|
.IP \(bu 4
|
|
\fB\fCservice\fR \fBNAME\fP allows you to specify the service name reported to the tracing server.
|
|
Default is \fB\fCcoredns\fR.
|
|
.IP \(bu 4
|
|
\fB\fCclient_server\fR will enable the \fB\fCClientServerSameSpan\fR OpenTracing feature.
|
|
.IP \(bu 4
|
|
\fB\fCdatadog_analytics_rate\fR \fBRATE\fP will enable trace analytics
|
|
\[la]https://docs.datadoghq.com/tracing/app_analytics\[ra] on the traces sent
|
|
from \fI0\fP to \fI1\fP, \fI1\fP being every trace sent will be analyzed. This is a datadog only feature
|
|
(\fBENDPOINT-TYPE\fP needs to be \fB\fCdatadog\fR)
|
|
.IP \(bu 4
|
|
\fB\fCzipkin_max_backlog_size\fR configures the maximum backlog size for Zipkin HTTP reporter. When batch size reaches this threshold,
|
|
spans from the beginning of the batch will be disposed. Default is 1000 backlog size.
|
|
.IP \(bu 4
|
|
\fB\fCzipkin_max_batch_size\fR configures the maximum batch size for Zipkin HTTP reporter, after which a collect will be triggered. The default batch size is 100 traces.
|
|
.IP \(bu 4
|
|
\fB\fCzipkin_max_batch_interval\fR configures the maximum duration we will buffer traces before emitting them to the collector using Zipkin HTTP reporter.
|
|
The default batch interval is 1 second.
|
|
|
|
|
|
.SH "ZIPKIN"
|
|
.PP
|
|
You can run Zipkin on a Docker host like this:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
docker run \-d \-p 9411:9411 openzipkin/zipkin
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Note the zipkin provider does not support the v1 API since coredns 1.7.1.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Use an alternative Zipkin address:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
trace tracinghost:9253
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
or
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
trace zipkin tracinghost:9253
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
If for some reason you are using an API reverse proxy or something and need to remap
|
|
the standard Zipkin URL you can do something like:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
trace http://tracinghost:9411/zipkin/api/v1/spans
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Using DataDog:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
trace datadog localhost:8126
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Trace one query every 10000 queries, rename the service, and enable same span:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
trace tracinghost:9411 {
|
|
every 10000
|
|
service dnsproxy
|
|
client\_server
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "METADATA"
|
|
.PP
|
|
The trace plugin will publish the following metadata, if the \fImetadata\fP
|
|
plugin is also enabled:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCtrace/traceid\fR: identifier of (zipkin/datadog) trace of processed request
|
|
|
|
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
See the \fIdebug\fP plugin for more information about debug logging.
|
|
|