observability-review

Review code changes for observability quality and OpenTelemetry compliance.

1|Updated Jul 31, 2023
One-click install
npx skills add https://github.com/austintheriot/dotfiles --skill observability-review-austintheriot
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: observability-review
Source: https://github.com/austintheriot/dotfiles/tree/main/.claude/skills/observability-review
Command: npx skills add https://github.com/austintheriot/dotfiles --skill observability-review-austintheriot

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you detect observability issues that make telemetry unreliable, misleading, or too expensive to operate in production—especially around spans, metrics, logs, context propagation, and semantic conventions.

Core Features & Use Cases

  • High-signal review of telemetry changes: evaluates diffs against observability quality principles, focusing on correctness and operational fragility.
  • Span/metric/log discipline checks: flags cardinality risks, context propagation breaks, span lifecycle problems, and structured logging gaps.
  • Honeycomb-aware guidance: applies Honeycomb-friendly defaults (like wide events and trace/log correlation) while avoiding dogma where tradeoffs are genuinely contested.

Quick Start

Run /observability-review <path> to review that file or directory for observability spec compliance and operational risks.

Frequently Asked Questions about observability-review

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

FAQPage Schema
How do I review code changes for observability and telemetry gaps?

You can review code changes for observability gaps by analyzing pull requests or file paths to evaluate span design, context propagation, and metric instrument choice. This process identifies telemetry issues before they reach production.

What is span lifecycle correctness and why does it matter for OpenTelemetry?

Span lifecycle correctness ensures OpenTelemetry spans start and end properly without leaking context. Validating span lifecycles prevents broken distributed traces and misleading telemetry data in production environments.

How do I check metric cardinality risks before deploying telemetry changes?

Checking metric cardinality risks involves scanning code diffs for high-cardinality attributes like user IDs in metric labels. Evaluating cardinality discipline prevents expensive telemetry storage and pipeline degradation.

Does this observability review work with Honeycomb and OpenTelemetry semantic conventions?

Yes, the review applies Honeycomb-friendly defaults like wide events and trace or log correlation while checking compliance with OpenTelemetry semantic conventions. It provides guidance without enforcing dogma on contested tradeoffs.

How do I validate SLI and SLO coverage in a pull request?

Validating SLI and SLO coverage in a pull request requires evaluating metric instrument choices and structured logging patterns against service objectives. This review flags missing service level indicators before code merges.

What is the best way to find broken context propagation in distributed tracing?

Finding broken context propagation requires reviewing code diffs to verify OpenTelemetry context flows correctly across service boundaries. Detecting propagation breaks early prevents fragmented traces and lost span relationships.