ericrisco/rsc-harness / skills/observability
observability
VerifiedUse when instrumenting a service from the inside so an incident can be explained from telemetry alone — wiring OpenTelemetry logs, metrics and traces, standing up a Collector, exporting via OTLP, and defining telemetry-driven alerts. NOT outside-in uptime probes, on-call rotation, or who-gets-paged (that is `monitoring`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.0 KB |
| evals/README.md | markdown | 1.3 KB |
| evals/cases.yaml | config | 3.8 KB |
| references/collector-config.md | markdown | 4.3 KB |
| references/instrumentation-recipes.md | markdown | 4.8 KB |
| scripts/verify.shexecutable | script | 6.2 KB |
scripts/verify.sh
View on GitHub#!/usr/bin/env bash
#
# verify.sh - lint an emitted OpenTelemetry observability setup.
#
# Usage:
# cd <dir containing the Collector config + SDK init>
# ./verify.sh [path-to-collector-config.yaml]
#
# Read-only: never mutates anything. Checks the wiring, not just presence:
# 1. a Collector config exists (a *.yaml/*.yml with receivers: and service:)
# 2. it is valid: `otelcol validate` if the binary is on PATH, else
# a required-keys check for receivers / exporters / service.pipelines
# 3. every exporter declared under exporters: is referenced in some
# pipeline (the classic "exporter defined but never enabled" footgun)
# 4. SDK init sets the service name (OTEL_SERVICE_NAME /
# OTEL_RESOURCE_ATTRIBUTES / a service.name resource attribute) -> warn
# 5. heuristic cardinality check: warn if user_id|request_id|email|session_id
# is used as a metric label/attribute key
#
# Emits [ ok ]/[warn]/[fail] per check, then PASS or FAIL.
# Exits 0 on a clean setup AND when nothing relevant is found (no false failure).
# Exits 1 only on hard failures: no config, invalid config, unused exporter.
#
# Portable: stock macOS bash 3.2 + grep + awk. No associative arrays, no mapfile.
set -euo pipefail
if [ -t 1 ]; then
RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
else
RED=''; GREEN=''; YELLOW=''; RESET=''
fi
failed=0
fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$*"; }
ok() { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
# --- 1. locate a Collector config -------------------------------------------
cfg="${1:-}"
if [ -z "$cfg" ]; then
# any yaml/yml that looks like a Collector config (has receivers: and service:)
while IFS= read -r f; do
if grep -Eq '^[[:space:]]*receivers[[:space:]]*:' "$f" \
&& grep -Eq '^[[:space:]]*service[[:space:]]*:' "$f"; then
cfg="$f"; break
fi
done < <(find . -maxdepth 3 -type f \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null)
fi
if [ -z "$cfg" ] || [ ! -f "$cfg" ]; then
skip "no OTel Collector config found (a *.yaml with receivers: + service:) - nothing to verify."
exit 0
fi
printf -- '----- linting %s\n' "$cfg"
# --- 2. validity ------------------------------------------------------------
if command -v otelcol >/dev/null 2>&1; then
if otelcol validate --config "$cfg" >/dev/null 2>&1; then
ok "otelcol validate passed"
else
fail "otelcol validate rejected the config"
fi
elif command -v otelcol-contrib >/dev/null 2>&1; then
if otelcol-contrib validate --config "$cfg" >/dev/null 2>&1; then
ok "otelcol-contrib validate passed"
else
fail "otelcol-contrib validate rejected the config"
fi
else
# no binary: required top-level/section keys must be present
miss=""
grep -Eq '^[[:space:]]*receivers[[:space:]]*:' "$cfg" || miss="$miss receivers"
grep -Eq '^[[:space:]]*exporters[[:space:]]*:' "$cfg" || miss="$miss exporters"
grep -Eq '^[[:space:]]*service[[:space:]]*:' "$cfg" || miss="$miss service"
grep -Eq '^[[:space:]]*pipelines[[:space:]]*:' "$cfg" || miss="$miss service.pipelines"
if [ -z "$miss" ]; then
ok "required sections present (receivers, exporters, service.pipelines) [otelcol not on PATH; key-check only]"
else
fail "config missing required section(s):$miss"
fi
fi
# --- 3. every declared exporter is referenced in a pipeline -----------------
# Collect exporter ids: indented one level under the top-level `exporters:` block,
# keys ending in ':' (e.g. "otlphttp/traces:"). Then confirm each id's bare name
# appears somewhere after a "service:"/"pipelines:" context.
exp_ids="$(awk '
/^exporters[[:space:]]*:/ { in_exp=1; ind=-1; next }
/^[a-zA-Z0-9_]+[[:space:]]*:/ { if (in_exp) in_exp=0 } # next top-level block ends it
in_exp {
if ($0 ~ /^[[:space:]]+[A-Za-z0-9_\/.-]+[[:space:]]*:/) {
line=$0
sub(/:.*/, "", line); gsub(/[[:space:]]/, "", line)
# only the first indentation level (exporter ids), skip deeper config keys
lead=match($0, /[^ ]/)-1
if (ind==-1) ind=lead
if (lead==ind && line!="") print line
}
}
' "$cfg" 2>/dev/null || true)"
if [ -z "$exp_ids" ]; then
skip "no exporter ids parsed under exporters: - skipping unused-exporter check"
else
# body after the first `service:` line is where pipelines reference exporters
svc_body="$(awk '/^service[[:space:]]*:/{s=1} s{print}' "$cfg")"
unused=""
for e in $exp_ids; do
if printf '%s\n' "$svc_body" | grep -Fq "$e"; then
:
else
unused="$unused $e"
fi
done
if [ -z "$unused" ]; then
ok "every declared exporter is wired into a pipeline"
else
fail "exporter(s) declared but never used in any pipeline:$unused (inert until added to service.pipelines)"
fi
fi
# --- 4. service.name is set somewhere in the setup --------------------------
# Look across the whole dir's likely SDK-init files, not just the yaml.
sdk_hit=0
if grep -Rqs -E 'OTEL_SERVICE_NAME|OTEL_RESOURCE_ATTRIBUTES|service[._-]?name|ServiceName' . 2>/dev/null; then
sdk_hit=1
fi
if [ "$sdk_hit" -eq 1 ]; then
ok "service.name is set (OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES / resource attr found)"
else
warn "no service.name found - telemetry will land as 'unknown_service'. Set OTEL_SERVICE_NAME or a service.name resource attribute."
fi
# --- 5. high-cardinality metric label heuristic -----------------------------
# Warn (don't fail) if an unbounded id is used as a metric label/attribute key.
card_hit="$(grep -RnsE '(user_id|request_id|session_id|email)[[:space:]]*[:=]' . 2>/dev/null \
| grep -Ei 'label|attribute|metric|tags?|dimension' || true)"
if [ -n "$card_hit" ]; then
warn "possible high-cardinality metric label(s) - keep these off metrics, put them on spans/logs:"
printf '%s\n' "$card_hit" | sed 's/^/ /'
else
ok "no obvious high-cardinality metric label (user_id/request_id/session_id/email)"
fi
# --- verdict ----------------------------------------------------------------
echo
if [ "$failed" -eq 0 ]; then
printf '%sPASS%s - observability setup is wired.\n' "$GREEN" "$RESET"
exit 0
else
printf '%sFAIL%s - fix the items above.\n' "$RED" "$RESET"
exit 1
fi
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |