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

.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
ENDPOINT 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
}

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


.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

.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:8125

.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