observability-and-instrumentation

Instruments production code with structured logs, metrics, traces, and symptom-based alerts.

Updated Jun 8, 2026
One-click install
npx skills add https://github.com/Avistian/nba --skill observability-and-instrumentation-avistian
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: observability-and-instrumentation
Source: https://github.com/Avistian/nba/tree/main/.cursor/skills/observability-and-instrumentation
Command: npx skills add https://github.com/Avistian/nba --skill observability-and-instrumentation-avistian

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Production features often ship without telemetry, so when something breaks, engineers cannot tell what happened from the available data. This Skill guides you to instrument code alongside the feature so incidents become queries instead of archaeology. ## Core Features & Use Cases - Question-driven instrumentation: Define the on-call questions first, then map structured logs, RED/USE metrics, and OpenTelemetry traces to each question. - Structured logging with correlation IDs: Emit JSON log events with stable names and request IDs propagated across services, while keeping secrets and PII out of telemetry. - Symptom-based alerting: Create actionable alerts on user-facing symptoms with runbook links, and verify telemetry by triggering failures in staging. - Use Case: When adding a payment retry flow, use this Skill to add a payment_failed structured log event, a latency histogram for the provider call, a trace span around the charge operation, and an alert on elevated error rate. ## Quick Start Instrument my new checkout endpoint with structured logging, RED metrics, and an OpenTelemetry trace, then define the alerts an on-call engineer would need.

Frequently Asked Questions about observability-and-instrumentation

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

FAQPage Schema
How do I add structured logging to a production service?▼

Structured logging means emitting JSON log events with stable event names and machine-readable fields instead of interpolated strings. Attach a correlation or request ID at the system boundary and include it on every log line so a single request can be reconstructed.

What metrics should I instrument for an HTTP endpoint?▼

Use the RED method: rate, errors, and duration for every endpoint and external dependency. Track latency as a histogram so p95 and p99 are queryable, and keep label values from small fixed sets like route templates and status classes.

Should I use OpenTelemetry for distributed tracing?▼

OpenTelemetry is the vendor-neutral standard and its auto-instrumentation covers HTTP, gRPC, and common database clients with minimal code. Add manual spans only around meaningful internal units of work and propagate context across async boundaries.

Why do metric labels with user IDs cause problems?▼

Every unique label combination creates a separate time series, so unbounded values like user IDs, raw URLs, or error messages explode cardinality and can overwhelm the metrics backend. High-cardinality lookups belong in logs and traces instead.

When should an alert page someone versus create a ticket?▼

Page only for user-facing symptoms that need immediate action, such as error rate above threshold or high p99 latency. Use a ticket severity for degradations that can be handled within the week, and alert on symptoms rather than causes like CPU usage.

When is this observability skill not the right tool?▼

It is not for diagnosing an active incident, which belongs to debugging workflows, nor for profiling measured slowness, which is performance optimization. It covers the instrumentation written alongside features that makes later diagnosis fast.