feat(alerting): AGENT_LIFECYCLE condition kind with per-subject fire mode
Allows alert rules to fire on agent-lifecycle events — REGISTERED,
RE_REGISTERED, DEREGISTERED, WENT_STALE, WENT_DEAD, RECOVERED — rather
than only on current state. Each matching `(agent, eventType, timestamp)`
becomes its own ackable AlertInstance, so outages on distinct agents are
independently routable.
Core:
- New `ConditionKind.AGENT_LIFECYCLE` + `AgentLifecycleCondition` record
(scope, eventTypes, withinSeconds). Compact ctor rejects empty
eventTypes and withinSeconds<1.
- Strict allowlist enum `AgentLifecycleEventType` (six entries matching
the server-emitted types in `AgentRegistrationController` and
`AgentLifecycleMonitor`). Custom agent-emitted event types tracked in
backlog issue #145.
- `AgentEventRepository.findInWindow(env, appSlug, agentId, eventTypes,
from, to, limit)` — new read path ordered `(timestamp ASC, insert_id
ASC)` used by the evaluator. Implemented on
`ClickHouseAgentEventRepository` with tenant + env filter mandatory.
App:
- `AgentLifecycleEvaluator` queries events in the last `withinSeconds`
window and returns `EvalResult.Batch` with one `Firing` per row.
Every Firing carries a canonical `_subjectFingerprint` of
`"<agentId>:<eventType>:<tsMillis>"` in context plus `agent` / `event`
subtrees for Mustache templating.
- `NotificationContextBuilder` gains an `AGENT_LIFECYCLE` branch that
exposes `{{agent.id}}`, `{{agent.app}}`, `{{event.type}}`,
`{{event.timestamp}}`, `{{event.detail}}`.
- Validation is delegated to the record compact ctor + enum at Jackson
deserialization time — matches the existing policy of keeping
controller validators focused on env-scoped / SQL-injection concerns.
Schema:
- V16 migration generalises the V15 per-exchange discriminator on
`alert_instances_open_rule_uq` to prefer `_subjectFingerprint` with a
fallback to the legacy `exchange.id` expression. Scalar kinds still
resolve to `''` and keep one-open-per-rule. Duplicate-key path in
`PostgresAlertInstanceRepository.save` is unchanged — the index is
the deduper.
UI:
- New `AgentLifecycleForm.tsx` wizard form with multi-select chips for
the six allowed event types + `withinSeconds` input. Wired into
`ConditionStep`, `form-state` (validation + defaults: WENT_DEAD,
300 s), and `enums.ts` options. Tests in `enums.test.ts` pin the
new option array.
- `alert-variables.ts` registers `{{agent.app}}`, `{{event.type}}`,
`{{event.timestamp}}`, `{{event.detail}}` leaves for the new kind,
and extends `agent.id`'s availability list to include `AGENT_LIFECYCLE`.
Tests (all passing):
- 5 new JSON-roundtrip cases on `AlertConditionJsonTest` (positive +
empty/zero/unknown-type rejection).
- 5 new evaluator unit tests on `AgentLifecycleEvaluatorTest` (empty
window, multi-agent fingerprint shape, scope forwarding, missing env).
- `NotificationContextBuilderTest` switch now covers the new kind.
- 119 alerting unit tests + 71 UI tests green.
Docs: `.claude/rules/{core,app,ui}` and CLAUDE.md migration list updated.
2026-04-21 14:52:08 +02:00
|
|
|
{"openapi":"3.1.0","info":{"title":"Cameleer Server API","version":"1.0"},"servers":[{"url":"/api/v1","description":"Relative"}],"security":[{"bearer":[]}],"tags":[{"name":"Route Metrics","description":"Route performance metrics (env-scoped)"},{"name":"Database Admin","description":"Database monitoring and management (ADMIN only)"},{"name":"Threshold Admin","description":"Monitoring threshold configuration (ADMIN only)"},{"name":"Agent Commands","description":"Command push endpoints for agent communication"},{"name":"Agent List","description":"List registered agents in an environment"},{"name":"Sensitive Keys Admin","description":"Global sensitive key masking configuration (ADMIN only)"},{"name":"License Admin","description":"License management"},{"name":"Role Admin","description":"Role management (ADMIN only)"},{"name":"RBAC Stats","description":"RBAC statistics (ADMIN only)"},{"name":"OIDC Config Admin","description":"OIDC provider configuration (ADMIN only)"},{"name":"Alerts Inbox","description":"In-app alert inbox, ack and read tracking (env-scoped)"},{"name":"Application Config","description":"Per-application observability configuration (user-facing)"},{"name":"App Management","description":"Application lifecycle and JAR uploads (env-scoped)"},{"name":"Catalog","description":"Unified application catalog"},{"name":"ClickHouse Admin","description":"ClickHouse monitoring and diagnostics (ADMIN only)"},{"name":"Alert Silences","description":"Alert silence management (env-scoped)"},{"name":"Ingestion","description":"Data ingestion endpoints"},{"name":"Group Admin","description":"Group management (ADMIN only)"},{"name":"Usage Analytics","description":"UI usage pattern analytics"},{"name":"Alert Notifications","description":"Outbound webhook notification management"},{"name":"Deployment Management","description":"Deploy, stop, promote, and view logs"},{"name":"Detail","description":"Execution detail and processor snapshot endpoints"},{"name":"Outbound Connections Admin","description":"Admin-managed outbound HTTPS destinations"},{"name":"Agent Config","description":"Agent-authoritative config read (AGENT only)"},{"name":"User Admin","description":"User management (ADMIN only)"},{"name":"Agent Management","description":"Agent registration and lifecycle endpoints"},{"name":"Authentication","description":"Login and token refresh endpoints"},{"name":"Agent Events","description":"Agent lifecycle event log (env-scoped)"},{"name":"Route Catalog","description":"Route catalog and discovery (env-scoped)"},{"name":"Application Logs","description":"Query application logs (env-scoped)"},{"name":"Agent SSE","description":"Server-Sent Events endpoint for agent communication"},{"name":"Search","description":"Transaction search and stats (env-scoped)"},{"name":"Audit Log","description":"Audit log viewer (ADMIN only)"},{"name":"Claim Mapping Admin","description":"Manage OIDC claim-to-role/group mapping rules"},{"name":"Diagrams","description":"Diagram rendering endpoints"},{"name":"Environment Admin","description":"Environment management (ADMIN only)"},{"name":"App Settings","description":"Per-application dashboard settings (ADMIN/OPERATOR)"},{"name":"Alert Rules","description":"Alert rule management (env-scoped)"}],"paths":{"/environments/{envSlug}/apps/{appSlug}/settings":{"get":{"tags":["App Settings"],"summary":"Get settings for an application in this environment (returns defaults if not configured)","operationId":"getByAppId","parameters":[{"name":"env","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Environment"}},{"name":"appSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AppSettings"}}}}}},"put":{"tags":["App Settings"],"summary":"Create or update settings for an application in this environment","operationId":"update","parameters":[{"name":"env","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Environment"}},{"name":"appSlug","in":"path","required":true,"schema":{"type":"string"}}],"re
|