Alarm

Documentation for the Alarms service in Magistrala, including alarm structure and API endpoints.

The Alarms service in Magistrala allows users to create alarms triggered by threshold conditions defined in the Rules Engine. When a rule is triggered, the system generates an alarm with relevant information. The documentation below highlights the basic structure of an alarm and how to interact with the alarms service API.

Core concepts

Basic Alarm Structure

The alarm struct is defined as shown below:

type Alarm struct {
    ID             string    `json:"id"`
    RuleID         string    `json:"rule_id"`
    DomainID       string    `json:"domain_id"`
    ChannelID      string    `json:"channel_id"`
    ClientID       string    `json:"client_id"`
    Subtopic       string    `json:"subtopic"`
    Status         Status    `json:"status"` // uint8
    Measurement    string    `json:"measurement"`
    Value          string    `json:"value"`
    Unit           string    `json:"unit"`
    Threshold      string    `json:"threshold"`
    Cause          string    `json:"cause"`
    Severity       uint8     `json:"severity"`
    AssigneeID     string    `json:"assignee_id"`
    CreatedAt      time.Time `json:"created_at"`
    UpdatedAt      time.Time `json:"updated_at"`
    UpdatedBy      string    `json:"updated_by"`
    AssignedAt     time.Time `json:"assigned_at,omitempty"`
    AssignedBy     string    `json:"assigned_by,omitempty"`
    AcknowledgedAt time.Time `json:"acknowledged_at,omitempty"`
    AcknowledgedBy string    `json:"acknowledged_by,omitempty"`
    ResolvedAt     time.Time `json:"resolved_at,omitempty"`
    ResolvedBy     string    `json:"resolved_by,omitempty"`
    Metadata       Metadata  `json:"metadata,omitempty"` //map[string]any
}

Field	Type	Description	Required
id	string	Unique identifier of the alarm	✅ (generated by system)
rule_id	string	ID of the rule that triggered the alarm	✅ (added by system)
domain_id	string	ID of the domain this alarm belongs to	✅ (added by system)
channel_id	string	ID of the channel related to the alarm	✅ (added by system)
client_id	string	ID of the client associated with the alarm	✅ (added by system)
subtopic	string	Subtopic of the message that triggered the alarm	❌
status	string	Current status of the alarm (e.g., active, cleared)	❌
measurement	string	Name of the measurement involved in the alarm condition	✅
value	string	Value that triggered the alarm	✅
unit	string	Unit of the measurement value	❌
threshold	string	Threshold value set in the rule that triggered the alarm	✅
cause	string	Explanation of why the alarm was triggered	✅
severity	uint8	Severity level of the alarm (e.g., 1 = low, 5 = critical)	✅
assignee_id	string	ID of the user assigned to resolve the alarm	❌
created_at	time.Time	Timestamp when the alarm was created	❌
updated_at	time.Time	Timestamp when the alarm was last updated	❌
updated_by	string	ID of the user who last updated the alarm	❌
assigned_at	time.Time	Timestamp when the alarm was assigned	❌
assigned_by	string	ID of the user who assigned the alarm	❌
acknowledged_at	time.Time	Timestamp when the alarm was acknowledged	❌
acknowledged_by	string	ID of the user who acknowledged the alarm	❌
resolved_at	time.Time	Timestamp when the alarm was resolved	❌
resolved_by	string	ID of the user who resolved the alarm	❌
metadata	Metadata	Additional metadata related to the alarm	❌

Alarm Status

The status field in the Alarm struct indicates the current state of the alarm. The possible statuses are defined as follows:

0 - Active: The alarm is currently active and requires attention.
1 - Cleared: The condition that triggered the alarm has been resolved.

Severity Levels

The severity field indicates the importance of the alarm. The severity levels are user defined and can range from low to critical (e.g., 1 to 5).

Alarm API Endpoints

The Alarms service provides the following API endpoints for managing alarms:

Creating an Alarm

Alarm is creation is handled by the rules engine. This is done by creating a rule whose output is an alarm. When the threshold condition defined by the rule is met, an alarm is automatically generated.

To create a rule that generates alarms, refer to the Rules Engine documentation.

Or simply:

Example command:

curl --location 'http://localhost:9008/<domain_id>/rules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '{
  "name": "water_volume_monitor",
  "input_channel": "<channel_id>",
  "input_topic": "water_volume",
  "logic": {
    "type": 0,
    "value": "function logicFunction()\n  local results = {}\n  local threshold = 20000\n\n  for _, msg in ipairs(message.payload) do\n    local value = msg.v\n    local severity\n    local cause\n\n    if value >= threshold * 1.5 then\n      severity = 5\n      cause = \"Critical level exceeded\"\n    elseif value >= threshold * 1.2 then\n      severity = 4\n      cause = \"High level detected\"\n    elseif value >= threshold then\n      severity = 3\n      cause = \"Threshold reached\"\n    end\n\n    table.insert(results, {\n      measurement = msg.n,\n      value = tostring(value),\n      threshold = tostring(threshold),\n      cause = cause,\n      unit = msg.unit,\n      severity = severity\n    })\n  end\n\n  return results\nend\nreturn logicFunction()"
  },
  "outputs": [
    {
      "type": "alarms"
    }
  ]
}'

The above command creates a rule that monitors water volume messages and generates alarms when certain thresholds are exceeded.

Listing Alarms

To retrieve a list of alarms, you can use the following API endpoint:

curl --location 'http://localhost:8050/<domain_id>/alarms' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

This command fetches all alarms associated with the specified domain. The expected reponse is as shown below:

{
    "offset": 0,
    "limit": 10,
    "total": 3,
    "alarms": [
        {
            "id": "721d7925-148c-4003-8fa0-e15af4493976",
            "rule_id": "4165e5ac-c85b-4e8d-b389-13fcb6fd6aae",
            "domain_id": "f93c0da3-d436-42a0-ac93-d2c96f80187a",
            "channel_id": "cd4126f5-8f4a-4b2e-a0f7-7d727f6fc96f",
            "client_id": "6fccdb77-6304-4960-84a5-5a42764c21d3",
            "subtopic": "water_volume",
            "status": "active",
            "measurement": "volume",
            "value": "30001",
            "unit": "",
            "threshold": "20000",
            "cause": "Critical level exceeded",
            "severity": 5,
            "assignee_id": "",
            "created_at": "2026-01-22T14:02:01.360386Z",
            "updated_at": "0001-01-01T00:00:00Z",
            "updated_by": "",
            "assigned_at": "0001-01-01T00:00:00Z",
            "acknowledged_at": "0001-01-01T00:00:00Z",
            "resolved_at": "0001-01-01T00:00:00Z"
        },
        {
            "id": "4231e5d7-9d31-4285-942c-a297a61c1952",
            "rule_id": "4165e5ac-c85b-4e8d-b389-13fcb6fd6aae",
            "domain_id": "f93c0da3-d436-42a0-ac93-d2c96f80187a",
            "channel_id": "cd4126f5-8f4a-4b2e-a0f7-7d727f6fc96f",
            "client_id": "6fccdb77-6304-4960-84a5-5a42764c21d3",
            "subtopic": "water_volume",
            "status": "active",
            "measurement": "volume",
            "value": "24001",
            "unit": "",
            "threshold": "20000",
            "cause": "High level detected",
            "severity": 4,
            "assignee_id": "",
            "created_at": "2026-01-22T14:01:41.544936Z",
            "updated_at": "0001-01-01T00:00:00Z",
            "updated_by": "",
            "assigned_at": "0001-01-01T00:00:00Z",
            "acknowledged_at": "0001-01-01T00:00:00Z",
            "resolved_at": "0001-01-01T00:00:00Z"
        }
       ...
    ]
}

The following query parameters can be used to filter and paginate the results:

Query Parameter	Type	Description
offset	int	The starting point for the list of alarms (default: 0).
limit	int	The maximum number of alarms to return (default: 10).
domain_id	string	Filter alarms by their domain ID.
channel_id	string	Filter alarms by their channel ID.
client_id	string	Filter alarms by their client ID.
subtopic	string	Filter alarms by their subtopic.
rule_id	string	Filter alarms by their rule ID.
status	string	Filter alarms by their status (e.g., active, cleared).
assignee_id	string	Filter alarms by the ID of the assigned user.
severity	int	Filter alarms by their severity level.
updated_by	string	Filter alarms by the ID of the user who last updated them.
assigned_by	string	Filter alarms by the ID of the user who assigned them.
acknowledged_by	string	Filter alarms by the ID of the user who acknowledged them.
resolved_by	string	Filter alarms by the ID of the user who resolved them
created_from	string	Filter alarms created after the specified timestamp (RFC3339 format).
created_to	string	Filter alarms created before the specified timestamp (RFC3339 format).
order	string	Specify the criteria to order the results e.g `updated_by`
dir	string	Specify the direction of results based on creation time (`asc` for ascending, `desc` for descending).

Retrieving a Specific Alarm

To retrieve details of a specific alarm by its ID, use the following API endpoint:

curl --location 'http://localhost:8050/<domain_id>/alarms/<alarm_id>' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

This command fetches the details of the alarm with the specified ID. The expected response is as shown below:

{
  "id": "721d7925-148c-4003-8fa0-e15af4493976",
  "rule_id": "4165e5ac-c85b-4e8d-b389-13fcb6fd6aae",
  "domain_id": "f93c0da3-d436-42a0-ac93-d2c96f80187a",
  "channel_id": "cd4126f5-8f4a-4b2e-a0f7-7d727f6fc96f",
  "client_id": "6fccdb77-6304-4960-84a5-5a42764c21d3",
  "subtopic": "water_volume",
  "status": "active",
  "measurement": "volume",
  "value": "30001",
  "unit": "",
  "threshold": "20000",
  "cause": "Critical level exceeded",
  "severity": 5,
  "assignee_id": "",
  "created_at": "2026-01-22T14:02:01.360386Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "updated_by": "",
  "assigned_at": "0001-01-01T00:00:00Z",
  "acknowledged_at": "0001-01-01T00:00:00Z",
  "resolved_at": "0001-01-01T00:00:00Z"
}

Updating an Alarm

To update an existing alarm, you can use the following API endpoint:

curl --location --request PUT 'http://localhost:8050/<domain_id>/alarms/<alarm_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '{
    "status": "cleared",
    "metadata": {
        "notes": "pump fault fixed"
    },
    "assignee_id":"6fccdb77-6304-4960-84a5-5a42764c21d3"
}'

This command updates the status, metadata, and assignee of the specified alarm. The expected response is as shown below:

{
  "id": "721d7925-148c-4003-8fa0-e15af4493976",
  "rule_id": "4165e5ac-c85b-4e8d-b389-13fcb6fd6aae",
  "domain_id": "f93c0da3-d436-42a0-ac93-d2c96f80187a",
  "channel_id": "cd4126f5-8f4a-4b2e-a0f7-7d727f6fc96f",
  "client_id": "6fccdb77-6304-4960-84a5-5a42764c21d3",
  "subtopic": "water_volume",
  "status": "cleared",
  "measurement": "volume",
  "value": "30001",
  "unit": "",
  "threshold": "20000",
  "cause": "Critical level exceeded",
  "severity": 5,
  "assignee_id": "6fccdb77-6304-4960-84a5-5a42764c21d3",
  "created_at": "2026-01-22T14:02:01.360386Z",
  "updated_at": "2026-01-22T15:30:45.123456Z",
  "updated_by": "admin_user_id",
  "assigned_at": "0001-01-01T00:00:00Z",
  "acknowledged_at": "0001-01-01T00:00:00Z",
  "resolved_at": "0001-01-01T00:00:00Z",
  "metadata": {
    "notes": "pump fault fixed"
  }
}

The fields that can be updated are:

status
assignee_id
assigned_at
assigned_by
acknowledged_at
acknowledged_by
resolved_at
resolved_by
metadata

Deleting an Alarm

To delete an existing alarm, you can use the following API endpoint:

curl --location --request DELETE 'http://localhost:8050/<domain_id>/alarms/<alarm_id>' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

This command deletes the alarm with the specified ID. A successful deletion will return a 204 No Content status code.

Troubleshooting

Common Errors

Status: 401 Message:"failed to perform authentication over the entity" - This error indicates that the provided access token is invalid or has expired. Ensure that you are using a valid token.
Status: 403 Message:"failed to perform authorization over the entity" - This error indicates that the user does not have the necessary permissions to access the requested resource.
Status: 404 Message:""entity not found"" - This error indicates that the specified alarm ID does not exist. Verify that the alarm ID is correct.
Status: 400 Message:"invalid query parameters" - This error indicates that the query parameters provided in the request are invalid. Check the parameter names and values for correctness.
Status: 400 Message: "request body is not a valid JSON, expecting a valid JSON" - This error indicates that the request body is not properly formatted as JSON. Ensure that the JSON syntax is correct.

On this page