stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
822a92faeebbceea6fa005b7eddb7572a8b29b41
git.stella-ops.org/docs-archived/modules/excititor/operations/chunk-telemetry.md

1.6 KiB
Raw Blame History

Excititor Chunk Telemetry (Sprint 110)

Metrics (Meter: StellaOps.Excititor.Chunks)

  • vex_chunks_ingested_total (counter) — tags: tenant, source, status (accepted|rejected), reason (nullable for accepted). Increments per chunk submitted.
  • vex_chunks_item_count (histogram, unit=items) — records item count per chunk.
  • vex_chunks_payload_bytes (histogram, unit=bytes) — measured from NDJSON payload length.
  • vex_chunks_latency_ms (histogram) — end-to-end ingestion latency per request.

Logs

  • vex.chunk.ingest.accepted — includes chunk_id, tenant, source, item_count, chunk_digest.
  • vex.chunk.ingest.rejected — includes chunk_id, tenant, source, reason, validation errors (summarized).

Wiring steps

  1. Register ChunkTelemetry as singleton with shared Meter instance.
  2. In /vex/evidence/chunks handler, compute chunk_digest deterministically from canonical JSON and emit counters/histograms via ChunkTelemetry.
  3. Log using structured templates above; avoid request bodies in logs.
  4. Expose metrics via default ASP.NET metrics export (Prometheus/OpenTelemetry) already configured in WebService.

Determinism & offline posture

  • Do not include host-specific paths or timestamps in metric dimensions.
  • Histogram buckets: use standard OTEL defaults; no runtime-generated buckets.
  • Keep meter name stable; adding new instruments requires version note in sprint Decisions & Risks.

Ownership

  • Implementer: Excititor Observability Guild
  • Reviewers: Evidence Locker Guild (for parity with attestation metrics)