OpenTelemetry (OTEL)

This page shows how to enable distributed tracing for KalamDB with OTLP-compatible backends such as Jaeger.

Quick Start (Jaeger)

Download a ready-to-run compose file:

• Download docker-compose.yml (Jaeger)

Run it from the folder where you downloaded it:

cd /path/to/downloaded/file
docker compose up -d

Jaeger UI: http://127.0.0.1:16686

This example mirrors the Jaeger section in KalamDB/docker/utils/docker-compose.yml.

Configure server.toml

KalamDB OTEL settings live under [logging.otlp]:

[logging.otlp]
enabled = true
endpoint = "http://127.0.0.1:4317"
protocol = "grpc"
service_name = "kalamdb-server"
timeout_ms = 3000

Environment Variable Overrides

Environment variables override server.toml values at startup.

export KALAMDB_OTLP_ENABLED=true
export KALAMDB_OTLP_ENDPOINT="http://127.0.0.1:4317"
export KALAMDB_OTLP_PROTOCOL="grpc"
export KALAMDB_OTLP_SERVICE_NAME="kalamdb-prod"
export KALAMDB_OTLP_TIMEOUT_MS=5000

KALAMDB_OTLP_ENABLED accepts "true", "1", or "yes" (case-insensitive).

Full OTEL Configuration Matrix

Protocol behavior:

• grpc expects endpoint like http://127.0.0.1:4317 (Jaeger port 4317)
• http expects collector HTTP endpoint like http://127.0.0.1:4318; the exporter appends /v1/traces automatically

Validation Checklist

1. Start Jaeger/collector
2. Start KalamDB with OTEL enabled
3. Execute API requests or SQL calls
4. Open Jaeger UI and confirm service name appears

Configuration Precedence

KalamDB applies settings in this order:

1. server.toml
2. KALAMDB_* environment overrides

If both are set, environment variables win.

Supported Backends

Any OTLP-compatible collector works with KalamDB, including:

• Jaeger (built-in compose example)
• Grafana Tempo
• Honeycomb
• Datadog (OTLP ingest)
• OpenTelemetry Collector (forwarding to any backend)

Related

• Jaeger Integration
• Advanced Configuration