open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/voyage/examples/observability/README.md
Kjell Tore Guttormsen 169d5a45ca fix(voyage): correct env-var names in observability/README.md 
Step 14 follow-up — VOYAGE_OTEL_ENDPOINT (not VOYAGE_OTLP_ENDPOINT) per
hooks/scripts/otel-export.mjs and lib/exporters/endpoint-validator.mjs.
Adds VOYAGE_OTEL_ALLOW_PRIVATE=1 for localhost since 127.0.0.1 is
loopback and rejected by default.
2026-05-09 09:50:48 +02:00

2.9 KiB
Raw Blame History

Voyage observability — local Docker Compose stack

A version-pinned local-development stack for inspecting Voyage v4.1 metrics emitted by hooks/scripts/otel-export.mjs. Two complementary paths:

Mode env var Pull/push Container that scrapes
Prometheus textfile VOYAGE_EXPORT_MODE=textfile voyage writes voyage.prom to ./voyage-textfile/, node-exporter scrapes node-exporter
OTLP/HTTP VOYAGE_EXPORT_MODE=otlp voyage POSTs to http://localhost:4318/v1/metrics otel-collector (re-exposed as Prometheus on :8889)

Both modes feed Prometheus → Grafana.

Quickstart

cd examples/observability
mkdir -p voyage-textfile
docker compose up -d

Endpoints (all bound to localhost):

Service URL
Prometheus UI http://localhost:9090
Grafana UI http://localhost:3000 (anonymous Viewer enabled; admin/admin)
OTLP/HTTP receiver http://localhost:4318/v1/metrics
Node Exporter http://localhost:9100/metrics
OTel Collector Prometheus exporter http://localhost:8889/metrics

Stop with docker compose down. Add -v to wipe Prometheus + Grafana volumes.

Activating Voyage export

In another terminal, set one of the env vars before invoking a Voyage command:

# Path A — textfile mode
export VOYAGE_EXPORT_MODE=textfile
export VOYAGE_TEXTFILE_DIR="$(pwd)/voyage-textfile"

# Path B — OTLP mode
export VOYAGE_EXPORT_MODE=otlp
export VOYAGE_OTEL_ENDPOINT=http://localhost:4318/v1/metrics
export VOYAGE_OTEL_ALLOW_PRIVATE=1   # required: localhost is loopback (RFC1122)

The Stop hook (wired in hooks/hooks.json) will run hooks/scripts/otel-export.mjs automatically at session-end.

See docs/observability.md for the full env-var matrix and security notes.

Pinned versions (per research/01)

Component Image Pinned to
Prometheus prom/prometheus v3.0.1
Node Exporter prom/node-exporter v1.10.2
Grafana grafana/grafana 11.4.0
OTel Collector (contrib) otel/opentelemetry-collector-contrib 0.115.0

These are reference versions for the v4.1 release window; bump only after re-testing the full smoke flow.

Limitations

  • Stop-hook export runs at normal session end. If Claude Code exits via crash or hard kill, the final metrics for that session are not flushed. Use --resume on next start to recover plan/progress state; metrics for the unflushed session will be missing from Prometheus.
  • The VOYAGE_OTEL_ALLOW_PRIVATE=1 escape hatch enables sending to RFC1918 addresses (home-lab use). It is off by default so accidental internal-network exfiltration is blocked. See docs/observability.md.
  • This stack is for local development. Do not expose ports :9090 / :3000 / :4318 outside loopback — Grafana ships with anonymous viewer access enabled and admin/admin credentials.