Logging & Traceability

This page is the canonical guide for KalamDB runtime logging, JSON log output, Docker log collection, and distributed tracing.

Use it when you want to:

• switch the backend to JSON logs
• configure logging from server.toml
• run with logging overrides from environment variables
• ship logs through Docker or Dokploy
• enable OTLP tracing for Jaeger or another collector

What KalamDB Supports Today

KalamDB currently supports two practical runtime log output modes:

• compact: human-readable text logs written to server.log
• json: JSON Lines logs written to server.jsonl

When log_to_console = true, the same events are also emitted to container stdout or your local terminal.

For traceability beyond logs, KalamDB also supports OTLP trace export under [logging.otlp].

JSON Logging Syntax

KalamDB JSON logs are emitted as JSON Lines.

• Each log event is one JSON object
• Each object is written on its own line
• The log file is server.jsonl
• This format is the one read by system.server_logs

Example real log line:

1{"timestamp":"2026-05-13T04:39:33.428337Z","level":"INFO","message":"KalamDB Server v0.5.0-beta.1 | Build: 2026-05-13 03:42:16 UTC","log.target":"kalamdb_server","log.module_path":"kalamdb_server","log.file":"backend/src/main.rs","log.line":340,"target":"kalamdb_server","threadName":"main"}

Common fields you should expect:

Depending on the event and span context, extra tracing metadata can also appear.

Important Limitation: No Custom JSON Schema Yet

KalamDB does not currently support custom JSON log templates.

That means:

• you can choose compact or json
• you can choose the log level and destination
• you can export OTLP traces
• you cannot rename JSON keys or define a custom JSON logging pattern yet

If you need a different schema for downstream systems, transform the JSON lines in your log pipeline after KalamDB emits them.

Configure Logging In server.toml

Use this when you want structured logs on disk and on stdout:

1[logging]2level = "info"3format = "json"4logs_path = "./logs"5log_to_console = true6slow_query_threshold_ms = 12007 8[logging.targets]9datafusion = "warn"10arrow = "warn"11parquet = "warn"

With that config:

• file logs go to ./logs/server.jsonl
• console logs also use the same event stream
• system.server_logs can read the JSON log file

If you use format = "compact", the server writes server.log instead.

Configure Logging With Environment Variables

Environment variables override server.toml at startup.

JSON Logging From Env

1KALAMDB_LOG_LEVEL=info \2KALAMDB_LOG_FORMAT=json \3KALAMDB_LOGS_DIR=./logs \4KALAMDB_LOG_TO_CONSOLE=true \5cargo run --manifest-path backend/Cargo.toml --bin kalamdb-server

Logging Environment Variables

Current limitation:

• per-target overrides under [logging.targets] are currently configured in server.toml, not through dedicated environment variables

Docker Logging

For Docker deployments, the simplest pattern is:

1. emit JSON logs to stdout
2. keep log_to_console = true
3. optionally persist the same logs under /data/logs

The single-node Docker config shipped with KalamDB already does this:

1[logging]2level = "info"3logs_path = "/data/logs"4log_to_console = true5format = "json"

docker run Example

1docker run --rm \2  -p 8080:8080 \3  -v "$PWD/data:/data" \4  -e KALAMDB_LOG_LEVEL=info \5  -e KALAMDB_LOG_FORMAT=json \6  -e KALAMDB_LOG_TO_CONSOLE=true \7  -e KALAMDB_LOGS_DIR=/data/logs \8  jamals86/kalamdb:latest

Docker Compose Example

1services:2  kalamdb:3    image: jamals86/kalamdb:latest4    ports:5      - "8080:8080"6    volumes:7      - ./data:/data8    environment:9      KALAMDB_LOG_LEVEL: info10      KALAMDB_LOG_FORMAT: json11      KALAMDB_LOG_TO_CONSOLE: "true"12      KALAMDB_LOGS_DIR: /data/logs

Dokploy Compatibility

Dokploy runtime logs are compatible with KalamDB JSON logs as raw log lines.

What this means in practice:

• if KalamDB writes JSON logs to stdout, Dokploy can display them
• each KalamDB log event appears as one JSON line
• this works best when KALAMDB_LOG_FORMAT=json and KALAMDB_LOG_TO_CONSOLE=true

What you should not assume today:

• Dokploy does not appear to have a documented KalamDB-specific schema for these fields
• I did not find evidence that Dokploy automatically maps fields like threadName, target, or log.line into structured columns for KalamDB logs

The safe assumption is:

• Dokploy will show the JSON lines correctly
• any deeper structured parsing depends on Dokploy-side features or downstream tooling, not on a KalamDB-specific format contract

Dokploy’s log UI is built around Docker log streaming, so stdout compatibility matters more than matching a custom syntax.

OTLP Tracing

For distributed tracing, configure [logging.otlp] in addition to normal logs.

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

Environment equivalent:

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"5export KALAMDB_OTLP_TIMEOUT_MS=3000

Use OTLP when you want:

• trace spans in Jaeger, Tempo, or an OpenTelemetry Collector
• request correlation across services
• timing and span visibility beyond plain log lines

Use JSON logging when you want:

• structured application logs
• Docker or Dokploy log shipping
• queryable system.server_logs entries

Most production setups use both.

Query Logs From SQL

system.server_logs reads the JSON log file generated by the backend.

Example:

1SELECT timestamp, level, target, message2FROM system.server_logs3ORDER BY timestamp DESC4LIMIT 50;

This view only works reliably when the backend log format is json.

Recommended Production Setup

For most production deployments:

1. set format = "json"
2. keep log_to_console = true
3. write logs under a persistent directory such as /data/logs
4. enable OTLP if you need request tracing in Jaeger or Tempo
5. use Dokploy or Docker for raw log streaming, and a collector for deeper analytics if needed

Related

• OpenTelemetry (OTEL)
• Advanced Configuration
• Jaeger