coredns/plugin/trace/README.md

# trace

## Name

*trace* - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.

## Description

With *trace* you enable OpenTracing of how a request flows through CoreDNS. Enable the *debug*
plugin to get logs from the trace plugin.

## Syntax

The simplest form is just:

~~~
trace [ENDPOINT-TYPE] [ENDPOINT]
~~~

* **ENDPOINT-TYPE** is the type of tracing destination. Currently only `zipkin` and `datadog` are supported.
  Defaults to `zipkin`.
* **ENDPOINT** is the tracing destination, and defaults to `localhost:9411`. For Zipkin, if
  **ENDPOINT** does not begin with `http`, then it will be transformed to `http://ENDPOINT/api/v1/spans`.

With this form, all queries will be traced.

Additional features can be enabled with this syntax:

~~~
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
}
~~~

* `every` **AMOUNT** 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.
* `service` **NAME** allows you to specify the service name reported to the tracing server.
  Default is `coredns`.
* `client_server` will enable the `ClientServerSameSpan` OpenTracing feature.
* `datadog_analytics_rate` **RATE** will enable [trace analytics](https://docs.datadoghq.com/tracing/app_analytics) on the traces sent
  from *0* to *1*, *1* being every trace sent will be analyzed. This is a datadog only feature
  (**ENDPOINT-TYPE** needs to be `datadog`)
* `zipkin_max_backlog_size` 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.
* `zipkin_max_batch_size` configures the maximum batch size for Zipkin HTTP reporter, after which a collect will be triggered. The default batch size is 100 traces.
* `zipkin_max_batch_interval` 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.

## Zipkin

You can run Zipkin on a Docker host like this:

```
docker run -d -p 9411:9411 openzipkin/zipkin
```

Note the zipkin provider does not support the v1 API since coredns 1.7.1.

## Examples

Use an alternative Zipkin address:

~~~
trace tracinghost:9253
~~~

or

~~~ corefile
. {
    trace zipkin tracinghost:9253
}
~~~

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:

~~~
trace http://tracinghost:9411/zipkin/api/v1/spans
~~~

Using DataDog:

~~~
trace datadog localhost:8126
~~~

Trace one query every 10000 queries, rename the service, and enable same span:

~~~
trace tracinghost:9411 {
	every 10000
	service dnsproxy
	client_server
}
~~~

## Metadata

The trace plugin will publish the following metadata, if the *metadata*
plugin is also enabled:

* `trace/traceid`: identifier of (zipkin/datadog) trace of processed request

## See Also

See the *debug* plugin for more information about debug logging.