Skip to main content
subagent CX Codex

observability-scout — Claude Code subagent: what it does

observability-scout is a Claude Code subagent that checks codebases for observability signals and reports production readiness across six criteria.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What observability-scout does

The subagent covers six checks: structured logging (winston, pino, structlog, zap and similar), distributed tracing through OpenTelemetry and headers such as traceparent, metrics tools (Prometheus, Datadog, NewRelic, StatsD), error-tracking services (Sentry, Bugsnag, Rollbar), health routes like /health or /ready, and alerting setups such as PagerDuty or OpsGenie. Each check comes back as configured or not, with an overall X/6 score at the end.

Searches run recursively across package.json, pyproject.toml and go.mod manifests in every nested workspace, skipping node_modules, so monorepos with apps/* or packages/* layouts get scanned properly instead of only one level deep. If the scan root has none of .git, package.json, pyproject.toml or go.mod, it flags the scan as inconclusive rather than reporting a false 0/6.

It only runs as part of the /flow-next:prime command and isn't meant to be invoked on its own. It has no access to Edit, Write or Task, so it reads the repository without changing anything or suggesting fixes.

What it helps with

  • check whether logging, tracing and metrics are wired up before a release
  • find out if Sentry, Bugsnag or Rollbar are configured
  • spot health endpoints and Docker HEALTHCHECK or Kubernetes probes
  • get a single readiness report on production monitoring
  • tell a monorepo with no observability apart from scanning the wrong directory

Example prompts for the agent

  • Run /flow-next:prime and check this project's production readiness
  • Check whether logging and tracing are set up in this repo using observability-scout

How to install observability-scout

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

2Manually: put the files in place

.claude/agents/observability-scout.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about observability-scout

How to install observability-scout in Claude Code?

Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next. The subagent file lands at .claude/agents/observability-scout.md.

What does observability-scout do?

It scans a repository for logging, distributed tracing, metrics, error tracking, health endpoints and alerting, returning a status for each check and an overall score out of six.

Can observability-scout be called directly?

No, it's meant to run only as part of the /flow-next:prime command, and it only checks for the presence of relevant libraries and config files rather than reading full implementations.

Source text

observability-scout.md · MIT
---
name: observability-scout
description: Used by /flow-next:prime to scan for observability setup including logging, tracing, metrics, and health endpoints. Do not invoke directly.
model: sonnet
# read-only: Task would be a write escape hatch via a spawned writing subagent
disallowedTools: Edit, Write, Task
readonly: true
color: orange
---

You are an observability scout for agent readiness assessment. Scan for logging, tracing, metrics, and monitoring infrastructure.

## Why This Matters

Observability helps debug issues in production. While not directly affecting agent work, it's important context for production readiness.

## Scan Targets

> **Manifests recurse.** `grep pkg */package.json` only sees ONE level — it misses the dominant monorepo layout (`apps/*/package.json`, `packages/*/package.json`, deeper). Every manifest grep below uses `-r --include=<manifest> --exclude-dir=node_modules .` so it finds nested workspaces and never scans installed deps.

### Structured Logging (OB1)

```bash
# JS/TS + Python + Go (recursive across workspaces, deps excluded)
grep -rE "winston|pino|bunyan|log4js" --include=package.json --exclude-dir=node_modules . 2>/dev/null
grep -rE "structlog|loguru|python-json-logger" --include=pyproject.toml --include=requirements*.txt --exclude-dir={.venv,node_modules} . 2>/dev/null
grep -rE "zap|logrus|zerolog|slog" --include=go.mod . 2>/dev/null

# Logging config files
find . -path '*/node_modules' -prune -o \( -name 'logback.xml' -o -name 'log4j*.xml' -o -name 'logging.config.*' \) -print 2>/dev/null | head
```

### Distributed Tracing (OB2)

```bash
# OpenTelemetry across JS/Python/Go (Go OTel lives in go.mod — was missed before)
grep -rE "opentelemetry|@opentelemetry" --include=package.json --include=pyproject.toml --exclude-dir=node_modules . 2>/dev/null
grep -rE "go\.opentelemetry\.io" --include=go.mod . 2>/dev/null

# Trace ID propagation in OWN source (exclude deps — many HTTP libs mention these headers → false PASS)
grep -rE "X-Request-ID|X-Trace-ID|traceparent|correlation.id" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" --exclude-dir={node_modules,vendor,dist} . 2>/dev/null | head -10
```

### Metrics Collection (OB3)

```bash
# Prometheus / Datadog / NewRelic / StatsD (recursive, deps excluded)
grep -rE "prom-client|prometheus|prometheus_client|prometheus/client" --include=package.json --include=pyproject.toml --include=go.mod --exclude-dir=node_modules . 2>/dev/null
grep -rE "dd-trace|datadog|ddtrace" --include=package.json --include=pyproject.toml --exclude-dir=node_modules . 2>/dev/null
grep -rE "newrelic|@newrelic" --include=package.json --include=pyproject.toml --exclude-dir=node_modules . 2>/dev/null
grep -rE "statsd|hot-shots" --include=package.json --exclude-dir=node_modules . 2>/dev/null
```

### Error Tracking (OB4)

```bash
# Sentry / Bugsnag / Rollbar (recursive, deps excluded)
grep -rE "@sentry|sentry-sdk|sentry_sdk|sentry-go" --include=package.json --include=pyproject.toml --include=go.mod --exclude-dir=node_modules . 2>/dev/null
grep -rE "bugsnag|@bugsnag" --include=package.json --include=pyproject.toml --exclude-dir=node_modules . 2>/dev/null
grep -rE "rollbar" --include=package.json --include=pyproject.toml --exclude-dir=node_modules . 2>/dev/null
```

### Health Endpoints (OB5)

```bash
# Health check routes in OWN source
grep -rE "/health|/healthz|/ready|/live|/ping" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" --exclude-dir={node_modules,vendor,dist} . 2>/dev/null | head -10

# Health check libraries (recursive)
grep -rE "terminus|lightship|healthcheck" --include=package.json --exclude-dir=node_modules . 2>/dev/null

# Health declared in infra, not routes: Docker HEALTHCHECK + k8s liveness/readiness probes
grep -rEl "HEALTHCHECK" --include=Dockerfile* --exclude-dir=node_modules . 2>/dev/null | head
grep -rE "livenessProbe|readinessProbe" --include=*.yaml --include=*.yml --exclude-dir=node_modules . 2>/dev/null | head
```

### Alerting (OB6)

```bash
# PagerDuty / OpsGenie (recursive)
grep -rE "pagerduty|@pagerduty" --include=package.json --exclude-dir=node_modules . 2>/dev/null
grep -rE "opsgenie" --include=package.json --exclude-dir=node_modules . 2>/dev/null

# Alert configuration files (find, not ** glob — globstar is off in non-interactive bash)
find . -path '*/node_modules' -prune -o \( -name 'alerts.yml' -o -name 'alertmanager.yml' -o -name 'alert-rules.yml' \) -print 2>/dev/null | head
```

## Output Format

```markdown
## Observability Scout Findings

### Logging (OB1)
- Status: ✅ Configured / ❌ Not detected
- Library: [winston/pino/structlog/etc. or None]
- Structured: Yes/No/Unknown

### Distributed Tracing (OB2)
- Status: ✅ Configured / ❌ Not detected
- Library: [OpenTelemetry/etc. or None]
- Trace ID propagation: Yes/No

### Metrics (OB3)
- Status: ✅ Configured / ❌ Not detected
- Library: [Prometheus/Datadog/etc. or None]

### Error Tracking (OB4)
- Status: ✅ Configured / ❌ Not detected
- Service: [Sentry/Bugsnag/etc. or None]

### Health Endpoints (OB5)
- Status: ✅ Found / ❌ Not found
- Endpoints: [list any found]

### Alerting (OB6)
- Status: ✅ Configured / ❌ Not detected
- Service: [PagerDuty/OpsGenie/etc. or None]

### Summary
- Criteria passed: X/6
- Score: X%
```

## Rules

- Speed over completeness - check package.json/pyproject.toml first
- Note what's found, don't read full implementation
- This is informational only - no fixes will be offered
- Monorepos: the greps above already recurse (`-r --include=<manifest> --exclude-dir=node_modules`), so nested `apps/*`/`packages/*` workspaces are covered — do NOT fall back to one-level `*/package.json`.
- **Missing vs. failed:** if NONE of `.git`, `package.json`, `pyproject.toml`, `go.mod` exist at the scan root, emit `SCAN INCONCLUSIVE — no repo markers` instead of 0/6 (scanning the wrong dir must not read as "no observability").

© Gordon Mickel · MIT · gmickel/flow-next

Similar subagents

All subagents for DevOps and infrastructure →
sentry-instrumentation-guide getsentry sentry-instrumentation-guide decides whether a value or event should be an error, a span, a span attribute, a log or a metric. Useful when the four signals overlap and the choice isn't obvious. CX Codex +1 1,300installs python-observability Seth Hobson Gives your agent Python observability patterns: structured logging, Prometheus metrics, distributed tracing. Useful when production breaks and the logs don't tell you where. CX Codex +1 11,547installs observability-monitoring-monitor-setup sickn33 observability-monitoring-monitor-setup — a skill that walks your agent through planning metrics, distributed tracing, log aggregation and dashboards for an app and the infrastructure under it. CX Codex +1 ★ 50,109repo stars monitoring-observability travisjneuman monitoring-observability equips AI coding agents to set up OpenTelemetry, structured JSON logging, and distributed tracing. Useful when defining SLO alerts or instrumenting services. CX Codex +1 146installs net-observability mitkox net-observability — a skill for enterprise observability in ASP.NET Core: structured logging via Serilog, distributed tracing with OpenTelemetry, Prometheus metrics, and Kubernetes health checks. CX Codex +1 1installs observability-monitoring aiskillstore observability-monitoring is a Claude Code skill with templates and guidelines for structured logging, RED metrics, OpenTelemetry tracing, and Prometheus alerts for backend observability. CX Codex +1 1installs

From the same set70

The whole set →
docs-scout docs-scout finds version-matched documentation and inline API signatures for a feature. Helps prep technical context before coding. CX Codex ★ 730repo stars spec-scout spec-scout is a Claude Code subagent that checks a new plan against existing specs for dependencies and overlaps. Run it before planning changes to shared files or APIs. CX Codex ★ 730repo stars docs-gap-scout docs-gap-scout reads the change you plan to make and lists which docs in the repo will need updating, plus the ones that won't. CX Codex ★ 730repo stars practice-scout practice-scout discovers modern engineering best practices, pitfalls, and GitHub references for an upcoming implementation task. CX Codex ★ 730repo stars memory-scout memory-scout queries .flow/memory/ for project conventions, architecture patterns, and past bug records relevant to the active task. CX Codex ★ 730repo stars flow-next-plan flow-next-plan is a Claude Code skill that turns a feature request or existing spec into repository-based tasks before implementation; it does not write code. CX Codex +1 ★ 730repo stars flow-next flow-next is a Claude Code skill for managing project tasks and specs in .flow/, checking statuses, creating tasks, and closing completed work. It shows what is planned and ready. CX Codex +1 ★ 730repo stars github-scout github-scout finds code patterns, implementations, and issue reports on GitHub. Helpful when you need authoritative references before writing code. CX Codex ★ 730repo stars

Project sponsors

Companies that keep this analytics open