Skip to content
Omniglass Omniglass Omniglass

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": "info" }'

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 (a critical alarm), 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 (info or warning) 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

Section titled “ Parameters ”

Path Parameters

Section titled “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

Section titled “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

string
message

What is wrong, for the operator reading it later

string
severity
required

How bad it is; critical puts the component itself in outage

string
Allowed values: info warning critical

Responses

Section titled “ Responses ”

201

Section titled “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
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
severity
required

Info, warning, or critical

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

default

Section titled “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"
}