> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/destinations/zipkin.md). # Zipkin Exports traces from a Bindplane pipeline to a [Zipkin](https://zipkin.io/) endpoint over HTTP or HTTPS. Spans are sent to the Zipkin v2 API (`/api/v2/spans` by default). This destination handles traces only. ### Supported Telemetry | Metrics | Logs | Traces | | ------- | ---- | ------ | | | | ✓ | ### Prerequisites You need a reachable Zipkin collector endpoint. The Zipkin server must accept spans on its HTTP API (`POST /api/v2/spans` by default, as defined in the [Zipkin v2 API specification](https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml)). Confirm the hostname, port, and API path the collector listens on, and ensure the collector host can reach it over the network. If the endpoint is served over HTTPS, have the appropriate CA certificate (and client certificate and key, for mutual TLS) available on the collector host. ### Configuration
Bindplane docs - Zipkin - image 1
**Traces** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | --------------- | ----------------------------------------------------- | | Hostname | String | Yes | *(empty)* | Hostname or IP address of the Zipkin server. | | Port | Integer | No | `9411` | Port of the Zipkin server. Valid range is 1 to 65535. | | Path | String | Yes | `/api/v2/spans` | API path to send traces to. | **Advanced** | Parameter | Type | Required | Default | Description | | ----------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------ | | Compression | Enum | No | `gzip` | Compression algorithm to use when sending traces to Zipkin. One of `none` or `gzip`. | **TLS (Advanced)** | Parameter | Type | Required | Default | Description | | --------------------------------- | ------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable TLS | Boolean | No | `false` | Whether or not to use TLS. When enabled, traces are sent over HTTPS. | | Skip TLS Certificate Verification | Boolean | No | `false` | Skip TLS certificate verification. Applies when Enable TLS is true. | | TLS Certificate Authority File | String | No | *(empty)* | Certificate authority file used to validate TLS certificates. Required only if the underlying operating system does not trust Zipkin's certificate. Applies when Enable TLS is true and Skip TLS Certificate Verification is false. | | Mutual TLS | Boolean | No | `false` | Whether or not to use mutual TLS authentication. Applies when Enable TLS is true. | | TLS Client Certificate File | String | No | *(empty)* | A TLS certificate used for client authentication. Applies when Enable TLS and Mutual TLS are both true. | | TLS Client Private Key File | String | No | *(empty)* | A TLS private key used for client authentication. Applies when Enable TLS and Mutual TLS are both true. | **Retry on Failure (Advanced)** | Parameter | Type | Required | Default | Description | | ----------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Enable Retry on Failure | Boolean | No | `true` | Attempt to resend telemetry data that has failed to be transmitted to the destination. | | Initial interval | Integer | No | `5` | Time (in seconds) to wait after the first failure before retrying. Applies when Enable Retry on Failure is true. | | Max interval | Integer | No | `30` | The upper bound (in seconds) on backoff. Applies when Enable Retry on Failure is true. | | Max elapsed time | Integer | No | `300` | The maximum amount of time (in seconds) spent trying to send a batch, used to avoid a never-ending retry loop. Applies when Enable Retry on Failure is true. | **Sending Queue (Advanced)** | Parameter | Type | Required | Default | Description | | ------------------------- | --------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable Sending Queue | Boolean | No | `true` | Buffer telemetry data temporarily before sending to help ensure telemetry data is not lost in case of a temporary network outage. | | Number of Consumers | Integer | No | `10` | Number of consumers that dequeue batches. Applies when Enable Sending Queue is true. | | Queue Size | Integer | No | `5000` | Maximum number of batches kept in memory before dropping. Applies when Enable Sending Queue is true. | | Enable Persistent Queuing | Boolean | No | `true` | Buffer telemetry data to disk before sending to help ensure telemetry data is not lost in case of network outages or collector restarts. Applies when Enable Sending Queue is true. | | Persistent Queue Storage | extension | Yes | File storage | The storage to use for the persistent queue. Applies when Enable Sending Queue and Enable Persistent Queuing are both true. See [persistent queue storage](https://docs.bindplane.com/configuration/bindplane-otel-collector/persistent-queue). | ### Examples #### Export traces to a plaintext Zipkin server Sends traces to a Zipkin collector reachable at `zipkin.example.com:9411` over HTTP, with gzip compression. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: zipkin spec: type: zipkin parameters: - name: hostname value: zipkin.example.com - name: port value: 9411 - name: path value: /api/v2/spans - name: compression value: gzip ``` #### Export traces over TLS Sends traces over HTTPS, validating the server certificate against a provided CA file. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: zipkin spec: type: zipkin parameters: - name: hostname value: zipkin.example.com - name: port value: 9411 - name: path value: /api/v2/spans - name: enable_tls value: true - name: ca_file value: /opt/tls/ca.crt ``` ### Configuration Tips * Keep `gzip` compression enabled to reduce egress bandwidth to the Zipkin server, unless the server cannot decompress request bodies. * Enabling TLS switches the export scheme from `http` to `https`. Set the port to match the TLS listener the Zipkin server exposes. * Leave the sending queue and persistent queuing enabled so spans buffer to disk during network outages or collector restarts instead of being dropped. ### Troubleshooting #### Spans are not reaching Zipkin Symptoms: traces leave the pipeline but do not appear in the Zipkin UI. Solutions: 1. Verify Hostname, Port, and Path point at the Zipkin v2 spans endpoint (`/api/v2/spans` by default). 2. Confirm the collector host can reach the endpoint over the network and that no firewall blocks the port. #### TLS handshake or certificate errors Symptoms: export fails with TLS or x509 certificate errors after Enable TLS is turned on. Solutions: 1. Provide a TLS Certificate Authority File if the operating system does not already trust the server certificate. 2. For mutual TLS, supply both the TLS Client Certificate File and TLS Client Private Key File. As a last resort for testing only, enable Skip TLS Certificate Verification. #### Data is being dropped under load Symptoms: spans are dropped and the collector logs queue-full or send-failure errors. Solutions: 1. Keep Enable Sending Queue and Enable Persistent Queuing on so data buffers during outages. 2. Increase Queue Size or Number of Consumers if the destination cannot keep up with incoming volume. ### Standalone Destination ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: zipkin spec: type: zipkin parameters: - name: hostname value: zipkin.example.com - name: port value: 9411 - name: path value: /api/v2/spans ``` ### Related Resources * [Zipkin Exporter — OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/zipkinexporter/README.md) * [Zipkin v2 API specification](https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/destinations/zipkin.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.