@odla-ai/cli 0.32.1 → 0.34.0

package/README.md

@@ -186,6 +186,87 @@ jobs, missing canary configuration, stale probes, and partial
 socket-reconciliation coverage remain explicit fields. Authentication progress
 is stderr-only, so stdout is a single JSON document.
 
+Repository-controlled SLO monitoring lives under `o11y.monitoring`. Objectives
+can consume Kitesurf routes or bounded observations of existing o11y error,
+latency, and protected-canary signals. A minimal route policy detects both
+short outages and sustained error-budget burn, and sends incident and digest
+email:
+
+```js
+export default {
+  services: ["o11y"],
+  links: { prod: "https://example.com" },
+  o11y: {
+    monitoring: {
+      probes: [{
+        id: "home", route: "/", envs: ["prod"], every: "5m",
+        expect: { status: 200, titleIncludes: "Example", textIncludes: ["Welcome"] },
+      }],
+      slos: [{
+        id: "availability", name: "Public availability",
+        indicator: { type: "probe-success", probes: ["home"] },
+        target: 0.999, window: "28d",
+        alerts: {
+          spike: { badChecks: 2, withinChecks: 3, recoverAfter: 2 },
+          trend: { burnRate: 1, shortWindow: "6h", longWindow: "3d", minBadChecks: 2 },
+        },
+      }],
+      notifications: {
+        prod: {
+          email: ["oncall@example.com"], timezone: "America/Costa_Rica",
+          daily: "08:00", weekly: { day: "monday", at: "08:00" },
+        },
+      },
+    },
+  },
+};
+```
+
+For a service-performance objective, omit `probes` and select an existing o11y
+metric. The comparator describes a successful observation, so this example
+requires each five-minute request p95 to be at most 500ms:
+
+```js
+slos: [{
+  id: "request-latency", name: "Request p95 at or below 500ms",
+  indicator: {
+    type: "o11y-metric", metric: "latency_p95", comparator: "lte",
+    threshold: 500, every: "5m", observationWindow: "5m",
+  },
+  target: 0.99, window: "28d",
+}]
+```
+
+`error_rate`, `latency_p95`, `synthetic_success`, and
+`synthetic_publish_to_visible` are supported. The checked-in odla-db first
+rollout is `ops/monitoring/odla-db.config.mjs`:
+
+```bash
+npx odla-ai monitor plan --config ops/monitoring/odla-db.config.mjs --env prod --json
+```
+
+Preview and apply the normalized policy, then inspect or exercise it through
+stable JSON:
+
+```bash
+npx odla-ai monitor plan --env prod --json
+npx odla-ai monitor apply --env prod --yes --json
+npx odla-ai monitor status --app <appId> --env prod --json
+npx odla-ai monitor run home --app <appId> --env prod --json
+npx odla-ai monitor incidents --app <appId> --env prod --runs --json
+npx odla-ai monitor report --app <appId> --env prod --period weekly --json
+```
+
+Only scheduled `good` and `bad` outcomes enter the application SLO denominator.
+Kitesurf failures, missing Analytics Engine evidence, stale canaries, query
+failures, and scheduler gaps are retained as `monitor_error`/`missed` and
+degrade monitoring health separately, so no traffic or a broken monitor cannot
+manufacture success or downtime. Probe responses retain bounded metadata only;
+page content and accessibility trees are never returned by the CLI or stored.
+Each applied desired-state revision starts a fresh SLO event series and closes
+open incidents as `config_revision_changed`; results produced by different
+thresholds, routes, assertions, or notification policy are never blended.
+
 For platform-wide operations, `platform status --json` requests only the
 short-lived, admin-approved `platform:status:read` capability and reads the
 same `odla.platform-status/v1` snapshot as Studio. It works outside a project