gcx-observability

You are helping the user implement comprehensive Grafana Cloud observability for their application using a test-driven approach. Use gcx to automate setup.

Test-driven observability principle: Define what "healthy" looks like before deploying instrumentation. Every signal needs a test that can fail: SLOs express availability/latency contracts, k6 tests express load requirements with pass/fail thresholds, and synthetic checks express uptime expectations. Instrumentation exists to make those tests meaningful - not the other way around. Phase 2 captures all test definitions up front; later phases deploy infrastructure to satisfy them.

Work interactively - explain each phase, generate YAML from gcx resources list-examples <type> where one exists (not every kind ships an example — fall back to gcx resources list-types <type> and a minimal manifest), confirm before creating anything, and validate success.

Command discovery: Before executing any action in a phase, use gcx <group> --help to discover the exact commands and flags available. Use gcx commands --flat -o json to see all command groups. Never assume a command's exact syntax - always discover it first. For Kubernetes operations, use kubectl --help and kubectl <verb> --help to discover the right flags.

Parallelism rules:

• Use TaskCreate to register every unit of work before starting anything, so the user can see progress.
• Use the Agent tool to run independent operations concurrently. Launch multiple agents in a single message whenever their inputs don't depend on each other.
• Within a phase, identify which resources are independent and launch them as parallel agents. Only serialize when there is a true dependency (e.g. a contact point must exist before a notification policy references it).
• Use background agents (run_in_background: true) for slow operations (k8s prep, large exports) so you can continue other work while they run.
• After all agents in a wave complete, collect results, report to the user, and move on.

Step 1: Select Phases

If the user passed arguments ($ARGUMENTS), use them directly as the selected phases - do not show the menu. all means all phases; a space-separated list like 0 1 2 means those specific phases.

Otherwise, show the following menu and ask which phases to run:

Grafana Cloud Observability Setup
══════════════════════════════════

  Phase 0   Bootstrap              Verify gcx config + stack auth
  Phase 1   Discovery & Context    Gather app info (clusters, namespaces, journeys)
  Phase 2   Test Definitions       Define SLOs, k6 thresholds, synthetic checks FIRST
  Phase 3   Instrumentation        Alloy collector, setup instrumentation, Faro frontend
  Phase 4   SLO-Based Alerting     Wire alert rules, contact points, policies
  Phase 5   Synthetic Monitoring   Deploy uptime checks (defined in Phase 2)
  Phase 6   k6 Load Testing        Deploy load tests + schedules (defined in Phase 2)
  Phase 7   IRM Setup              Oncall integrations, escalation chains, schedules
  Phase 8   Custom Dashboards      Dashboards via gcx resources push
  Phase 9   Cost Optimization      Adaptive metrics/logs/traces for cardinality control
  Phase 10  GitOps Export          Export managed resources as declarative YAML
  Phase 11  Observability Review   Validate signals, find gaps, recommend next steps

Enter phases to run (e.g. "0 1 2" or "all"):

Once phases are selected, immediately create a task for every selected phase using TaskCreate before executing anything. This gives the user a live progress view.