V1 Instrumentation: Prometheus metrics, alerting, and log retention #16

New Issue

2026-09-01T23:48:13Z

Ty commented

2026-09-01 23:48:13 +00:00

Summary

V1 instrumentation tier — additive on top of the POC tier (structured JSON logging, request IDs, real health checks, inference timing, queryable sync/inference logs). This issue is explicitly V1-scoped, not a POC gate.

Scope

1. Prometheus metrics endpoint

Add a GET /metrics endpoint in Prometheus exposition format.
Core metrics:
- Request counts and latencies by route (capture, review, submit, taxonomy sync, inference).
- U2Net inference duration (when the fallback path is enabled post-POC).
- WooCommerce call duration and error rate.
- Cache hit/miss and anchor-bump counts for the taxonomy refresh logic.
- Error rates by category (API failure, validation, Woo rejection).

2. Alerting path

Wire a cheap alerting path — a webhook to Hermes or a simple uptime check is sufficient.
Alert on: health endpoint failure, Woo call error rate above threshold, disk usage on the image volume, and container restart loops.

3. Log retention policy

Define retention for the json-file Docker driver (POC sets max-size/max-file; V1 formalizes the policy and documents rotation behavior).
Ensure logs survive container restarts without unbounded disk growth on a small self-hosted host.

Non-goals (deferred to nice-to-have)

Distributed tracing across phone-to-server-to-Woo hops.
Error-tracking service (e.g. Sentry).
Dashboarding.

Acceptance criteria

/metrics endpoint returns valid Prometheus text format and is scrapeable.
At least the core metrics above are emitted with correct labels.
An alerting path is configured and tested (even if the alert target is a no-op webhook initially).
Log retention policy is documented in DEPLOYMENT.md and enforced via Docker driver config.
POC instrumentation remains intact and unchanged; this tier only adds.

Branch

Linked to docs/refactor-v2.

## Summary V1 instrumentation tier — additive on top of the POC tier (structured JSON logging, request IDs, real health checks, inference timing, queryable sync/inference logs). This issue is explicitly **V1-scoped**, not a POC gate. ## Scope ### 1. Prometheus metrics endpoint - Add a `GET /metrics` endpoint in Prometheus exposition format. - Core metrics: - Request counts and latencies by route (capture, review, submit, taxonomy sync, inference). - U2Net inference duration (when the fallback path is enabled post-POC). - WooCommerce call duration and error rate. - Cache hit/miss and anchor-bump counts for the taxonomy refresh logic. - Error rates by category (API failure, validation, Woo rejection). ### 2. Alerting path - Wire a cheap alerting path — a webhook to Hermes or a simple uptime check is sufficient. - Alert on: health endpoint failure, Woo call error rate above threshold, disk usage on the image volume, and container restart loops. ### 3. Log retention policy - Define retention for the json-file Docker driver (POC sets max-size/max-file; V1 formalizes the policy and documents rotation behavior). - Ensure logs survive container restarts without unbounded disk growth on a small self-hosted host. ## Non-goals (deferred to nice-to-have) - Distributed tracing across phone-to-server-to-Woo hops. - Error-tracking service (e.g. Sentry). - Dashboarding. ## Acceptance criteria - `/metrics` endpoint returns valid Prometheus text format and is scrapeable. - At least the core metrics above are emitted with correct labels. - An alerting path is configured and tested (even if the alert target is a no-op webhook initially). - Log retention policy is documented in DEPLOYMENT.md and enforced via Docker driver config. - POC instrumentation remains intact and unchanged; this tier only adds. ## Branch Linked to `docs/refactor-v2`.

Ty added this to the V1 milestone 2026-09-01 23:49:01 +00:00

grokbot_ty added the post-launch label 2026-09-24 16:24:54 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Ty_Tech/SlabUploader#16