Summary
Structured logging is present in sync-digitalocean-openapi.ts at operation boundaries with stable contextual fields (pin, URLs, paths, hash, elapsedMs), but critical operational metrics, alerting definitions, and log-pattern documentation are absent.
Problem
Without metrics and documented failure patterns, operators cannot:
- Track success/failure rates for the refresh command over time.
- Identify latency regressions in archive download or Redocly bundling.
- Observe archive size distribution across upstream pin changes.
- Define actionable alerts for failure modes such as archive download timeout, tar extraction failure, or provenance hash mismatch.
- Diagnose production failures from logs alone without a reference log-pattern guide.
Required work
- Add metrics collection for operation success/failure rates, latency histograms, and archive size distribution to
sync-digitalocean-openapi.ts.
- Define alerts for the following failure modes: archive download timeout, tar extraction failure, provenance mismatch.
- Document expected log patterns and failure-diagnosis steps in
docs/developers-guide.md (section 8, DigitalOcean OpenAPI artefact refresh).
Context
Identified during review of PR #8 (Add pinned DigitalOcean OpenAPI artefact 1.3.1).
Raised by @leynos.
Summary
Structured logging is present in
sync-digitalocean-openapi.tsat operation boundaries with stable contextual fields (pin, URLs, paths, hash,elapsedMs), but critical operational metrics, alerting definitions, and log-pattern documentation are absent.Problem
Without metrics and documented failure patterns, operators cannot:
Required work
sync-digitalocean-openapi.ts.docs/developers-guide.md(section 8, DigitalOcean OpenAPI artefact refresh).Context
Identified during review of PR #8 (Add pinned DigitalOcean OpenAPI artefact 1.3.1).
Raised by @leynos.