Observe tracing using Zipkin

Users can configure Ballerina to support distributed tracing with Zipkin, which is one of the open-source and distributed tracing platforms that helps troubleshoot latency problems in service architectures. Ballerina provides tracing data in OpenTelemetry format.

The sample shop service will be used in this guide. Follow the steps given below to observe Ballerina tracing in Zipkin.

Step 1 - Set up Zipkin

You can configure Ballerina to support distributed tracing with Zipkin. This section focuses on configuring Zipkin with Docker as a quick installation.

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

Install Zipkin via Docker and start the Docker container by executing the command below.

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

Step 2 - Import Ballerina Zipkin extension

To include the Zipkin extension into the executable, the ballerinax/zipkin module needs to be imported into your Ballerina project main.bal file.

Copy
import ballerinax/zipkin as _;

Zipkin extension has a Zipkin Span Exporter which will push tracing data as batches to the Zipkin server endpoint (default - http://localhost:9411) in Zipkin format.

Step 3 - Configure Ballerina runtime configurations

Tracing can be enabled in your Ballerina project using configurations similar to the following in your Config.toml file.

Copy
[ballerina.observe]
tracingEnabled=true
tracingProvider="zipkin"

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

The table below provides the descriptions of each configuration option and possible values that can be assigned.

Configuration keyDescriptionDefault valuePossible values
ballerinax.zipkin. agentHostnameHostname of the Zipkin agentlocalhostIP or hostname of the Zipkin agent. If it is running on the same node as Ballerina, it can be localhost.
ballerinax.zipkin. agentPortPort of the Zipkin agent4317The port on which the Zipkin agent is listening.
ballerinax.zipkin. samplerTypeType of the sampling methods used in the Zipkin tracer.constconst, probabilistic, or ratelimiting.
ballerinax.zipkin. samplerParamIt is a floating value. Based on the sampler type, the effect of the sampler param varies1.0For const 0 (no sampling) or 1 (sample all spans), for probabilistic 0.0 to 1.0, for ratelimiting any positive integer (rate per second).
ballerinax.zipkin. reporterFlushIntervalThe Zipkin client will be sending the spans to the agent at this interval.2000Any positive integer value.
ballerinax.zipkin. reporterBufferSizeQueue size of the Zipkin client.2000Any positive integer value.

Step 4 - Run the Ballerina service

When Ballerina observability is enabled, the Ballerina runtime collects tracing data and traces will be published to Zipkin.

Run the following command to start the Ballerina service.

Copy
$ bal run

Compiling source

Running executable

ballerina: started publishing traces to Zipkin on http://localhost:9411

Step 5 - Send requests

Send requests to http://localhost:8090/shop/products.

Example cURL commands:

Copy
$ curl -X GET http://localhost:8090/shop/products

Copy
$ curl -X POST http://localhost:8090/shop/product \
-H "Content-Type: application/json" \
-d '{
    "id": 4, 
    "name": "Laptop Charger", 
    "price": 50.00
}'

Copy
$ curl -X POST http://localhost:8090/shop/order \
-H "Content-Type: application/json" \
-d '{
    "productId": 1, 
    "quantity": 1
}'

Copy
$ curl -X GET http://localhost:8090/shop/order/0

Step 6 - View distributed tracing on the Zipkin server

Go to http://localhost:9411 and load the web UI of Zipkin to make sure it is functioning properly. You can select the service for which you need tracing information find traces.

The image below is the sample tracing information you can see in Zipkin.

Zipkin tracing Dashboard