Get an event rule

GET

/event-rules/{name}

const url = 'https://example.com/api/v1/event-rules/example';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/v1/event-rules/example

Returns one event rule by name, with its live state as counts over the components the caller may read. Gated by rule:read.

Parameters

Path Parameters

name

required

The rule’s name

string

The rule’s name

Responses

200

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

clear_criteria

When the sample meets this for clear_sustain, the condition ends (and the alarm clears); absent, the negation of fire_criteria

object

expr

required

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”

string

clear_event_type

The event type the rule writes when its condition ends, by name; absent, it writes none

string

clear_sustain

required

How long the clear criteria must hold, a Go duration

string

conditions_in_force

required

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)

integer format: int64

criteria_error

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

code

The registered diagnostic that gave it, when one did (documented on the expressions page)

string

column

The 1-based column of the fault, when it has one

integer format: int64

field

required

Which criteria

string

Allowed values: fire_criteria clear_criteria

line

The 1-based line of the fault, when it has one

integer format: int64

message

required

string

criteria_warnings

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

Array<object> | null

object

code

The registered diagnostic that gave it, when one did (documented on the expressions page)

string

column

The 1-based column of the fault, when it has one

integer format: int64

field

required

Which criteria

string

Allowed values: fire_criteria clear_criteria

line

The 1-based line of the fault, when it has one

integer format: int64

message

required

string

description

string

enabled

required

boolean

fire_criteria

required

When the sample meets this for fire_sustain, the rule’s condition starts (and it opens an alarm when it names a severity)

object

expr

required

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”

string

fire_event_type

required

The event type the rule writes when its condition starts, by name

string

fire_sustain

required

How long the fire criteria must hold, a Go duration (0s fires at once)

string

required

The rule’s uuid, the stable form of name

string

label

string

last_judged_at

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

string format: date-time

message

The alarm’s message; empty uses the rule’s label or name

string

name

required

string

official

required

Shipped with the platform and read-only

boolean

open_alarms

required

How many alarms the rule raised are still open right now (its live state; GET /event-rules/{name}/state lists them)

integer format: int64

pending_streaks

required

How many of the rule’s streaks are waiting out a sustain right now

integer format: int64

sample_key

required

The property or metric the rule reads

string

sample_lane

required

Which lane the key reads, derived from the registries

string

Allowed values: property metric

selector

required

The components the rule watches; both lists empty is every component

object

component_types

Watch components whose type falls within one of these component types

Array<string> | null

components

Watch these components (by name or id on write; ids on read)

Array<string> | null

severity

The severity level the alarm is raised at, by name; absent, the rule is informational and raises no alarm

string

version

required

Bumps on every update

integer format: int64

Example

{
  "$schema": "/api/v1/schemas/EventRuleBody.json",
  "criteria_error": {
    "field": "fire_criteria"
  },
  "criteria_warnings": [
    {
      "field": "fire_criteria"
    }
  ],
  "sample_lane": "property"
}

default

Error

application/problem+json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

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"
}