Sending logs to a collector
How to send komrad's log lines, and the records its agents' CLIs export, to an OpenTelemetry collector or a backend that takes OTLP.
Komrad writes its log lines to files in your cache directory. The server writes komrad.log, which also holds the records your agents’ CLIs export, and the panel writes komrad-panel.log. If you keep your logs in a backend like Grafana, Honeycomb or Datadog, komrad can send every line there as well.
Naming a collector#
Set endpoint under [log.export] in your config:
[log.export]
endpoint = "http://localhost:4318"
Komrad speaks OTLP over HTTP with protobuf bodies. Point it at the OpenTelemetry Collector, Grafana Alloy, Vector, or straight at a backend that takes OTLP. A URL with no path gets /v1/logs added, the way OpenTelemetry’s own exporters do it. A URL with a path is used as written, for a backend that takes logs somewhere else.
A backend that wants an API key takes it as a header. Write the key as ${NAME} and komrad reads it from that environment variable, so the key stays out of the file. The database URLs read ${NAME} the same way, as the install guide lists:
[log.export]
endpoint = "https://api.honeycomb.io"
headers = { "x-honeycomb-team" = "${HONEYCOMB_API_KEY}" }
The server and the panel each read the environment they were started with. Export the variable in your shell profile, or in tmux’s global environment, before your first komrad open. A variable you export in a new shell later reaches neither until you run komrad stop and open the panel again. When a header names a variable that isn’t set, komrad refuses the config, as it does any other config error.
What komrad sends#
Each process sends what it writes to its file, at the same level. Komrad’s own lines go out with service.name set to komrad, and process.name tells the server’s lines from the panel’s. A record from an agent’s CLI goes out under the CLI’s own service.name, such as claude-code, with every attribute the CLI gave it. Komrad adds komrad.agent.id, komrad.task.id and komrad.workflow.id to both, so one query finds an agent’s lines and its CLI’s records together.
komrad open and komrad visual keep writing their files and send nothing.
When the collector is down#
Each process holds up to 2048 of its own lines while it waits for the collector, and the server holds up to 2048 more for each agent’s CLI. Past that, komrad drops the oldest and writes a warning to the file saying how many it dropped. Komrad tries a failed batch again for about 15 seconds, then drops it. A failure writes a warning to the file, at most once every 10 minutes.
On the way out, the server gives what it holds 5 seconds to reach the collector and the panel 1 second.
Remote engines#
An engine reads [log.export] from its own config, so its server sends to whatever that config names, such as a collector running beside it. Your panel sends to the collector your own config names, also while it is attached to an engine.