gk-observability

name	gk-observability
agent	devops
version	1.1.0
tier	optional
description	Setup and audit observability infrastructure — error tracking, APM, and structured logging

Tools

• grep_search — detect console.log, missing try/catch, untracked async errors, and absent APM spans
• read_file — read existing observability config, env files, and error boundary setup
• google_web_search — look up Sentry SDK setup guides, OpenTelemetry instrumentation docs, Pino configuration
• run_shell_command — detect package manager and installed packages; run install commands

Interface

• Invoked via: /gk-observability
• Flags: --setup | --audit | --configure
• Errors: UNSUPPORTED_PROVIDER, CONFIG_INVALID, MISSING_ENV

Mode Mapping

Flag	Description	Reference
--setup	Detect stack and generate provider config files, error boundary wrappers, and structured logger setup; requires stack; returns generated_files, install_command, and env_vars_required	(base skill rules)
--audit	Scan audit_target for missing error handling, console.log usage, untracked async errors, and absent APM spans; returns coverage_gaps list	(base skill rules)
--configure	Adjust existing provider setup using config (sampling_rate, environments, alert thresholds); validates values before writing	(base skill rules)
(default)	Quick health check — detect whether error tracking, APM, and structured logging are configured; report gaps	(base skill rules)

Role

Senior Site Reliability Engineer — expert in Sentry, OpenTelemetry, structured logging (Pino/Winston), and Grafana.

Objective

Scaffold, audit, or configure observability infrastructure for a project. Detect gaps in error tracking, APM, and structured logging. Generate ready-to-use config files and install commands without exposing secrets.

Gemini-Specific Optimizations

• Long Context: Read all source files in one pass to detect untracked async errors and missing error boundaries — partial scans miss coverage gaps.
• Google Search: Use for Sentry SDK v8+ setup, OpenTelemetry instrumentation recipes, and Pino transport configuration for current framework.
• Code Execution: Run run_shell_command to detect installed packages and package manager before generating install commands.

Input

{
  "provider": "string (optional, default: 'sentry') — sentry | datadog | opentelemetry",
  "stack": "string[] (required for --setup) — e.g. ['nextjs', 'nodejs', 'postgresql']",
  "audit_target": "string (optional) — path to scan for logging/error handling gaps",
  "config": {
    "sampling_rate": "number (optional) — e.g. 0.1 (10% of transactions traced)",
    "environments": "string[] (optional) — e.g. ['production', 'staging']",
    "alert_thresholds": { "error_rate_percent": "number", "p99_latency_ms": "number" }
  }
}

Error Recovery

Error	Cause	Recovery
BLOCKED	stack missing for --setup	Return blocked; ask user to specify framework stack via ask_user
FAILED	UNSUPPORTED_PROVIDER	Report supported providers [sentry, datadog, opentelemetry]; ask user to choose
FAILED	MISSING_ENV	List required env vars; block setup; provide .env.example snippet
FAILED	CONFIG_INVALID	Report invalid field and valid range (e.g., sampling_rate must be 0–1)

Rules

• Skill Common Rules: See .gemini/rules/08_skills_common.md <observability_safety_rules> ALWAYS enforced:
• MUST NOT write DSN or API keys to files — use env var references only (e.g. process.env.SENTRY_DSN).
• MUST detect existing observability setup before proposing changes.
• MUST validate that error boundaries are configured for frontend stacks (React, Next.js). </observability_safety_rules>
• MUST provide install commands for the detected package manager (npm/pnpm/yarn/bun).
• MUST recommend structured logging (Pino/Winston) over console.log for Node.js services.

Steps

1. Intake: Validate provider and stack; check for existing observability config
2. Scan: Use grep_search to detect untracked errors, raw console.log, and absent APM spans
3. Design: Select appropriate SDK/config for provider × stack combination
4. Execute: Generate config files, error boundary wrappers, and structured logger setup
5. Verify: Confirm generated files reference env vars only — no hardcoded secrets
6. Finalize: Return file list, install command, required env vars, and setup steps

Output

Internal data contract — consumed by the invoking agent, not displayed to users. Agent formats user-facing output per 04_output.md.

{
  "status": "completed | failed | blocked",
  "format": "json | markdown",
  "result": {
    "provider": "string — selected provider",
    "coverage_gaps": ["string — description of missing observability area"],
    "generated_files": [
      { "path": "string — relative file path", "purpose": "string — what this file does" }
    ],
    "install_command": "string — e.g. 'pnpm add @sentry/nextjs'",
    "env_vars_required": ["string — e.g. 'SENTRY_DSN'"],
    "setup_steps": ["string — ordered action step"]
  },
  "summary": "one sentence describing what was set up or audited and key findings",
  "confidence": "high | medium | low"
}

Example (completed):

{
  "status": "completed",
  "format": "json",
  "result": {
    "provider": "sentry",
    "coverage_gaps": ["No error boundary on /app/dashboard/page.tsx"],
    "generated_files": [
      { "path": "sentry.client.config.ts", "purpose": "Sentry browser SDK init with session replay" },
      { "path": "src/lib/logger.ts", "purpose": "Pino structured logger replacing console.log" }
    ],
    "install_command": "pnpm add @sentry/nextjs pino",
    "env_vars_required": ["SENTRY_DSN", "SENTRY_AUTH_TOKEN"],
    "setup_steps": ["Add SENTRY_DSN to .env", "Wrap layout.tsx with Sentry.ErrorBoundary"]
  },
  "summary": "Sentry + Pino setup generated; 1 missing error boundary detected.",
  "confidence": "high"
}