[dayaffe]

Summary

• add push-metrics to produce repository-health gauge snapshots for Datadog
• reconstruct daily historical snapshots from GitHub created_at and closed_at data
• add sync-metrics to fetch a complete GitHub snapshot into temporary local storage, rebuild the database, and produce metrics
• add --output-json so a Datadog workflow can submit size-safe /api/v2/series bodies through its managed HTTP connection
• keep fetched JSON and SQLite files ephemeral; no data is staged, committed, or pushed to GitHub
• default to the versioned github.health.v2 metric namespace and document the backfill/update procedure

This is a separate implementation that builds on and supersedes the direction explored in #15; it does not modify or close that PR.

Historical behavior

lookback/history controls the period reconstructed at daily UTC timestamps. activity_window independently controls the rolling period summarized by closed-item metrics. Every sync-metrics run performs a complete GitHub fetch into temporary storage, so correctness does not depend on persisting refreshed snapshots in this repository.

Recommended operation for a new metric prefix:

1. Submit a one-day seed so the metric names exist.
2. Enable Historical Metrics Ingestion for github.health.v2 in Datadog.
3. Run one 450-day backfill.
4. Schedule fixed-UTC weekly runs with a 7-day lookback and 30-day activity window.

Backlog membership is reconstructed from created_at and closed_at. Historical labels, issue types, PR draft transitions, discussion categories/answer state, and close/reopen cycles use the latest fetched state because GitHub's current-item snapshot does not contain complete timelines for those dimensions. A future incompatible dimension change should use a new prefix version rather than rewriting the existing namespace.

Metrics

All metrics are gauges and use deterministic, deduplicated tag ordering. Dashboard totals should use sum:, because each metric is split into dimension-specific series.

• github.health.v2.issues — open issues at each snapshot
• github.health.v2.prs — open, non-draft pull requests at each snapshot
• github.health.v2.discussions — open discussions at each snapshot
• github.health.v2.issues.closed — issues closed in the rolling activity window ending at each snapshot
• github.health.v2.prs.closed — pull requests closed or merged in the rolling activity window ending at each snapshot
• github.health.v2.discussions.closed — discussions closed in the rolling activity window ending at each snapshot

Closed metrics are sparse and are omitted when no matching item closed in the selected activity window.

Datadog Workflow behavior

The repository does not contain a GitHub composite action or shell wrapper for synchronization. Datadog Workflow Automation owns the trigger and schedule.

Run github-tools sync-metrics ... --output-json from Bits Code. The command performs the temporary fetch and reconstruction, then emits a compact JSON envelope with batches. Each batch is an exact request body for POST /api/v2/series; the workflow submits it through the managed Datadog Metrics API connection.

--output-json never reads a Datadog API key or submits metrics itself. Without that flag, direct CLI submission remains available for local use.

Simplification and review pass

• replace error-prone positional metric arguments with a named MetricsOptions struct
• reuse one fetch implementation instead of maintaining duplicate setup paths
• use the same --activity-window name in both metric commands
• sort and deduplicate tags before series grouping for deterministic reruns
• retain the existing data model and metric dimensions; no stable-total metrics or timeline reconstruction were added

Verification

• cargo test --locked — 6 tests passed
• cargo clippy --locked --all-targets -- -D warnings -A clippy::unnecessary-sort-by — passed (the allowed lint is pre-existing in chart generation code)
• git diff --check — passed
• offline Quickwit JSON-output validation — 650 points across 79 github.health.v2.* series, with the expected Datadog { "series": [...] } request shape
• no live metrics were submitted during this validation

A previous full run produced Quickwit metrics visible in this dashboard.