Setup Local Stack

gcx on the local oddyssey stack

The local stack is a single otel-lgtm container: Grafana, OTLP (gRPC and HTTP), and four datasources — Tempo, Prometheus, Loki, Pyroscope — behind the Grafana datasource proxy. The host ports come from the global configuration (defaults 3000 / 4317 / 4318): read the effective URLs from odd_stack_up's result (grafana_url, otlp_endpoint) or odd_config_get — never assume the defaults, and point an application's OTEL_EXPORTER_OTLP_ENDPOINT at those values, never at a hardcoded port. Grafana serves its API anonymously here: no credentials are required, and the admin/admin entries in the context below are accepted but inert (kept only so the template also fits an auth-enabled Grafana).

The stack holds no volume by design — a reset wipes everything, and the observation report is the only durable artifact. To configure the container, pass env to odd_stack_up/odd_stack_reset; env (like the embedded defaults, e.g. delta-metric ingestion) applies at container creation only, so a container predating the current oddyssey version keeps its old definition until its next reset. An applied env is persisted into the global configuration's stack_config.local and reapplied on every later recreation, so it survives resets without being repeated — except credential-named variables (headers, tokens, ...), which are applied but never persisted (the result's env_not_persisted names them): pass those again on every recreation. The catalog of the image's variables — per-component debug logs, backend tuning, OTLP forwarding to a remote backend, OBI, GF_* — is [references/otel-lgtm-env.md](references/otel-lgtm-env.md), aligned on the pinned image tag. For anything env cannot express (volumes, networks), the supported escape hatch is a manual docker run reusing the same name and ports — status/up/down keep working against it, but a reset recreates the container from the embedded definition plus env: hand-mounted volumes and networks do not survive it. Bring it up with the oddyssey MCP tools (odd_stack_status, odd_stack_up) before configuring anything here.

Configure an isolated context

Never edit the user's own gcx configuration. Point GCX_CONFIG at a stable per-session path — stable so the file is written once and reused while the configured ports stay the same, isolated so the user's contexts stay untouched. Read the effective grafana_url from odd_config_get (or odd_stack_up's result) before writing the file, and put that URL — not the default — on the server: line:

export GCX_CONFIG="${TMPDIR:-/tmp}/oddyssey/gcx-local.yaml"
mkdir -p "$(dirname "$GCX_CONFIG")"
cat > "$GCX_CONFIG"  --help` over this table.

gcx is the stack's mandatory **query** CLI — explore and measure
through it. Recording raw datasource-proxy HTTP in a report
(`/api/datasources/proxy/uid//...` URLs) is
the right form for **replayable evidence**: a proxy URL replays
verbatim with curl alone, on a machine with no gcx context. Query with
gcx; record a proof query in whichever form the verify run can replay
exactly — both are contract-conform, and the report says which was
used.

Discover before you query: `gcx metrics labels` / `gcx metrics metadata`,
`gcx traces labels`, `gcx logs labels`, `gcx profiles list-profile-types`.
`gcx metrics series` and `gcx logs series` are NOT discovery commands:
bare, they error — both require at least one selector (e.g. `gcx metrics
series 'target_info'`). Every service names its own telemetry — never
assume a metric, label, or stream exists.

## This stack is push-based

Apps push OTLP into the stack; Prometheus scrapes nothing here. So
`up{job=""}` is **empty for every service, healthy or not** — it
proves nothing, and any workflow that gates on a scrape-style liveness
check must skip it. Prove a service is present with its own data instead: a
Tempo search for `{resource.service.name=""}`, a Prometheus series
carrying it (`target_info{service_name=""}` or whatever discovery
returns), a Loki stream selecting it.

Also absent from this stack: `gcx assistant` and investigations — Grafana
Cloud features the local anonymous instance does not serve.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [using-system](https://github.com/using-system)
- **Source:** [using-system/oddyssey](https://github.com/using-system/oddyssey)
- **License:** MIT
- **Homepage:** https://github.com/using-system/oddyssey#readme

Install and usage instructions live in the source repository linked above.