Skip to content

Getting started

codexlb2otel must be able to read a codex-lb conversation-archive directory and write its checkpoint. Start with output disabled or pointed at test destinations; archive records can contain complete prompts, messages, tool arguments, and command output.

Build from source

The Go version is declared in go.mod:

git clone https://github.com/rknightion/codexlb2otel.git
cd codexlb2otel
go build -o bin/codexlb2otel ./cmd/codexlb2otel

Copy the example configuration and change the archive paths:

cp config.example.yaml config.yaml

For the first run, disable loki, otlp.metrics, otlp.traces, and agento11y. The health listener remains available on loopback:

./bin/codexlb2otel -config config.yaml
curl --fail http://127.0.0.1:9464/healthz

The binary also provides its own container health probe:

./bin/codexlb2otel -config config.yaml -healthcheck

Run the published container

Tagged releases and the rolling main image are published to GHCR:

docker pull ghcr.io/rknightion/codexlb2otel:main

The image is distroless and runs as a non-root user. Mount:

  • the archive directory at the path configured by archive.dir;
  • a readable configuration file at /etc/codexlb2otel/config.yaml; and
  • a writable persistent directory containing archive.checkpoint.

The repository's docker-compose.yml shows the complete mount and health-check shape. Its host paths and numeric user are deployment examples, not portable defaults: choose paths and a UID that can read your own archive without loosening the archive's permissions.

Enable one sink at a time

  1. Enable OTLP metrics and confirm series arrive.
  2. Enable traces if the additional volume is useful.
  3. Review Security, choose loki.record_types, then enable Loki.
  4. Enable Agent Observability only with a token carrying the required generation-write scope.

See Configuration for secret indirection and Troubleshooting for empty-output and delivery failures.