structured-logging-lite ยท diff
git:20260610.1fb8a11 to git:20260716.c6fdb3e
62 added, 13 removed. Audit A to A.
---
name: structured-logging-lite
- description: Logging system design guide covering centralized architecture, field standards, and distributed tracing. Use when designing log systems, establishing standards, or debugging production issues.
+ description: Design, audit, or implement application structured logging architecture from repository evidence. Use when a user asks whether or where to add logs, how to choose or migrate a logger, how to standardize events/fields/levels/redaction, how to add HTTP access or panic logs, or why production logs cannot answer an incident question. Do not use merely to tail platform logs or to design a full metrics, tracing, SLO, and incident-management program.
---
# Structured Logging Lite
- Use this skill to design practical structured logging schemas, levels, central configuration, masking rules, and operational checklists.
+ Build the smallest logging contract that makes the target system diagnosable without leaking data, duplicating audit records, or forcing an unnecessary logging-library migration.
- ## Routing
+ ## Operating Contract
- - Start here to confirm scope, safety boundaries, and the minimum workflow.
- - Load `references/full-guide.md` before executing detailed commands, applying templates, or relying on examples from this skill.
- - Keep the work limited to the user-requested target; do not add adjacent improvements unless the user asks.
+ - **Direct actions:** Inspect repositories, manifests, runtime entrypoints, tests, deployment files, and existing logs. Make local logging changes only when the user asks to implement or upgrade them; treat design, review, and diagnosis requests as read-only.
+ - **Escalate before:** Ask before publishing, pushing, changing remote observability infrastructure, touching production, or expanding from application logging into a full observability rollout.
+ - **Evidence-backed pushback:** Challenge a requested library migration or log-everything plan only with repository evidence, a measured requirement, a concrete security/cardinality risk, or a smaller compatible alternative.
+ - **Feedback loop:** Promote repeated missing fields, false-success signals, secret leaks, or manual incident queries into the field contract, gotchas, validation tests, or a deterministic helper.
+ - Never print or persist credentials, tokens, cookies, signatures, request bodies, DSNs, private URLs, or secret values while investigating.
+ - Return errors through the existing error contract. A new log line never justifies swallowing, downgrading, or replacing an error.
- ## Quick Workflow
+ ## Workflow
- 1. Confirm the target, available context, constraints, and done-when signal.
- 2. Read the relevant section of `references/full-guide.md` for task-specific details.
- 3. Execute the smallest reversible action that satisfies the request.
- 4. Verify that examples include required fields, level choices, sensitive-data handling, and integration points for the target stack.
- 5. Report changed files, commands run, evidence collected, and any remaining risk.
+ 1. **Search before proposing.** Read applicable repository instructions, check the worktree, then locate manifests, entrypoints, logger construction, log calls, request/context propagation, error mapping, panic handling, adapters, workers, audit records, metrics, tests, and deployment configuration.
+ 2. **Classify the target.** Distinguish a reusable library, CLI/batch job, HTTP service, long-running worker, or multi-service system. Libraries should usually accept host-provided diagnostics rather than configure process-global output.
+ 3. **Reconstruct current coverage.** Mark lifecycle, request, authentication, application milestones, external adapters, background jobs, degraded paths, panic/crash, and third-party library output as `covered`, `partial`, or `missing`.
+ 4. **Name the operational questions.** Require each proposed event to answer a concrete debugging, security, support, or capacity question. Delete events that only narrate normal control flow.
+ 5. **Choose boundaries before libraries.** Configure output at the composition root; observe requests at transport middleware; log effect failures at adapters; log worker batch outcomes at the worker owner; keep pure domain code free of logger dependencies.
+ 6. **Keep or select the logger.** Prefer a working repository-standard logger or a language standard library. Recommend migration only with evidence such as missing required capability, measured overhead, ecosystem incompatibility, or unsafe behavior.
+ 7. **Write the contract.** Define stable event names, required and conditional fields, level policy, error classification, correlation rules, redaction rules, retention/collection ownership, and low-cardinality metric labels.
+ 8. **Implement incrementally when authorized.** Land P0 request/error/security coverage first, P1 adapter and worker telemetry next, and tracing or backend-specific integration only when the runtime needs it.
+ 9. **Verify with fresh evidence.** Run repository-native build/tests plus log capture, secret-canary, route-normalization, panic, and streaming-response tests that match the change.
+ ## Boundary Rules
+
+ - Treat logs, metrics, traces, and durable audit records as different contracts. Do not claim one replaces another.
+ - Emit one request-completion event per request. Add a second event only when it contains a distinct root cause or business outcome.
+ - Use route templates or operation names in metrics. Keep request IDs, user IDs, asset/order IDs, raw paths, URLs, and error strings out of metric and log-index labels.
+ - Include `trace_id` and `span_id` only when a real trace context exists. Do not invent IDs or require tracing as a prerequisite for useful logging.
+ - Prefer fixed error codes and reason enums over arbitrary error strings for aggregation. Preserve a safe cause for debugging without exposing upstream payloads.
+ - Exclude or sample high-volume health and readiness success logs. Never sample security failures or user-visible server errors without an explicit loss policy.
+ - Preserve optional response/stream interfaces when observing HTTP writers; a naive wrapper can break flushing, hijacking, streaming, or byte counts.
+
+ ## Deliverable
+
+ For design or audit work, report:
+
+ ```text
+ verdict:
+ current_evidence:
+ chosen_stack:
+ boundary_map:
+ event_and_field_contract:
+ privacy_and_cardinality:
+ coverage_gaps:
+ P0_P1_P2:
+ validation:
+ remaining_risks:
+ ```
+
+ For implementation work, also report changed files, fresh verification commands, and any deployment or collector work that remains outside the repository.
+
+ ## Gotchas
+
+ - Raw URL paths turn identifiers into unbounded labels and can leak query credentials.
+ - Logging every function entry/exit creates volume without diagnostic value.
+ - Logging both at every return site and again at the boundary duplicates the same failure.
+ - ORM defaults may print interpolated SQL, expected not-found errors, or non-JSON output.
+ - A logger hidden in generic context values becomes an implicit dependency; keep typed correlation data in context and logging ownership at boundaries.
+ - A successful fallback that changes user-visible output still needs an error signal and metric; `warn` plus silent degradation is not success.
+ - Access logs without status, duration, normalized route, and request ID rarely answer incident questions.
+ - Persistent audit events require transactional and retention guarantees that stdout logs do not provide.
+
## References
- - `references/full-guide.md` - complete command patterns, examples, checklists, and edge cases.
+ - Read [`references/full-guide.md`](references/full-guide.md) before designing a schema, level policy, rollout, or validation plan.
+ - For Go repositories, also read [`references/go.md`](references/go.md) before choosing a library or implementing HTTP, `slog`, or ORM integration.
+ - For a full observability/SLO/tracing program, route to `observability-sre` after the logging contract is clear.