Kjell Tore Guttormsen
169d5a45ca
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.
76 lines
2.9 KiB
Markdown
76 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|