From 00292762e9f63c34bf9b5ebc125bf7e4a59d9ce4 Mon Sep 17 00:00:00 2001 From: using-system Date: Sun, 23 Aug 2026 21:55:24 +0200 Subject: [PATCH] docs(skill): align setup-local-stack with the verified gcx surface Every claim of issue #37 was re-verified live against gcx v1.0.0 and Grafana 13.1.3. The reported command failures do not reproduce on this version (list-profile-types and -d/--datasource work on all four groups; metadata is a listed subcommand) - the report reflects an older gcx surface, which itself proves the issue's meta-point: the surface moves. What was actually wrong and is fixed here: - the discovery line suggested bare `gcx metrics series`, which errors ("At least one selector is required" - confirmed); it and `gcx logs series` are now documented as requiring a selector, with `labels` / `metadata` as the discovery commands - the skill implied admin/admin credentials are needed; Grafana serves the local stack anonymously (verified: a credential-less context is fully functional), so the entries are documented as inert - the verified gcx/Grafana versions are now pinned next to the command table, with --help as the authority on drift Refs #37 Co-Authored-By: Claude Fable 5 --- .apm/skills/setup-local-stack/SKILL.md | 23 +++++++++++++------ .../skills/setup-local-stack/SKILL.md | 23 +++++++++++++------ 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/.apm/skills/setup-local-stack/SKILL.md b/.apm/skills/setup-local-stack/SKILL.md index 0dab279..036dffa 100644 --- a/.apm/skills/setup-local-stack/SKILL.md +++ b/.apm/skills/setup-local-stack/SKILL.md @@ -5,10 +5,12 @@ description: Configure gcx against the local oddyssey Grafana stack and query it # gcx on the local oddyssey stack -The local stack is a single otel-lgtm container: Grafana on `:3000` with -`admin`/`admin`, OTLP on `:4317` (gRPC) and `:4318` (HTTP), and four -datasources — Tempo, Prometheus, Loki, Pyroscope — behind the Grafana -datasource proxy. Bring it up with the oddyssey MCP tools (`odd_stack_status`, +The local stack is a single otel-lgtm container: Grafana on `:3000`, OTLP +on `:4317` (gRPC) and `:4318` (HTTP), and four datasources — Tempo, +Prometheus, Loki, Pyroscope — behind the Grafana datasource proxy. 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). Bring it up with the oddyssey MCP tools (`odd_stack_status`, `odd_stack_up`) before configuring anything here. ## Configure an isolated context @@ -56,9 +58,16 @@ the whole setup. | Logs | Loki | `loki` | `gcx logs labels/series/query` | LogQL | | Profiles | Pyroscope | `pyroscope` | `gcx profiles list-profile-types/labels/query -d pyroscope` | profile selector | -Discover before you query: `gcx metrics series` / `metadata`, `gcx traces -labels`, `gcx logs labels`, `gcx profiles list-profile-types`. Every service -names its own telemetry — never assume a metric, label, or stream exists. +This table is verified against gcx v1.0.0 and Grafana 13.1.3; the gcx +command surface moves between versions, so when a documented command +errors, trust `gcx --help` over this table. + +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 diff --git a/marketplace/oddyssey/skills/setup-local-stack/SKILL.md b/marketplace/oddyssey/skills/setup-local-stack/SKILL.md index 0dab279..036dffa 100644 --- a/marketplace/oddyssey/skills/setup-local-stack/SKILL.md +++ b/marketplace/oddyssey/skills/setup-local-stack/SKILL.md @@ -5,10 +5,12 @@ description: Configure gcx against the local oddyssey Grafana stack and query it # gcx on the local oddyssey stack -The local stack is a single otel-lgtm container: Grafana on `:3000` with -`admin`/`admin`, OTLP on `:4317` (gRPC) and `:4318` (HTTP), and four -datasources — Tempo, Prometheus, Loki, Pyroscope — behind the Grafana -datasource proxy. Bring it up with the oddyssey MCP tools (`odd_stack_status`, +The local stack is a single otel-lgtm container: Grafana on `:3000`, OTLP +on `:4317` (gRPC) and `:4318` (HTTP), and four datasources — Tempo, +Prometheus, Loki, Pyroscope — behind the Grafana datasource proxy. 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). Bring it up with the oddyssey MCP tools (`odd_stack_status`, `odd_stack_up`) before configuring anything here. ## Configure an isolated context @@ -56,9 +58,16 @@ the whole setup. | Logs | Loki | `loki` | `gcx logs labels/series/query` | LogQL | | Profiles | Pyroscope | `pyroscope` | `gcx profiles list-profile-types/labels/query -d pyroscope` | profile selector | -Discover before you query: `gcx metrics series` / `metadata`, `gcx traces -labels`, `gcx logs labels`, `gcx profiles list-profile-types`. Every service -names its own telemetry — never assume a metric, label, or stream exists. +This table is verified against gcx v1.0.0 and Grafana 13.1.3; the gcx +command surface moves between versions, so when a documented command +errors, trust `gcx --help` over this table. + +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