Jaeger

Use Jaeger as an OTLP-compatible backend for KalamDB distributed tracing.

Download Compose Example

Download docker-compose.yml (Jaeger)

Docker Compose Details

The compose file runs:

YAML

1jaeger:2  image: jaegertracing/jaeger:latest3  environment:4    COLLECTOR_OTLP_ENABLED: "true"5  ports:6    - "16686:16686"   # Jaeger UI7    - "4317:4317"     # OTLP gRPC receiver8    - "4318:4318"     # OTLP HTTP receiver

Start it:

BASH

1docker compose up -d

Jaeger UI: http://127.0.0.1:16686

Connect KalamDB → Jaeger

Via gRPC (default, port 4317)

TOML

1[logging.otlp]2enabled = true3endpoint = "http://127.0.0.1:4317"4protocol = "grpc"5service_name = "kalamdb-server"6timeout_ms = 3000

Via HTTP (port 4318)

TOML

1[logging.otlp]2enabled = true3endpoint = "http://127.0.0.1:4318"4protocol = "http"5service_name = "kalamdb-server"6timeout_ms = 3000

The OTLP HTTP exporter appends /v1/traces automatically.

Via Environment Variables

BASH

1export KALAMDB_OTLP_ENABLED=true2export KALAMDB_OTLP_ENDPOINT="http://127.0.0.1:4317"3export KALAMDB_OTLP_PROTOCOL="grpc"4export KALAMDB_OTLP_SERVICE_NAME="kalamdb-server"

What to Expect in Jaeger UI

After starting KalamDB with OTEL enabled:

Open http://127.0.0.1:16686.
Select the service name from the dropdown (default: kalamdb-server).
Click Find Traces.
You should see traces for API requests, SQL execution, and storage operations.

Each trace shows the full request lifecycle — from API entry through SQL parsing, query execution, and storage I/O.

Troubleshooting

Symptom	Cause	Fix
No service in Jaeger dropdown	OTEL not enabled or no traffic yet	Set `enabled = true`, execute some SQL, then refresh
Service appears but no traces	Endpoint mismatch	Verify `protocol` matches the port: `grpc` → 4317, `http` → 4318
Connection refused	Jaeger not running or wrong port	Run `docker compose ps` to verify Jaeger is up
Traces delayed	Batch export timeout	Default timeout is 3000ms; increase `timeout_ms` if network is slow

For all OTEL configuration options and environment variable overrides, see OpenTelemetry (OTEL).