Create an event rule
const url = 'https://example.com/api/v1/event-rules';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"clear_criteria":{"expr":"example","op":"eq","value":"example"},"clear_event_type":"example","clear_sustain":"example","description":"example","enabled":true,"fire_criteria":{"expr":"example","op":"eq","value":"example"},"fire_event_type":"example","fire_sustain":"example","label":"example","message":"example","name":"example","sample_key":"example","selector":{"component_types":["example"],"components":["example"]},"severity":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/event-rules \ --header 'Content-Type: application/json' \ --data '{ "clear_criteria": { "expr": "example", "op": "eq", "value": "example" }, "clear_event_type": "example", "clear_sustain": "example", "description": "example", "enabled": true, "fire_criteria": { "expr": "example", "op": "eq", "value": "example" }, "fire_event_type": "example", "fire_sustain": "example", "label": "example", "message": "example", "name": "example", "sample_key": "example", "selector": { "component_types": [ "example" ], "components": [ "example" ] }, "severity": "example" }'Authors a rule whose condition starts on each component it watches when its sample key meets the fire criteria for the fire sustain, and ends when the clear criteria (or the negation of fire) holds for the clear sustain. It names the event type it writes when the condition starts (required) and, optionally, when it ends; with a severity it also raises an alarm while the condition holds, and without one it is informational. Criteria are expressions over the sample (value, key, instance, component.name, component.type) yielding true or false; a body may give {expr} or the short form {op, value}, and the answer is always {expr}. The key must be a registered property or metric, the criteria must compile against its lane (an unknown name or a result that is not a bool is a 422 naming the criteria, line and column), the event types registered and the severity, when given, a level that exists (else 422); a name already taken is a 409. Audited. Gated by rule:create, with an all-scope grant.
Request Body required
Section titled “Request Body required ”object
A URL to the JSON Schema for this object.
The criteria that ends it: {expr} or {op, value}; absent clears on the negation of fire_criteria, !(fire)
object
The criterion as an expression over the sample (value, key, instance, component.name, component.type), yielding true or false; give this or op and value
The short form’s comparison: a property compares text with eq or ne; a metric compares numbers with any of them
The short form’s threshold: text for a property, a number for a metric
The event type the rule writes when its condition ends, by name (condition-ended is the generic one); absent, it writes none
A Go duration; empty is 0s
What the rule watches for and why
Defaults to true
The criteria that starts the condition: {expr}, or the short form {op, value}
object
The criterion as an expression over the sample (value, key, instance, component.name, component.type), yielding true or false; give this or op and value
The short form’s comparison: a property compares text with eq or ne; a metric compares numbers with any of them
The short form’s threshold: text for a property, a number for a metric
The event type the rule writes when its condition starts, by name (condition-started is the generic one)
A Go duration; empty is 0s
A human label; also the alarm message when message is empty
The alarm message; empty uses the label or the name
The rule’s name (lowercase kebab)
The property or metric the rule reads
The components the rule watches (component types and components); absent is every component
object
Watch components whose type falls within one of these component types
Watch these components (by name or id on write; ids on read)
The severity level the alarm is raised at, by name; absent or empty, the rule is informational and raises no alarm
Responses
Section titled “ Responses ”Created
object
A URL to the JSON Schema for this object.
When the sample meets this for clear_sustain, the condition ends (and the alarm clears); absent, the negation of fire_criteria
object
The criterion, an expression over the sample (value, key, instance, component.name, component.type) that yields true or false, e.g. value > 80 && instance != “aux”
The event type the rule writes when its condition ends, by name; absent, it writes none
How long the clear criteria must hold, a Go duration
How many conditions the rule holds in force right now, one per component and instance, whether or not it raises an alarm (GET /event-rules/{name}/state lists them)
Why the rule’s stored criteria do not compile (its key’s data type changed under them, a row the backfill left in short form, or an expression a newer diagnostic refuses); absent when they compile. While present the rule holds: it judges nothing
object
The registered diagnostic that gave it, when one did (documented on the expressions page)
The 1-based column of the fault, when it has one
Which criteria
The 1-based line of the fault, when it has one
The warnings the stored criteria compile with (a likely mistake, such as == against a decimal), each with its code; notes only, never a fault: the rule judges all the same
object
The registered diagnostic that gave it, when one did (documented on the expressions page)
The 1-based column of the fault, when it has one
Which criteria
The 1-based line of the fault, when it has one
When the sample meets this for fire_sustain, the rule’s condition starts (and it opens an alarm when it names a severity)
object
The criterion, an expression over the sample (value, key, instance, component.name, component.type) that yields true or false, e.g. value > 80 && instance != “aux”
The event type the rule writes when its condition starts, by name
How long the fire criteria must hold, a Go duration (0s fires at once)
The rule’s uuid, the stable form of name
When an ingested sample was last judged by the rule, to within 5s; absent when it never has been. A fleet-wide fact about the rule, naming no component
The alarm’s message; empty uses the rule’s label or name
Shipped with the platform and read-only
How many alarms the rule raised are still open right now (its live state; GET /event-rules/{name}/state lists them)
How many of the rule’s streaks are waiting out a sustain right now
The property or metric the rule reads
Which lane the key reads, derived from the registries
The components the rule watches; both lists empty is every component
object
Watch components whose type falls within one of these component types
Watch these components (by name or id on write; ids on read)
The severity level the alarm is raised at, by name; absent, the rule is informational and raises no alarm
Bumps on every update
Example
{ "$schema": "/api/v1/schemas/EventRuleBody.json", "criteria_error": { "field": "fire_criteria" }, "criteria_warnings": [ { "field": "fire_criteria" } ], "sample_lane": "property"}default
Section titled “default ”Error
object
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
object
Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{ "$schema": "/api/v1/schemas/ErrorModel.json", "detail": "Property foo is required but is missing.", "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "about:blank"}