Cursor rule

1---
2description: "Add structured JSON logging, observability commands, and idempotent setup scripts to a project. Use when a project needs production-readiness instrumentation, when user wants structured logging, or as a production-readiness gate at any phase of development."
3alwaysApply: false
4---
5 
6# Wire Observability
7> **HARD GATE** — **HARD GATE** — Observability is not optional. Before shipping, verify: structured logging is in place, key metrics are instrumented, error cases emit signals. 'We'll add metrics later' becomes 'never.'
8 
9 
10Add structured logging, observability commands, and idempotent setup scripts. Can be invoked at any phase — recommended at the end of the first working slice, before the first deploy.
11 
12## What this sets up
13 
141. **Structured JSON logging** — machine-readable logs for debugging and observability
152. **Observability commands** — how to check the system's health documented in CLAUDE.md
163. **Idempotent setup scripts** — scripts that can be run repeatedly without side effects
17 
18## Process
19 
20### 1. Assess current state
21 
22Check what's already in place:
23- Is there a logging library? (pino, winston, structlog, zap, slog, etc.)
24- Is logging JSON or plain text?
25- Is there a health check endpoint or command?
26- Are there setup scripts? Are they idempotent?
27 
28### 2. Add structured JSON logging
29 
30**For user-facing CLI output:** plain text is fine.
31**For everything else:** structured JSON.
32 
33Structured log entry format:
34```json
35{
36  "level": "info",
37  "timestamp": "2025-01-15T10:23:45.123Z",
38  "message": "User created",
39  "userId": "usr_abc123",
40  "requestId": "req_xyz789"
41}
42```
43 
44Guidelines:
45- Include `level`, `timestamp`, `message` in every entry
46- Add context fields relevant to the operation (userId, requestId, traceId)
47- Log at boundaries: HTTP requests in/out, DB queries, external API calls, background job start/end
48- Log errors with stack traces: `logger.error({ err, context }, "Operation failed")`
49- **Never log secrets, passwords, tokens, or PII**
50 
51### 3. Document observability commands in CLAUDE.md
52 
53Add an "Observability" section to the project's CLAUDE.md:
54 
55```markdown
56## Observability
57 
58| What | Command |
59|------|---------|
60| View logs | `<log tail command>` |
61| Health check | `<health check command>` |
62| Check DB connection | `<db ping command>` |
63| View metrics | `<metrics command>` |
64```
65 
66### 4. Write idempotent setup scripts
67 
68An idempotent script can be run multiple times and always produces the same result (no errors on re-run).
69 
70Pattern: check if the thing already exists before creating it.
71 
72```bash
73#!/usr/bin/env bash
74set -euo pipefail
75 
76# Idempotent: only create if not exists
77if ! psql -c &quot;SELECT 1 FROM pg_database WHERE datname = 'myapp'&quot; | grep -q 1; then
78  createdb myapp
79  echo &quot;Database created&quot;
80else
81  echo &quot;Database already exists, skipping&quot;
82fi
83```
84 
85Place setup scripts in `scripts/setup.sh` (or language-appropriate equivalent). Document the command in CLAUDE.md under Commands.
86 
87### 5. Verify
88 
89- [ ] Run the app and confirm JSON logs appear in the correct format
90- [ ] Run `scripts/setup.sh` twice — second run should produce no errors
91- [ ] Health check command returns success
92- [ ] No sensitive data in log output
93 
94## BCP Plus Integration
95 
96This skill maps to **BCP Plus dimension 11 (Quality Attributes)** — specifically performance, reliability, and availability instrumentation. Structured logging, health checks, and idempotent setup scripts are observable manifestations of quality-attribute requirements. The NFR Gate rule applies: standard-expectation items (e.g., "the app should log errors") score 0 with a one-line rationale; only above-standard quality requirements (e.g., p99 latency tracking, SLO-based alerting) contribute to the dimension 11 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern.
97