Skip to main content

Zipkin

Zipkin is an open-source distributed tracing platform that helps troubleshoot latency problems in service architectures. WSO2 Integrator provides built-in Zipkin support, publishing tracing data in OpenTelemetry format.

Prerequisites​

RequirementDetails
ZipkinVersion 2.24 or later
NetworkIntegration must reach the Zipkin agent endpoint

Step 1: Start Zipkin​

Run Zipkin using Docker:

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

The Zipkin UI is available at http://localhost:9411.

tip

There are many possible ways to deploy Zipkin. For more information, see Zipkin Quickstart.

Step 2: Import the Zipkin Extension​

To include the Zipkin extension in the executable, import the ballerinax/zipkin module in your project's main.bal file.

  1. In the Explorer pane, navigate to your project root and open main.bal.
  2. Add the following import at the top of the file:
import ballerinax/zipkin as _;

The Zipkin extension includes a Zipkin Span Exporter that pushes tracing data as batches to the Zipkin server endpoint (default: http://localhost:9411) in Zipkin format.

Step 3: Configure Ballerina for Zipkin​

Open Ballerina.toml by navigating file explorer and edit as follows

[build-options]
observabilityIncluded = true

Configure Config.toml:

  1. In the Explorer pane, navigate to your project root and open Config.toml. If the file does not exist, create it at the project root.
  2. Add or update the following configuration:
[ballerina.observe]
tracingEnabled = true
tracingProvider = "zipkin"

[ballerinax.zipkin]
agentHostname = "localhost"
agentPort = 9411
samplerType = "const"
samplerParam = 1.0
reporterFlushInterval = 1000
reporterBufferSize = 10000

Configuration options​

KeyTypeDefaultDescription
agentHostnamestring"localhost"Hostname of the Zipkin agent. Use localhost if running on the same node as Ballerina.
agentPortint9411Port on which the Zipkin agent is listening.
samplerTypestring"const"Sampling strategy: const, probabilistic, or ratelimiting.
samplerParamfloat1.0For const: 0 (no sampling) or 1 (sample all). For probabilistic: 0.0–1.0. For ratelimiting: positive integer (rate per second).
reporterFlushIntervalint1000Interval (ms) at which the client sends spans to the agent.
reporterBufferSizeint10000Queue size of the Zipkin client.

Step 4: Send Requests​

Run the service and send requests to your service to generate trace data. Example cURL commands:

curl -X GET http://localhost:8090/shop/products
curl -X POST http://localhost:8090/shop/product \
  -H "Content-Type: application/json" \
  -d '{"id": 4, "name": "Laptop Charger", "price": 50.00}'
curl -X POST http://localhost:8090/shop/order \
  -H "Content-Type: application/json" \
  -d '{"productId": 1, "quantity": 1}'

Step 5: View Traces​

  1. Open the Zipkin UI at http://localhost:9411.
  2. Select the service for which you need tracing information.
  3. Click Run Query to find recent traces.
  4. Click a trace to view the span timeline.

Trace visualization​

Zipkin displays traces as a timeline of spans:

  • Service Name: The Ballerina service that generated the span
  • Span Name: The HTTP method and resource path
  • Duration: Time taken for the operation
  • Annotations: Client send/receive, server send/receive timestamps

What's next​

  • Jaeger — Alternative distributed tracing with Jaeger
  • Logging — Configure structured logging
  • Overview — Full observability architecture