Zipkin

Exports traces from a Bindplane pipeline to a Zipkin 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 Types

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

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.

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.

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.

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

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
• Zipkin v2 API specification