ContextEvent Schema

A ContextEvent is the fundamental unit of data in Noctuary — a single structured signal extracted from a raw log line by a vendor plugin.

Full schema

{
  "service_name":  "payments-api",
  "vendor":        "argocd",
  "entity":        "payments-api",
  "event_type":    "deploy",
  "old_value":     null,
  "new_value":     "syncing:a4f2c1",
  "actor":         "ci/cd pipeline",
  "sha":           "a4f2c1",
  "confidence":    0.97,
  "ttl_seconds":   3600,
  "timestamp":     "2026-05-31T02:10:41Z",
  "raw_line":      "time=\"2026-05-31T02:10:41Z\" level=info msg=\"Sync operation starting\" app=payments-api revision=a4f2c1"
}

Field reference

Field	Type	Required	Description
service_name	string	Yes	Maps to OTel service.name. Used to group events by service.
vendor	string	Yes	The plugin that detected this event: argocd, kubernetes, postgres
entity	string	Yes	The specific resource: app name, pod name, table name, flag name
event_type	string	Yes	Semantic event category — see below
old_value	string	No	Previous state. For deploys: previous SHA. For flags: previous value.
new_value	string	No	New state. For deploys: new SHA. For restarts: exit reason.
actor	string	No	What triggered the change: ci/cd pipeline, username, automated process
sha	string	No	Git commit SHA for deploy events
confidence	float	Yes	Plugin confidence: 0.0 < x <= 1.0. Events below the agent's confidence_threshold are discarded.
ttl_seconds	integer	Yes	How long this event remains relevant. After ttl_seconds, it is removed from the state window.
timestamp	string	No	ISO 8601 UTC. Defaults to server receipt time if omitted.
raw_line	string	No	Original log line. Stored locally in the database for audit — never retransmitted.

Event types

Type	Typical vendor	Description
deploy	argocd	Application sync or deployment started or completed
restart	kubernetes	Pod restarted: OOMKill, CrashLoopBackOff, probe failure
saturation	postgres, kubernetes	Resource exhausted: deadlock, connection pool, memory
flag_change	any	Feature flag toggled
circuit_open	any	Circuit breaker opened
dependency_failure	any	Downstream dependency became unavailable

TTL guidance

The TTL controls how long an event is considered relevant for incident correlation. Set it based on how long the event could plausibly be a cause:

Event type	Recommended TTL
Deploy	3600s (1 hour) — most deploy-caused incidents surface within an hour
Config change	7200s (2 hours)
OOMKill / restart	900s (15 minutes) — symptom rather than cause
Deadlock	1800s (30 minutes)
Feature flag change	7200s (2 hours)

Events with very short TTLs may not correlate correctly with later incidents. Events with very long TTLs may produce false correlations.