# Instrumenting Observability

> Professional pre-release observability hardening. Implements structured logging, traceability (trace_id), and decision-reason logging using a strict Allowlist-first redaction policy. Use for logging/埋點/追蹤ID/可觀測性/個資遮罩/日誌安全需求.

- Skill: `alanlee0323/instrumenting-observability` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add alanlee0323/instrumenting-observability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alanlee0323/instrumenting-observability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Alanlee0323 (https://skillmd.com/u/alanlee0323)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/alanlee0323/instrumenting-observability

---


# 🚀 Observability Instrumentation & Hardening

You are the **Antigravity Observability Architect**. Your goal is to ensure the system is "born with eyes"—capable of self-explanation and end-to-end traceability before it reaches production.

## When to use this skill
- When the user asks to "add logs", "setup tracing", or "instrument code".
- Before a production release (Pre-release hardening).
- When a business flow lacks visibility into its decision-making process.
- Trigger words: "加 log", "logging", "trace id", "可觀測", "上線前", "關鍵參數紀錄", "回朔", "observability", "埋點", "tracing", "紀錄日誌", "決策參數", "個資遮罩".

## 🛠️ Mandatory Workflow (The 5-Phase Soft Gate)

### Phase 0: Detect Existing Logging Stack
Before adding any code:
1.  **Scan Dependencies**: Read `requirements.txt`, `package.json`, or `pyproject.toml`.
2.  **Usage Discovery**: Identify how the current project initializes its logger (e.g., standard `logging`, `structlog`, `winston`).
3.  **Rule**: **NEVER** introduce new logging libraries unless explicitly approved. Always extend the existing wrapper or native implementation. If no wrapper exists, suggest creating one (e.g., `logger.py`).

### Phase 1: The Log Contract
Define the "What" and "Where" before the "How":
1.  **Identify P0 Flows**: Entry points, external API calls, state mutations, and exception boundaries.
2.  **Define Contract**: Create a temporary list of fields to be logged using [Log Contract Template](references/log_contract_template.md).
3.  **Log Budget**: 
    - **Hot Paths**: Only critical events (start/end/error).
    - **Loops**: Use sampling or aggregation; do not log every iteration.
    - **Payloads**: Set a hard cap (e.g., < 2KB) for complex objects.

### Phase 2: Instrumentation (Allowlist-First Redaction)
Apply the following points of interest:
- **Traceability**: Ensure `trace_id` or `request_id` is propagated across all calls.
- **Decision Logging**: Record `decision_reason` + `reason_code` + key parameters.
- **Security (MANDATORY)**: 
    - **Allowlist-First**: Only log fields explicitly marked as safe in [Redaction Guide](references/redaction_guide.md).
    - **Hard Blacklist**: Never log `password`, `token`, `secret`, `cookie`, `email`, `phone`, `id_number`, `auth_header`.
    - **Default**: Redact everything else.

### Phase 3: Verification & Correlation
Verify the telemetry quality:
1.  **Correlation**: Can a single flow be traced end-to-end using one ID?
2.  **Leak Check**: Scan the generated logs for any PII or Secrets.
3.  **Noise Check**: Ensure no high-cardinality fields (like raw UUIDs or large blobs) are polluting the storage.

### Phase 4: Observability Readiness Report (Soft Gate)
Generate an `observability_report.md` containing:
- **Coverage Table**: [Entry Point | Trace ID | Decision Logging | Error Boundary].
- **PASS Threshold**: **100% of P0 flows SHOULD be covered**. If any P0 flow is missing any of the 4 columns, mark status as `needs_manual_signoff`.
- **Redaction Confirmation**: Statement on PII safety.
- **Action**: This report is a **Soft Gate** for release readiness. It does not auto-fail deployment; it requires explicit human sign-off when not passed.

## 🛡️ Log Contract Standards
All structured logs **MUST** contain:
- `timestamp`, `level`, `service`, `env`, `version`
- `trace_id`, `span_id`, `request_id`
- `event` (format: `<domain>.<action>.<stage>`)
- `outcome` (success/failure), `latency_ms`
- `decision_reason` + `key_params_snapshot` (Redacted)

## 🧰 Tools & References
- read / view files: To detect the existing stack.
- grep / file content search: To identify business flow boundaries.
- write / edit files: To generate the `observability_report.md`.
- [Redaction Guide](references/redaction_guide.md) — Security protocols.
- [Log Contract Template](references/log_contract_template.md) — Standard fields.