Jaeger

Jaeger is an open-source distributed tracing platform that helps you monitor and troubleshoot request flows across your integration services. WSO2 Integrator provides built-in Jaeger support through the OpenTelemetry protocol.

Prerequisites

Requirement	Details
Jaeger	Version 1.45 or later (all-in-one or production deployment)
Ballerina	Built with --observability-included
Network	Integration must reach the Jaeger OTLP gRPC endpoint (port 4317)

Step 1: Start Jaeger

Run the Jaeger all-in-one image for development and testing:

docker run -d --name jaeger \
  -p 13133:13133 \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/jaeger:latest

Port	Protocol	Purpose
4317	gRPC	OpenTelemetry collector (OTLP)
13133	HTTP	Health check endpoint (/status)
16686	HTTP	Jaeger UI

For production deployments with higher throughput, use a dedicated Jaeger collector deployment with a persistent storage backend.

Step 2: Configure Ballerina for Jaeger

Import the Jaeger extension

Navigate to your entry point file in the file explorer (typically main.bal in the project root) and add the following import statement at the top:

File path: main.bal (or your entry point)

import ballerinax/jaeger as _;

This enables Jaeger tracing capabilities in your Ballerina application.

Enable tracing in configuration

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

[build-options]
observabilityIncluded = true

Open the Config.toml file in your project root and add the following sections:

File path: Config.toml

[ballerina.observe]
tracingEnabled = true
tracingProvider = "jaeger"

[ballerinax.jaeger]
agentHostname = "localhost"
agentPort = 4317
samplerType = "const"
samplerParam = 1.0
reporterFlushInterval = 2000
reporterBufferSize = 1000

If Config.toml doesn't exist, create it in your project root directory.

Configuration options

Key	Type	Default	Description
agentHostname	string	"localhost"	Jaeger agent hostname
agentPort	int	55680	Jaeger OpenTelemetry receiver port (gRPC). Set it to 4317 for current Jaeger versions.
samplerType	string	"const"	Sampling strategy: const, probabilistic, ratelimiting
samplerParam	decimal	1	Sampler parameter (1.0 = sample all)
reporterFlushInterval	int	1000	Flush interval in milliseconds
reporterBufferSize	int	10000	Maximum spans buffered

Sampling strategies

Strategy	Parameter	Description
const	1.0 (on) or 0.0 (off)	Sample all or none
probabilistic	0.0 to 1.0	Probability of sampling each trace
ratelimiting	traces/second	Fixed rate of traces per second

For production, use probabilistic or ratelimiting to reduce overhead.

Edit Config.toml to modify the sampler configuration:

File path: Config.toml

[ballerinax.jaeger]
samplerType = "probabilistic"
samplerParam = 0.1   # Sample 10% of traces

This configuration samples 10% of traces in production to reduce overhead while maintaining visibility into your system.

Step 3: View Traces

Run the service and Open the Jaeger UI at http://localhost:16686:

1. Select your service from the Service dropdown.
2. Click Find Traces.
3. Click a trace to view the span details.

What's next

• Distributed Tracing — How tracing works and how to choose a backend
• Zipkin — Alternative distributed tracing with Zipkin
• Metrics — Collect and monitor metrics alongside traces
• Overview — Full observability architecture