# Zipkin Input Plugin This service plugin implements the [Zipkin][zipkin] HTTP server to gather trace and timing data needed to troubleshoot latency problems in microservice architectures. > [!CRITICAL] > This plugin produces high cardinality data, which when not controlled for will > cause high load on your database. Please make sure to [filter][filtering] the > produced metrics or configure your database to avoid cardinality issues! ⭐ Telegraf v1.4.0 🏷️ cloud 💻 all [zipkin]: https://zipkin.io/ [filtering]: /docs/CONFIGURATION.md#metric-filtering ## Service Input This plugin is a service input. Normal plugins gather metrics determined by the interval setting. Service plugins start a service to listen and wait for metrics or events to occur. Service plugins have two key differences from normal plugins: 1. The global or plugin specific `interval` setting may not apply 2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce output for this plugin ## Global configuration options Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md][CONFIGURATION.md] for more details. [CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins ## Configuration ```toml @sample.conf # Gather data from a Zipkin server including trace and timing data [[inputs.zipkin]] ## URL path for span data # path = "/api/v1/spans" ## Port on which Telegraf listens # port = 9411 ## Maximum duration before timing out read of the request # read_timeout = "10s" ## Maximum duration before timing out write of the response # write_timeout = "10s" ``` The plugin accepts spans in `JSON` or `thrift` if the `Content-Type` is `application/json` or `application/x-thrift`, respectively. If `Content-Type` is not set, then the plugin assumes it is `JSON` format. ## Metrics This plugin uses Annotations tags and fields to track data from spans - `TRACE` is a set of spans that share a single root span. Traces are built by collecting all Spans that share a traceId. - `SPAN` is a set of Annotations and BinaryAnnotations that correspond to a particular RPC. - `Annotations` create a metric for each annotation & binary annotation of a span. This records an occurrence in time at the beginning and end of each request. Annotations may have the following values: - `CS` (client start) marks the beginning of the span, a request is made. - `SR` (server receive) marks the point in time the server receives the request and starts processing it. Network latency & clock jitters distinguish this from `CS`. - `SS` (server send) marks the point in time the server is finished processing and sends a request back to client. The difference to `SR` denotes the amount of time it took to process the request. - `CR` (client receive) marks the end of the span, with the client receiving the response from server. RPC is considered complete with this annotation. All metrics contain the following fields: - `duration_ns` the time in nanoseconds between the end and beginning of a span ### Tags - `id` the 64-bit ID of the span. - `parent_id` an ID associated with a particular child span. If there is no child span, `parent_id` is equal to `id` - `trace_id` the 64-bit or 128-bit ID of a particular trace. Every span in a trace uses this ID. - `name` defines a span #### Annotations have these additional tags - `service_name` defines a service - `annotation` the value of an annotation - `endpoint_host` listening IPv4 address and, if present, port #### Binary Annotations have these additional tag - `service_name` defines a service - `annotation` the value of an annotation - `endpoint_host` listening IPv4 address and, if present, port - `annotation_key` label describing the annotation ## Example Output The Zipkin data ```json [ { "trace_id": 2505404965370368069, "name": "Child", "id": 8090652509916334619, "parent_id": 22964302721410078, "annotations": [], "binary_annotations": [ { "key": "lc", "value": "dHJpdmlhbA==", "annotation_type": "STRING", "host": { "ipv4": 2130706433, "port": 0, "service_name": "trivial" } } ], "timestamp": 1498688360851331, "duration": 53106 }, { "trace_id": 2505404965370368069, "name": "Child", "id": 103618986556047333, "parent_id": 22964302721410078, "annotations": [], "binary_annotations": [ { "key": "lc", "value": "dHJpdmlhbA==", "annotation_type": "STRING", "host": { "ipv4": 2130706433, "port": 0, "service_name": "trivial" } } ], "timestamp": 1498688360904552, "duration": 50410 }, { "trace_id": 2505404965370368069, "name": "Parent", "id": 22964302721410078, "annotations": [ { "timestamp": 1498688360851325, "value": "Starting child #0", "host": { "ipv4": 2130706433, "port": 0, "service_name": "trivial" } }, { "timestamp": 1498688360904545, "value": "Starting child #1", "host": { "ipv4": 2130706433, "port": 0, "service_name": "trivial" } }, { "timestamp": 1498688360954992, "value": "A Log", "host": { "ipv4": 2130706433, "port": 0, "service_name": "trivial" } } ], "binary_annotations": [ { "key": "lc", "value": "dHJpdmlhbA==", "annotation_type": "STRING", "host": { "ipv4": 2130706433, "port": 0, "service_name": "trivial" } } ], "timestamp": 1498688360851318, "duration": 103680 } ] ``` generated the following metrics ```text zipkin,id=7047c59776af8a1b,name=child,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=53106000i 1498688360851331000 zipkin,annotation=trivial,annotation_key=lc,endpoint_host=127.0.0.1,id=7047c59776af8a1b,name=child,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=53106000i 1498688360851331000 zipkin,id=17020eb55a8bfe5,name=child,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=50410000i 1498688360904552000 zipkin,annotation=trivial,annotation_key=lc,endpoint_host=127.0.0.1,id=17020eb55a8bfe5,name=child,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=50410000i 1498688360904552000 zipkin,id=5195e96239641e,name=parent,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=103680000i 1498688360851318000 zipkin,annotation=Starting\ child\ #0,endpoint_host=127.0.0.1,id=5195e96239641e,name=parent,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=103680000i 1498688360851318000 zipkin,annotation=Starting\ child\ #1,endpoint_host=127.0.0.1,id=5195e96239641e,name=parent,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=103680000i 1498688360851318000 zipkin,annotation=A\ Log,endpoint_host=127.0.0.1,id=5195e96239641e,name=parent,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=103680000i 1498688360851318000 zipkin,annotation=trivial,annotation_key=lc,endpoint_host=127.0.0.1,id=5195e96239641e,name=parent,parent_id=5195e96239641e,service_name=trivial,trace_id=22c4fc8ab3669045 duration_ns=103680000i 1498688360851318000 ```