.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-TRACE" 7 "March 2021" "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
}

.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)


.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 "SEE ALSO"
.PP
See the \fIdebug\fP plugin for more information about debug logging.