/configure:instrumentation

Check and upsert observability instrumentation — OpenTelemetry traces and metrics, structured logging, and error tracking — against project standards.

When to Use This Skill

Context

• Package.json: !find . -maxdepth 1 -name 'package.json'
• Pyproject.toml: !find . -maxdepth 1 -name 'pyproject.toml'
• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml' -type f
• OTel in package.json: !find . -maxdepth 1 -name 'package.json' -exec grep -o '"@opentelemetry/[^"]*"' {} +
• OTel in pyproject.toml: !find . -maxdepth 1 -name 'pyproject.toml' -exec grep -o 'opentelemetry-[a-z-]*' {} +
• Init candidates: !find . -maxdepth 2 -type f \( -name 'otel*' -o -name '*telemetry*' -o -name 'tracing*' -o -name 'instrumentation*' \) -not -path '*/node_modules/*'
• Structured loggers: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' \) -exec grep -oE '"(pino|winston)"|structlog|loguru' {} +
• Sentry SDK: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' \) -exec grep -oE '@sentry/[a-z-]*|sentry-sdk' {} +

Parameters

Parse these from $ARGUMENTS:

Execution

Execute this instrumentation compliance check:

Step 1: Run the detection script

bash "${CLAUDE_SKILL_DIR}/scripts/configure-instrumentation.sh" --project-dir "$(pwd)"

The script emits OTEL_SDK=, OTEL_INIT=, OTEL_ENV=, STRUCTURED_LOGGER=, METRICS_EXPORTER=, SENTRY_SDK=, and RECOMMENDATION=configured|partial|setup. Use these booleans as the ground truth for the rest of the check — do not re-derive detection by hand.

Step 2: Detect language and framework

1. Read .project-standards.yaml for project_type if present
2. Node/TypeScript: package.json (Express/Fastify/Next.js shape decides the auto-instrumentation set)
3. Python: pyproject.toml or requirements.txt (Django/Flask/FastAPI decide the instrumentor packages)

Step 3: Analyze against standards

Compare the detection output against the compliance tables in REFERENCE.md. The standard posture is:

1. Traces + metrics: OpenTelemetry SDK installed, one init file that starts it (instrumentation.ts NodeSDK / telemetry.py), OTLP exporter configured via OTEL_EXPORTER_OTLP_ENDPOINT (never hardcoded endpoints)
2. Sampling: OTEL_TRACES_SAMPLER set for production (parentbased_traceidratio)
3. Logging: one structured logger (pino/winston or structlog/loguru) emitting JSON with trace correlation (trace_id/span_id fields)
4. Metrics: exported through the OTel SDK, or prom-client/prometheus-client with a /metrics endpoint
5. Error tracking: if SENTRY_SDK=true, delegate the Sentry compliance pass to /configure:sentry --check-only via the SlashCommand tool rather than re-checking it here

If --type was given, check only that signal.

Step 4: Report results

Print a compliance report: per-signal status (PASS/WARN/FAIL), the RECOMMENDATION verdict, and missing items. If --check-only, stop here.

Step 5: Apply fixes (if --fix or user confirms)

Using the templates in REFERENCE.md:

1. Missing OTel SDK: add the SDK packages for the detected language
2. Missing init: create the init file (Node instrumentation.ts NodeSDK; Python telemetry.py or opentelemetry-instrument entrypoint)
3. Missing env config: add OTEL_SERVICE_NAME / OTEL_EXPORTER_OTLP_* to .env.example and deployment manifests — never commit real endpoints with credentials
4. Missing structured logger: add pino (Node) or structlog (Python) with the trace-correlation config
5. Sentry gaps: run /configure:sentry --fix via SlashCommand

Step 6: Update standards tracking

Update or create .project-standards.yaml:

standards_version: "2025.1"
project_type: "<detected>"
last_configured: "<timestamp>"
components:
  instrumentation: "2025.1"

Environment Variables

For SDK install commands, init templates, sampling guidance, logger configuration, and metrics-endpoint patterns, see REFERENCE.md.

Agentic Optimizations

Error Handling

• No package manifest: report "no instrumentable project detected" and stop
• Both Node and Python present: check both stacks, report per-stack status
• OTel SDK present but never started (OTEL_INIT=false): FAIL — an installed-but-unstarted SDK silently exports nothing

See Also

• /configure:sentry - Sentry error-tracking setup (the vendor complement; this skill delegates Sentry fixes there)
• /configure:all - Run all compliance checks
• /configure:status - Quick compliance overview
• typescript-plugin:typescript-sentry - Day-to-day Sentry SDK usage patterns for Bun/Node/Next.js