Raise an alarm on a component

POST

/components/{name}/alarms

curl --request POST \
  --url https://example.com/api/v1/components/example/alarms \
  --header 'Content-Type: application/json' \
  --data '{ "dedup_key": "example", "message": "example", "severity": "example" }'

Records a condition on this component, then recomputes health in the same transaction: the component’s own verdict moves, and if it is now outage (an alarm at or above the high level), any role it occupies loses it as an occupant while the alarm is active, which can move its system and location verdicts with it; a lesser alarm degrades the component but leaves it occupying its roles. Gated by component:update; read and update scopes drive the 404 versus 403 split.

Parameters

Path Parameters

name

required

The component’s name, or a dotted address (e.g. boi.17c.415a.$comp.display-1)

string

The component’s name, or a dotted address (e.g. boi.17c.415a.$comp.display-1)

Request Body ^required

Media type application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

dedup_key

The condition identity; defaults to the message. Raising an already-open (component, dedup_key) returns the existing open alarm instead of a duplicate. A key (or, without one, a message) beginning rule: is refused (422): that namespace names a rule’s condition

string

message

What is wrong, for the operator reading it later

string

severity

required

How bad it is: a severity level by name (see /severity-levels); a level at or above high puts the component itself in outage

string

>= 1 characters

Responses

201

Created

Media type application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

acknowledged

required

Whether anybody has recorded seeing this alarm; says nothing about whether it is still raised

boolean

acknowledged_at

When a human first recorded seeing this alarm; null while nobody has. Independent of cleared_at

string format: date-time

acknowledged_by

Who acknowledged it, by name; empty while unacknowledged, or once that principal has been purged (the audit log keeps the name)

string

active

required

boolean

cleared_at

Null while the alarm is active

string format: date-time

component

required

The component the alarm is on, by name

string

component_id

required

The component’s uuid, the stable form of component

string

dedup_key

required

The condition identity: one open alarm per (component, dedup_key)

string

id

required

string

message

required

string

raised_at

required

string format: date-time

raised_by_rule

The event rule that raised the alarm, by name; absent when an operator raised it

string

raised_by_rule_id

The raising rule’s uuid

string

severity

required

The severity level the alarm was raised at, by name (see /severity-levels)

string

Example

{
  "$schema": "/api/v1/schemas/AlarmBody.json"
}

default

Error

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