--- title: Telegraf Documentation description: Telegraf plugin for collecting metrics from Zipkin url: https://docs.influxdata.com/telegraf/v1/input-plugins/zipkin/ estimated_tokens: 5466 product: Telegraf version: v1 --- - Telegraf v1.4.0+ # Zipkin Input Plugin This service plugin implements the [Zipkin](https://zipkin.io/) HTTP server to gather trace and timing data needed to troubleshoot latency problems in microservice architectures. This plugin produces high cardinality data, which when not controlled for will cause high load on your database. Please make sure to [filter](/telegraf/v1/configuration/#metric-filtering) the produced metrics or configure your database to avoid cardinality issues! **Introduced in:** Telegraf v1.4.0 **Tags:** cloud **OS support:** all ## 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](/telegraf/v1/configuration/#plugins) for more details. ## Configuration ```toml # 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 ``` #### Related - [Configure plugins](/telegraf/v1/configure_plugins/) - [Zipkin Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/inputs/zipkin/README.md)