Aggregation Observability

Audience: SREs and developers operating the Link-Not-Merge (LNM) aggregation and evidence pipelines. Scope: The metrics, traces, logs, SLOs, and alerts emitted by aggregation, plus offline/air-gap operation.

Last updated: 2025-11-25

This guide documents the telemetry that Stella Ops emits for Link-Not-Merge (LNM) aggregation — the pipeline that links advisory and VEX statements into evidence without destructively merging them. Use it to build dashboards, wire alerts, and triage ingest incidents.

Metrics

• aggregation_ingest_latency_seconds (histogram) — end-to-end ingest per statement; labels: tenant, source, status.
• aggregation_conflict_total (counter) — conflicts encountered; labels: tenant, advisory, product, reason.
• aggregation_overlay_cache_hits_total / _misses_total — overlay cache effectiveness; labels: tenant, cache.
• aggregation_vex_gate_total — VEX gating outcomes; labels: tenant, status (affected, not_affected, unknown).
• aggregation_queue_depth (gauge) — pending statements per tenant.

Traces

• Span name aggregation.process with attributes:
  • tenant, advisory, product, vex_status, source_kind
  • overlay_version, cache_hit (bool)
• Link to upstream ingest span (traceparent forwarded by Excititor/Concelier).
• Export to OTLP; sampling default 10% outside prod, 100% for status=error.

Logs

Structured JSON with fields: tenant, advisory, product, vex_status, decision (merged|suppressed|dropped), reason, duration_ms, trace_id.

SLOs

• Ingest latency: p95 < 500ms per statement (steady state).
• Cache hit rate: >80% for overlays; alerts when below for 15 minutes.
• Error rate: <0.1% over 10 minute window.

Alerts

• HighConflictRate — aggregation_conflict_total delta > 100/minute per tenant.
• QueueBacklog — aggregation_queue_depth > 10k for 5 minutes.
• LowCacheHit — overlay cache hit rate < 60% for 10 minutes.

Offline/air-gap considerations

• Export metrics to a local Prometheus scrape; no external sinks.
• Trace sampling and log retention are configured via environment, without needing control-plane access.
• Deterministic ordering is preserved; cache warmers are seeded from bundled fixtures.

Related

• Metrics & SLOs — platform-wide metric families and SLO conventions.
• Telemetry Standards — the common telemetry envelope all signals share.
• Tracing Standards — span naming and W3C context propagation.
• Logging Standards — the structured-log schema referenced above.