stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity
Files
6bee1fdcf58fe6c2fd8dae6201f5f71eb504710f
git.stella-ops.org/docs/modules/concelier/operations/observation-events.md
StellaOps Bot 6bee1fdcf5
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
work
2025-11-25 08:01:23 +02:00

2.3 KiB
Raw Blame History

Observation Event Transport (advisory.observation.updated@1)

Purpose: document how to emit advisory.observation.updated@1 events via Mongo outbox with optional NATS JetStream transport.

Configuration (appsettings.yaml / config)

advisoryObservationEvents:
  enabled: false            # set true to publish beyond Mongo outbox
  transport: "mongo"        # "mongo" (no-op publisher) or "nats"
  natsUrl: "nats://127.0.0.1:4222"
  subject: "concelier.advisory.observation.updated.v1"
  deadLetterSubject: "concelier.advisory.observation.updated.dead.v1"
  stream: "CONCELIER_OBS"

Defaults: disabled, transport mongo; subject/stream as above.

Flow

  1. Observation sink writes event to advisory_observation_events (idempotent on observationHash).
  2. Background worker dequeues unpublished rows, publishes via configured transport, then stamps publishedAt.
  3. If transport disabled/unavailable, outbox accumulates safely; re-enabling resumes publishing.

Operational notes

  • Ensure NATS JetStream is reachable before enabling transport: nats to avoid retry noise.
  • Stream is auto-created if missing with current subject; size capped at 512 KiB per message.
  • Dead-letter subject reserved; not yet wired—keep for future schema validation failures.
  • Backlog monitoring: count documents in advisory_observation_events with publishedAt: null.

Testing

  • Without NATS: leave enabled=false; app continues writing outbox only.
  • With NATS: run a local nats-server -js and set enabled=true transport=nats. Verify published messages on subject via nats sub concelier.advisory.observation.updated.v1.

2025-11-25 demo review notes

  • Verified attestation demo emits StellaOps.Concelier.Advisory.Observations meter with counters events_published_total and gauges outbox_backlog. Ensure these metrics are scraped with tenant labels.
  • Backlog guard: alert if outbox_backlog > 500 for 10m while transport=nats; recommended SLO is P95 publish latency < 2s.
  • When transport disabled for air-gap runs, confirm background worker remains paused (enabled=false) to avoid noisy retries; resume only after mirror bundles restored.
  • TRX from /internal/attestations/verify suite lives at TestResults/concelier-attestation/web.trx for current demo build; keep alongside dashboards for reproducibility.