# Alarms

Alarms bind alerting rules, entities, and notification plans into a logical unit. Alarms are responsible for determining a state (`OK`, `WARNING` or `CRITICAL`) based on the result of a Check, and executing a notification plan whenever that state changes. You create alerting rules by using the alarm DSL. For information about using the alarm language, refer to the reference documentation.

## Setup

In order to interact with this feature, you must first retrieve an entity by its ID:

    $entity = $service->getEntity('{entityId}');

and then a particular check, about which you can configure alarms:

    $check = $entity->getCheck('{checkId}');

For more information about these resource types, please consult the documentation about entities and checks.

## Retrieve alarm

    $alarm = $check->getAlarm('{alarmId}');

Once you have access to a `OpenCloud\Monitoring\Resource\Alarm` object, these are the attributes you can access:

Name | Description | Required? | Method
--- | --- | --- | ---
check_id | The ID of the check to alert on. | Required | `getCheckId()`
notification_plan_id | The ID of the notification plan to execute when the state changes. | Optional | `getNotificationPlanId()`
criteria | The alarm DSL for describing alerting conditions and their output states. | Optional | `getCriteria()`
disabled | Disable processing and alerts on this alarm | Optional | `isDisabled()` <`bool`>
label | A friendly label for an alarm. | Optional | `getLabel()`
metadata | Arbitrary key/value pairs. | Optional | `getMetadata()`

## Create Alarm

    $alarm = $check->getAlarm();
    $alarm->create(array(
        'check_id' => 'chAAAA',
        'criteria' => 'if (metric["duration"] >= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);',
        'notification_plan_id' => 'npAAAAA'
    ));

## List Alarms

    $alarms = $entity->getAlarms();

    foreach ($alarms as $alarm) {
        echo $alarm->getId();
    }

## Update Alarm

    $alarm->update(array(
        'criteria' => 'if (metric["duration"] >= 5) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);'
    ));

## Delete alarm

    $alarm->delete();