observability

Add structured logs, health endpoints, and persisted failure state to long-running code.

Updated Apr 28, 2026
One-click install
npx skills add https://github.com/GregM1991/skills --skill observability-gregm1991
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: observability
Source: https://github.com/GregM1991/skills/tree/main/skills/observability
Command: npx skills add https://github.com/GregM1991/skills --skill observability-gregm1991

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Unattended processes like background jobs, servers, and watchers fail silently, leaving no signal for whoever debugs them later. This Skill guides you to instrument code with decision-point logs, durable failure state, and health surfaces so a cold-start agent can diagnose problems without rerunning the code. ## Core Features & Use Cases - Decision-Point Logging: Add structured JSONL log events at the exact points where decisions are made, with the values that drove them, instead of noisy entry/exit traces. - Failure-State Persistence: Write atomic failure records (error, stack, retry count) to a known runtime location so the last failure is always discoverable. - Health & Status Surfaces: Expose cheap health endpoints or status files for long-running processes, plus a minimal set of metrics that drive alerts. - Use Case: You are building a dispatch loop with retries and guards. Use this Skill to map its failure modes, log each dispatch decision with its reason, persist errors to runtime/last-error.json, and verify the signals by simulating one failure. ## Quick Start Ask the agent to add observability to your background job or server so failures are logged, persisted, and visible on a health endpoint.

Frequently Asked Questions about observability

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add logging to a background job or server?▼

Log decisions, not activity: emit one structured event per decision point with the values that drove the choice, such as {event: "unit-dispatched", reason: "pending"}. Avoid uniform entry/exit logging, which buries signal in noise.

What is structured logging and why use JSONL?▼

Structured logging emits one machine-readable event per line with fields like ts, event, and domain-specific values instead of prose strings. JSONL output is greppable and filterable, so a future debugger can query exactly what happened.

How do I make failures visible in long-running processes?▼

Persist failure state atomically to a known location such as runtime/last-error.json with the error, stack, and retry count, and expose a cheap health endpoint or status file returning healthy, degraded, or down. Never swallow errors in an empty catch block.

How many metrics should a service expose?▼

Ship only the 3-5 counters that drive alerts, such as requests, errors, and active jobs. A metrics empire of hundreds of unread series costs CPU and disk without helping anyone diagnose a problem at 3am.

When should I not add more instrumentation?▼

Avoid logging inside tight hot loops, where you should sample or aggregate instead, and remove temporary debug lines before shipping. Keep only decision-point logs, persisted failure state, health surfaces, and explicit failure modes.