Alarms · Stellar Control

GET/v1/alarms

List alarms#

Alarms

The alarms not NORMAL or shelved, from stellar_alarms; every alarm recorded with all.

Query parameters

target

string

Only the alarms of this target.

all

boolean

Every alarm recorded, NORMAL included.

Responses

200Alarms, by key order.application/json

alarmsrequired

array of Alarm

Alarms, by key order.

Alarm · 5 fields

alarmrequired

string

Alarm: its name, or the measure of the limits.

componentrequired

string

Component.

instance

string

Component instance.

targetrequired

string

Target.

recordrequired

AlarmRecord

Current state.

AlarmRecord · 10 fields

active_since

string

Start of the activation.

by

string

Operator of the last transition, when not the condition.

cause

AlarmCause

Cause of the last transition.

changed_at

string

Last transition.

previous

AlarmState

State before the last transition.

seqrequired

integer · uint64

Number of the last transition, from 1; the transition event bears it.

≥ 0

severity

one of AlarmSeverity | null

Severity of the activation; kept while cleared and unacknowledged.

shelved_until

string

End of the shelving: until then, the alarm triggers no reaction.

staterequired

AlarmState

State.

value

any

Value of the measure at the last transition, for the alarm of its limits.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/alarms"

import requests

BASE_URL = "http://localhost:8080"

response = requests.get(f"{BASE_URL}/v1/alarms")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/alarms"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "alarms": [
    {
      "alarm": "string",
      "component": "string",
      "instance": "string",
      "target": "string",
      "record": {
        "active_since": "string",
        "by": "string",
        "cause": null,
        "changed_at": "string",
        "previous": null,
        "seq": 0,
        "severity": null,
        "shelved_until": "string",
        "state": null,
        "value": null
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/alarms/watch

Watch alarms#

Follow the alarm transitions (WebSocket)

Every transition from now, in order. Each message is an AlarmEvent.

Query parameters

target

string

Only the transitions of this target.

Responses

101WebSocket: one AlarmEvent per message.application/json

alarmrequired

string

Alarm: its name, or the measure of the limits.

atrequired

string

Time of the transition.

by

string

Operator, for an acknowledgement or a shelving.

causerequired

AlarmCause

Cause.

componentrequired

string

Component.

instance

string

Component instance.

previousrequired

AlarmState

State before.

seqrequired

integer · uint64

Number of the transition.

≥ 0

severity

one of AlarmSeverity | null

Severity of the activation.

shelved_until

string

End of the shelving in progress.

staterequired

AlarmState

State after.

targetrequired

string

Target.

value

any

Value of the measure, for the alarm of its limits.

404Invalid target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/alarms/watch"

import requests

BASE_URL = "http://localhost:8080"

response = requests.get(f"{BASE_URL}/v1/alarms/watch")
response.raise_for_status()

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/alarms/watch"))
    .send()
    .await?
    .error_for_status()?;

Response

{
  "alarm": "string",
  "at": "string",
  "by": "string",
  "cause": "condition",
  "component": "string",
  "instance": "string",
  "previous": "NORMAL",
  "seq": 0,
  "severity": "warning",
  "shelved_until": "string",
  "state": "NORMAL",
  "target": "string",
  "value": null
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/alarms/{target}/{alarm}/{action}

Command alarm#

Acknowledge, shelve or unshelve an alarm

acknowledge moves ACTIVE_UNACK to ACTIVE_ACK and CLEARED_UNACK to NORMAL; shelve silences the reactions of the alarm for a bounded duration (at most alarms.max_shelve); unshelve ends it. The command goes to the alarm service, traced with the identity of the operator.

Path parameters

targetrequired

string

Target, as named in the topology (sim-1).

alarmrequired

string

Alarm: tcu[TCU1].anode_voltage, or eps.undervoltage without instance.

actionrequired

string

acknowledge, shelve or unshelve.

Request body application/json

For shelve only: its duration.

one of Shelve | null

Responses

202Command applied.

400Invalid body, or no identity: api::anonymous.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

404Invalid target or alarm, or unknown command.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409Refused: nothing to acknowledge, alarm not shelved or never recorded, duration out of bounds (alarm::refused).application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503No alarm service is running: alarm::no-service.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

504The alarm service did not answer: alarm::timeout.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/alarms/<target>/<alarm>/<action>" \
  -H "Content-Type: application/json" \
  -d '{
  "for": "30 min"
}' \
  -o response.bin

import requests

BASE_URL = "http://localhost:8080"
target = "<target>"  # Target, as named in the topology (`sim-1`).
alarm = "<alarm>"  # Alarm: `tcu[TCU1].anode_voltage`, or `eps.undervoltage` without instance.
action = "<action>"  # `acknowledge`, `shelve` or `unshelve`.

response = requests.post(
    f"{BASE_URL}/v1/alarms/{target}/{alarm}/{action}",
    json={
        "for": "30 min",
    },
)
response.raise_for_status()
data = response.content

let base_url = "http://localhost:8080";
let target = "<target>"; // Target, as named in the topology (`sim-1`).
let alarm = "<alarm>"; // Alarm: `tcu[TCU1].anode_voltage`, or `eps.undervoltage` without instance.
let action = "<action>"; // `acknowledge`, `shelve` or `unshelve`.

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/alarms/{target}/{alarm}/{action}"))
    .json(&serde_json::json!({
      "for": "30 min"
    }))
    .send()
    .await?
    .error_for_status()?;
let bytes = response.bytes().await?;

Response

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}