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 Zipkin format.

Prerequisites

Requirement	Details
Zipkin	Version 2.24 or later
Network	Integration 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

Key	Type	Default	Description
agentHostname	string	"localhost"	Hostname of the Zipkin agent. Use localhost if running on the same node as Ballerina.
agentPort	int	9411	Port on which the Zipkin agent is listening.
samplerType	string	"const"	Sampling strategy: const, probabilistic, or ratelimiting.
samplerParam	decimal	1	For const: 0 (no sampling) or 1 (sample all). For probabilistic: 0.0–1.0. For ratelimiting: positive integer (rate per second).
reporterFlushInterval	int	1000	Interval (ms) at which the client sends spans to the agent.
reporterBufferSize	int	10000	Queue size of the Zipkin client.

Step 4: Send Requests

Run the service and send requests to it to generate trace data. The example requests below call this sample shop service (main.bal), which listens on port 8090:

import ballerina/http;
import ballerinax/zipkin as _;

type Product record {|
    int id;
    string name;
    decimal price;
|};

type OrderRequest record {|
    int productId;
    int quantity;
|};

type Order record {|
    int id;
    *OrderRequest;
|};

map<Product> products = {
    "1": {id: 1, name: "Laptop", price: 1200.00},
    "2": {id: 2, name: "Mouse", price: 25.00},
    "3": {id: 3, name: "Keyboard", price: 45.00}
};
Order[] orders = [];

service /shop on new http:Listener(8090) {

    resource function get products() returns Product[] {
        return products.toArray();
    }

    resource function post product(Product product) returns Product {
        products[product.id.toString()] = product;
        return product;
    }

    resource function post 'order(OrderRequest request) returns Order|http:NotFound {
        if !products.hasKey(request.productId.toString()) {
            return http:NOT_FOUND;
        }
        Order newOrder = {id: orders.length(), ...request};
        orders.push(newOrder);
        return newOrder;
    }

    resource function get 'order/[int id]() returns Order|http:NotFound {
        if id < 0 || id >= orders.length() {
            return http:NOT_FOUND;
        }
        return orders[id];
    }
}

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: Checkpoints recorded while the request is processed, each with the source module and code position (src.module, src.position)

What's next

• Distributed Tracing — How tracing works and how to choose a backend
• Jaeger — Alternative distributed tracing with Jaeger
• Logging — Configure structured logging
• Overview — Full observability architecture