[Alerting] formalize alert status and add status fields to alert save…

…d object

resolves #51099

This formalizes the concept of "alert status", in terms of it's execution, with
some new fields in the alert saved object and types used with the alert client
and http APIs.

These fields are read-only from the client point-of-view; they are provided in
the alert structures, but are only updated by the alerting framework itself.
The values will be updated after each run of the alert type executor.

interim commits:

calculate the execution status, some refactoring

x-pack/plugins/alerts/common/alert.ts

@@ -15,6 +15,18 @@ export interface IntervalSchedule extends SavedObjectAttributes {
   interval: string;
 }
 
+export type AlertExecutionStatuses = 'ok' | 'active' | 'error' | 'noData' | 'unknown';
+export type AlertExecutionStatusErrorReasons = 'read' | 'decrypt' | 'execute' | 'unknown';
+
+export interface AlertExecutionStatus {
+  status: AlertExecutionStatuses;
+  date: Date;
+  error?: {
+    reason: AlertExecutionStatusErrorReasons;
+    message: string;
+  };
+}
+
 export type AlertActionParams = SavedObjectAttributes;
 
 export interface AlertAction {
@@ -44,6 +56,7 @@ export interface Alert {
   throttle: string | null;
   muteAll: boolean;
   mutedInstanceIds: string[];
+  executionStatus: AlertExecutionStatus;
 }
 
 export type SanitizedAlert = Omit<Alert, 'apiKey'>;

x-pack/plugins/alerts/server/alerts_client.test.ts

@@ -339,6 +339,10 @@ describe('create()', () => {
         ],
         "alertTypeId": "123",
         "createdAt": 2019-02-12T21:01:22.479Z,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,
@@ -372,6 +376,10 @@ describe('create()', () => {
         "createdAt": "2019-02-12T21:01:22.479Z",
         "createdBy": "elastic",
         "enabled": true,
+        "executionStatus": Object {
+          "date": "2020-08-20T19:23:38Z",
+          "status": "unknown",
+        },
         "muteAll": false,
         "mutedInstanceIds": Array [],
         "name": "abc",
@@ -564,6 +572,10 @@ describe('create()', () => {
         ],
         "alertTypeId": "123",
         "createdAt": 2019-02-12T21:01:22.479Z,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,
@@ -638,6 +650,10 @@ describe('create()', () => {
         "alertTypeId": "123",
         "createdAt": 2019-02-12T21:01:22.479Z,
         "enabled": false,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,
@@ -938,6 +954,10 @@ describe('create()', () => {
         muteAll: false,
         mutedInstanceIds: [],
         tags: ['foo'],
+        executionStatus: {
+          date: '2020-08-20T19:23:38Z',
+          status: 'unknown',
+        },
       },
       {
         references: [
@@ -1051,6 +1071,10 @@ describe('create()', () => {
         muteAll: false,
         mutedInstanceIds: [],
         tags: ['foo'],
+        executionStatus: {
+          date: '2020-08-20T19:23:38Z',
+          status: 'unknown',
+        },
       },
       {
         references: [
@@ -2025,6 +2049,10 @@ describe('get()', () => {
         ],
         "alertTypeId": "123",
         "createdAt": 2019-02-12T21:01:22.479Z,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,
@@ -2347,6 +2375,10 @@ const BaseAlertStatusSavedObject: SavedObject<RawAlert> = {
     throttle: null,
     muteAll: false,
     mutedInstanceIds: [],
+    executionStatus: {
+      status: 'unknown',
+      date: '2020-08-20T19:23:38Z',
+    },
   },
   references: [],
 };
@@ -2618,6 +2650,10 @@ describe('find()', () => {
             ],
             "alertTypeId": "myType",
             "createdAt": 2019-02-12T21:01:22.479Z,
+            "executionStatus": Object {
+              "date": 2019-02-12T21:01:22.479Z,
+              "status": "unknown",
+            },
             "id": "1",
             "params": Object {
               "bar": true,
@@ -3059,6 +3095,10 @@ describe('update()', () => {
         ],
         "createdAt": 2019-02-12T21:01:22.479Z,
         "enabled": true,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,
@@ -3236,6 +3276,10 @@ describe('update()', () => {
         "apiKey": "MTIzOmFiYw==",
         "createdAt": 2019-02-12T21:01:22.479Z,
         "enabled": true,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,
@@ -3387,6 +3431,10 @@ describe('update()', () => {
         "apiKey": null,
         "createdAt": 2019-02-12T21:01:22.479Z,
         "enabled": false,
+        "executionStatus": Object {
+          "date": 2019-02-12T21:01:22.479Z,
+          "status": "unknown",
+        },
         "id": "1",
         "params": Object {
           "bar": true,

x-pack/plugins/alerts/server/alerts_client.ts

@@ -25,6 +25,8 @@ import {
   SanitizedAlert,
   AlertTaskState,
   AlertStatus,
+  AlertExecutionStatus,
+  RawAlertExecutionStatus,
 } from './types';
 import { validateAlertTypeParams } from './lib';
 import {
@@ -121,6 +123,7 @@ export interface CreateOptions {
     | 'muteAll'
     | 'mutedInstanceIds'
     | 'actions'
+    | 'executionStatus'
   > & { actions: NormalizedAlertAction[] };
   options?: {
     migrationVersion?: Record<string, string>;
@@ -224,6 +227,10 @@ export class AlertsClient {
       params: validatedAlertTypeParams as RawAlert['params'],
       muteAll: false,
       mutedInstanceIds: [],
+      executionStatus: {
+        status: 'unknown',
+        date: '2020-08-20T19:23:38Z',
+      },
     };
     const createdAlert = await this.unsecuredSavedObjectsClient.create('alert', rawAlert, {
       ...options,
@@ -355,12 +362,18 @@ export class AlertsClient {
     // eslint-disable-next-line @typescript-eslint/naming-convention
     const authorizedData = data.map(({ id, attributes, updated_at, references }) => {
       ensureAlertTypeIsAuthorized(attributes.alertTypeId, attributes.consumer);
-      return this.getAlertFromRaw(
+      const alert = this.getAlertFromRaw(
         id,
         fields ? (pick(attributes, fields) as RawAlert) : attributes,
         updated_at,
         references
       );
+      // executionStatus is a synthetic field added by getAlertFromRaw(), so we
+      // need to remove it if it wasn't listed in the fields
+      if (fields && !fields.includes('executionStatus')) {
+        delete alert.executionStatus;
+      }
+      return alert;
     });
 
     logSuccessfulAuthorization();
@@ -864,11 +877,13 @@ export class AlertsClient {
     updatedAt: SavedObject['updated_at'] = createdAt,
     references: SavedObjectReference[] | undefined
   ): PartialAlert {
+    const executionStatus = this.rawAlertToExecutionStatus(rawAlert);
     return {
       id,
       ...rawAlert,
       // we currently only support the Interval Schedule type
       // Once we support additional types, this type signature will likely change
+      executionStatus,
       schedule: rawAlert.schedule as IntervalSchedule,
       actions: rawAlert.actions
         ? this.injectReferencesIntoActions(id, rawAlert.actions, references || [])
@@ -878,6 +893,22 @@ export class AlertsClient {
     };
   }
 
+  private rawAlertToExecutionStatus(rawAlert: Partial<RawAlert> = {}): AlertExecutionStatus {
+    const rawExecutionStatus: Partial<RawAlertExecutionStatus> = rawAlert.executionStatus || {};
+    const { status: rawStatus, date: rawDate, error: rawError } = rawExecutionStatus;
+
+    const result: AlertExecutionStatus = {
+      status: rawStatus || 'unknown',
+      date: rawDate ? new Date(rawDate) : new Date(),
+    };
+
+    if (rawError) {
+      result.error = rawError;
+    }
+
+    return result;
+  }
+
   private validateActions(alertType: AlertType, actions: NormalizedAlertAction[]): void {
     const { actionGroups: alertTypeActionGroups } = alertType;
     const usedAlertActionGroups = actions.map((action) => action.group);

x-pack/plugins/alerts/server/lib/alert_status_from_event_log.test.ts

@@ -461,4 +461,8 @@ const BaseAlert: SanitizedAlert = {
   createdAt: new Date(),
   updatedAt: new Date(),
   apiKeyOwner: null,
+  executionStatus: {
+    status: 'unknown',
+    date: new Date('2020-08-20T19:23:38Z'),
+  },
 };

x-pack/plugins/alerts/server/lib/error_with_reason.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+import { AlertExecutionStatusErrorReasons } from '../types';
+
+export class ErrorWithReason extends Error {
+  public readonly reason: AlertExecutionStatusErrorReasons;
+
+  constructor(reason: AlertExecutionStatusErrorReasons, message: string) {
+    super(message);
+    this.reason = reason;
+  }
+}
+
+export function getReasonFromError(error: Error): AlertExecutionStatusErrorReasons {
+  if (error instanceof ErrorWithReason) {
+    return error.reason;
+  }
+  return 'unknown';
+}

x-pack/plugins/alerts/server/lib/index.ts

@@ -7,3 +7,4 @@
 export { parseDuration, validateDurationSchema } from '../../common/parse_duration';
 export { LicenseState } from './license_state';
 export { validateAlertTypeParams } from './validate_alert_type_params';
+export { ErrorWithReason, getReasonFromError } from './error_with_reason';

x-pack/plugins/alerts/server/routes/create.test.ts

@@ -10,6 +10,7 @@ import { mockLicenseState } from '../lib/license_state.mock';
 import { verifyApiAccess } from '../lib/license_api_access';
 import { mockHandlerArguments } from './_mock_handler_arguments';
 import { alertsClientMock } from '../alerts_client.mock';
+import { Alert } from '../../common/alert';
 
 const alertsClient = alertsClientMock.create();
 
@@ -46,7 +47,7 @@ describe('createAlertRoute', () => {
     ],
   };
 
-  const createResult = {
+  const createResult: Alert = {
     ...mockedAlert,
     enabled: true,
     muteAll: false,
@@ -64,6 +65,10 @@ describe('createAlertRoute', () => {
         actionTypeId: 'test',
       },
     ],
+    executionStatus: {
+      status: 'unknown',
+      date: new Date('2020-08-20T19:23:38Z'),
+    },
   };
 
   it('creates an alert with proper parameters', async () => {

x-pack/plugins/alerts/server/routes/get.test.ts

@@ -10,6 +10,7 @@ import { mockLicenseState } from '../lib/license_state.mock';
 import { verifyApiAccess } from '../lib/license_api_access';
 import { mockHandlerArguments } from './_mock_handler_arguments';
 import { alertsClientMock } from '../alerts_client.mock';
+import { Alert } from '../../common';
 
 const alertsClient = alertsClientMock.create();
 jest.mock('../lib/license_api_access.ts', () => ({
@@ -21,7 +22,7 @@ beforeEach(() => {
 });
 
 describe('getAlertRoute', () => {
-  const mockedAlert = {
+  const mockedAlert: Alert = {
     id: '1',
     alertTypeId: '1',
     schedule: { interval: '10s' },
@@ -51,6 +52,10 @@ describe('getAlertRoute', () => {
     apiKeyOwner: '',
     throttle: '30s',
     mutedInstanceIds: [],
+    executionStatus: {
+      status: 'unknown',
+      date: new Date('2020-08-20T19:23:38Z'),
+    },
   };
 
   it('gets an alert with proper parameters', async () => {

x-pack/plugins/alerts/server/saved_objects/index.ts

@@ -28,6 +28,7 @@ export function setupSavedObjects(
       'muteAll',
       'mutedInstanceIds',
       'updatedBy',
+      'executionStatus',
     ]),
   });
 }

x-pack/plugins/alerts/server/saved_objects/mappings.json

@@ -76,6 +76,26 @@
       },
       "mutedInstanceIds": {
         "type": "keyword"
+      },
+      "executionStatus": {
+        "properties": {
+          "status": {
+            "type": "keyword"
+          },
+          "date": {
+            "type": "date"
+          },
+          "error": {
+            "properties": {
+              "reason": {
+                "type": "keyword"
+              },
+              "message": {
+                "type": "keyword"
+              }
+            }
+          }
+        }
       }
     }
   }

x-pack/plugins/alerts/server/task_runner/alert_task_instance.test.ts

@@ -29,6 +29,10 @@ const alert: SanitizedAlert = {
   throttle: null,
   muteAll: false,
   mutedInstanceIds: [],
+  executionStatus: {
+    status: 'unknown',
+    date: new Date('2020-08-20T19:23:38Z'),
+  },
 };
 
 describe('Alert Task Instance', () => {