Alert Actions

An alert action is a response to an event alert. To create an alert action, specify one or more events, and specify one or more actions to take when an alert is sent for that event such as send an email or execute a workflow. More than one alert action can be specified for any particular event alert.

The category property specifies the category of event for which the alert action will be performed. Each category includes one or more events. The events within each category are listed when you create or list the alert action. By default, the alert action will be performed for all events in the category. If the alert action should be performed for only a subset of events, change to false the values of properties that represent events that should not cause the alert action to be performed.

The following table describes the event categories that you can specify.

Table 4-2 Alert Action Event Categories

Category	Description
`ad`	Active Directory or SMB Kerberos client authentication degraded
`all`	High-level events such as all alerts or defects, service alerts, and hardware faults
`analytics`	High-level events such as datasets auto-suspend warning, memory total exceeded, and usage exceeded. For events for specific Analytics statistics, see Threshold Alerts.
`appliance_software`	Events that prevent software update or that result in kernel panic
`cloud_snapshot`
`cluster`	Cluster events, including link failures and peer errors
`custom`	An alert action for a custom event, which is specified in a workflow. See Custom Alerts.
`hardware`	Appliance boot and hardware configuration changes
`hardware_faults`	Any hardware fault
`ndmp` `backup` `restore`	NDMP TAR/DUMP backup and restore start and finish events
`network`	Network port, datalink, and IP interface events and failures
`scrk`	Support bundle upload events
`replication` `replication_source` `replication_target`	Send and receive events and failures
`smf`	Software services failure events
`shadow`	Migration errors or migration complete
`thresholds`	Enables you to add an action to an existing threshold event alert as described in Threshold Alerts
`zfs_pool`	Storage pool events, including scrub and hot space activation

The handler property specifies the type of action you want to take when the specified event occurs. Most values of handler require additional properties to be set, as shown in the following table.

Table 4-3 Alert Action Response Types

Response Type (handler)	Handler Properties	Response Type Description
`email`	`address` `subject`	Sends an email with the specified subject to the specified recipients. To send to multiple individual recipients, separate email addresses with a comma and a space on one line. Use the SMTP service to configure how email is sent. See List Services.
`snmp_trap`	None	Sends an SNMP trap that contains alert details. Use the SNMP service to configure an SNMP trap destination. See List Services.
`syslog`	None	Sends a system message that contains alert details to one or more remote systems. Use the `syslog` service to configure syslog destinations. See List Services. For more information about sending syslog messages, see Syslog Configuration in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.
`resume_dataset`	`dataset`	Resumes an Analytics dataset. Resuming and suspending datasets can be useful for diagnosing intermittent performance issues and for other cases when keeping a dataset continuously enabled is not desirable. For more information, see About Analytics Datasets in Oracle ZFS Storage Appliance Analytics Guide, Release OS8.8.x.
`suspend_dataset`	`dataset`	Suspends an Analytics dataset.
`resume_worksheet`	`worksheet`	Resumes an Analytics worksheet. Resuming and suspending worksheets can be useful for the same reasons as resuming and suspending datasets. A worksheet might contain numerous datasets. For more information, see Worksheet Graphs and Plots in Oracle ZFS Storage Appliance Analytics Guide, Release OS8.8.x.
`suspend_worksheet`	`worksheet`	Suspends an Analytics worksheet.
`execute_workflow`	`workflow`	Executes the specified workflow. For more information about workflows that are eligible to be alert actions, see Using Workflows for Alert Actions in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

List All Alert Actions

When you list all alert actions, only the event category and each event in that category are listed for each alert action. To also show the responses that are defined for an alert action, see List a Single Alert Action.

Example Request to Get Alert Actions:

GET /api/alert/v1/actions HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 1395

{
    "actions": [
        {
            "category": "smf",
            "uuid": "actions-uuid1",
            "failed_services": true,
            "degraded_services": true,
            "repaired_services": false,
            "actions": "actions-000",
            "href": "/api/alert/v2/actions/actions-000"
        },
        {
            "category": "analytics",
            "uuid": "actions-uuid2",
            "analytics_datasets_auto-suspend_notify": false,
            "analytics_datasets_auto-suspend_warning": false,
            "analytics_memory_total_exceeded": true,
            "analytics_memory_total_normal": false,
            "analytics_usage_exceeded": true,
            "analytics_usage_normal": false,
            "actions": "actions-001",
            "href": "/api/alert/v2/actions/actions-001"
        }
    ]
}

List a Single Alert Action

When you specify a particular alert action to list, the event category, each event in that category, and each response or action are listed for that alert action.

The following alert action has three responses that all will be performed when one of the true events occurs.

Example Request:

GET /api/alert/v1/actions/actions-000 HTTP/1.1

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 331

{
    "actions": {
        "href": "/api/alert/v2/actions/actions-000",
        "category": "smf",
        "uuid": "actions-uuid1",
        "failed_services": true,
        "degraded_services": true,
        "repaired_services": false,
        "action-000": {
            "handler": "email",
            "address": "admin@example.com",
            "subject": "failed or degraded service",
            "href": "/api/alert/v2/actions/actions-000/action-000"
        },
        "action-001": {
            "handler": "email",
            "address": "it-team@example.com",
            "subject": "failed or degraded service",
            "href": "/api/alert/v2/actions/actions-000/action-001"
        },
        "action-002": {
            "handler": "syslog",
            "href": "/api/alert/v2/actions/actions-000/action-002"
        }
    }
}

Create an Alert Action

When you create an alert action, you must specify a value for the category property, which is the category of event for which you are defining this custom response. See table "Alert Action Event Categories" in Alert Actions for the list of category values.

Example Request:

POST /api/alert/v1/actions HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdv
Content-Type: application/json
Content-Length: 30

{"category": "smf"}

Example Result:

The result lists all the events in the specified event category. By default, all events in the category will cause the response actions to be performed (they are all set to true).

HTTP/1.1 201 Created
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 118
Location: /api/alert/v1/actions/actions-000

{
    "actions": {
        "href": "/api/alert/v2/actions/actions-000",
        "category": "smf",
        "uuid": "actions-uuid",
        "failed_services": true,
        "degraded_services": true,
        "repaired_services": true
    }
}

Modify an Alert Action

If some of the events in the specified event category should not cause the response actions to be performed, set to false the properties that represent those events.

In the following example, you might want to define a different response for a repaired service than for a failed or degraded service.

Example Request:

PUT /api/alert/v1/actions/actions-000 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdv
Content-Type: application/json
Content-Length: 30

{"repaired_services": false}

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 195

{
    "actions": {
        "href": "/api/alert/v2/actions/actions-000",
        "category": "smf",
        "uuid": "actions-uuid",
        "failed_services": true,
        "degraded_services": true,
        "repaired_services": false
    }
}

Specify a Response for an Event

By default, event alerts are logged to the alerts log. The preceding examples specified the events for which you want to define a response in addition to posting to the alerts log. To define the response to those events, specify the value of the handler property for the particular alert action. See table "Alert Action Response Types" in Alert Actions for the list of handler values.

Example Request:

This example creates an alert action of send an email to admin for the actions-000 alert.

POST /api/alert/v1/actions/actions-000 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdv
Content-Type: application/json
Content-Length: 68

{"handler": "email", "address": "admin@example.com", "subject": "failed or degraded service"}

Example Result:

HTTP/1.1 201 Created
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 177
Location: /api/alert/v1/actions/actions-000/action-000

{
    "action": {
        "href": "/api/alert/v1/actions/actions-002/action-000",
        "handler": "email",
        "address": "admin@example.com",
        "subject": "failed or degraded service"
    }
}

To specify additional responses for the same event, issue the POST request again for the same alert action and specify a different handler, or specify the same handler and a different argument for the handler. If you specify more than one handler property in one request, all handler properties except for the last one are ignored.

The following examples are shortened. These requests create /api/alert/v1/actions/actions-000/action-001 and /api/alert/v1/actions/actions-000/action-002 as shown in List a Single Alert Action.

POST /api/alert/v1/actions/actions-002 HTTP/1.1
...
{"handler": "email", "address": "it-team@example.com", "subject": "failed or degraded service"}

POST /api/alert/v1/actions/actions-002 HTTP/1.1
...
{"handler": "syslog"}

Modify a Response for an Event

To modify a response, specify the HREF for the response that you want to modify.

PUT /api/alert/v1/actions/actions-000/action-001 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdv
Content-Type: application/json
Content-Length: 28

{"address": "it-group@example.com"}

Delete a Response for an Event

To delete a response, specify the HREF for the response that you want to delete.

DELETE /api/alert/v1/actions/actions-000/action-000 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdv

HTTP/1.1 204 No Content

Delete an Alert Action

To delete an alert action, specify the HREF for the alert action that you want to delete.

Example Request:

DELETE /api/alert/v1/actions/actions-003 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215

Example Result:

HTTP/1.1 204 No Content
X-Zfssa-Appliance-Api: 1.0