Imported from bedkillerspacex-boop/codex-skill-library (python-metrics-catalog/SKILL.md). Install upstream with npx skills add bedkillerspacex-boop/codex-skill-library --skill python-metrics-catalog. Copyright stays with the author.

Python metrics catalog

Research grounding

Create a governed metrics catalog so Python services emit consistent, low-cardinality, owned metrics that map to SLOs. Skill id: python-metrics-catalog.

Scope And Authorization

• In scope: your Prometheus/OTel/Datadog/etc. metrics pipelines.
• Out of scope: high-cardinality attacks against shared SaaS; scraping foreign /metrics without authz.
• Prefer OpenTelemetry semantic conventions where applicable.
• Pair with observability-metrics-tracing, python-monitoring, python-logging-config-dict, code-quality-standards.

When To Use

• Standardizing metric names/labels across microservices.
• Preventing cardinality explosions (user_id as label).
• Cataloging metrics for SLO dashboards and cost control.

Do Not Use As Primary

Domain Focus

Workflow

1. Confirm scope and success criteria

1. Metrics backend, cardinality budget, naming standard owner.
2. Success: “catalog covers critical services; CI lints new metrics; no unbounded labels.”
3. Inventory top series count offenders.

2. Define conventions

3. Catalog schema

from dataclasses import dataclass, field

@dataclass
class MetricSpec:
    name: str
    mtype: str  # counter gauge histogram summary
    description: str
    labels: list[str]
    owner: str
    slo: str | None = None
    retention_days: int = 30
    unit: str = ""

    def validate(self) -> None:
        forbidden = {"user_id", "email", "request_id", "path"}
        bad = forbidden.intersection(self.labels)
        if bad:
            raise ValueError(f"forbidden labels: {bad}")

4. Instrument via shared library

from prometheus_client import Counter, Histogram

REQUESTS = Counter(
    "billing_http_requests_total",
    "HTTP requests",
    ["method", "route", "status_class"],
)
LATENCY = Histogram(
    "billing_http_request_duration_seconds",
    "Request latency",
    ["method", "route"],
    buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5),
)

1. Use route templates (/users/{id}) not raw paths.
2. Central registration: metrics not in catalog fail CI (optional strict mode).

5. Cardinality and cost controls

# Review top metrics by series count in backend
python -m metrics.catalog_lint catalog/*.yaml
python -m pytest tests/test_metric_spec.py -q

1. Drop or aggregate high-cost metrics.
2. Align retention with python-log-retention philosophy for metrics tiers.

6. SLO linkage

1. Each user-facing journey references catalog metrics.
2. Alert rules only on cataloged metrics with owners (python-monitoring).
3. Document recording rules for expensive queries.

7. Hand off

1. Publish catalog site or YAML repo.
2. Review process for new metrics (PR template).
3. Quarterly cardinality review.

Good / Bad

Output Checklist

• Naming and label policy documented
• Catalog schema and files exist
• Shared instrumentation library adopted
• Lint/CI for forbidden labels
• Cardinality review process
• SLO/alert linkage for critical journeys
• Owners assigned
• code-quality-standards applied

Rules

• Owned telemetry only; do not weaponize cardinality.
• Prefer fewer high-quality metrics over metric sprawl.
• Never put PII in labels.
• Keep secrets out of metric endpoints (auth on /metrics).
• Alerting operations detailed in python-monitoring.