[ResponseOps] move alert UUID generation from rule registry to the alerting framework

.github/CODEOWNERS

@@ -18,6 +18,7 @@ x-pack/test/alerting_api_integration/common/plugins/alerts @elastic/response-ops
 x-pack/examples/alerting_example @elastic/response-ops
 x-pack/test/functional_with_es_ssl/plugins/alerts @elastic/response-ops
 x-pack/plugins/alerting @elastic/response-ops
+x-pack/packages/kbn-alerting-state-types @elastic/response-ops
 packages/kbn-alerts @elastic/security-solution
 packages/kbn-alerts-as-data-utils @elastic/response-ops
 x-pack/test/alerting_api_integration/common/plugins/alerts_restricted @elastic/response-ops

docs/user/alerting/action-variables.asciidoc

@@ -100,6 +100,7 @@ If the rule's action frequency is not a summary of alerts, it passes the followi
 `alert.actionSubgroup`:: The action subgroup of the alert that scheduled the action.
 `alert.flapping`:: A flag on the alert that indicates whether the alert status is changing repeatedly.
 `alert.id`:: The ID of the alert that scheduled the action.
+`alert.uuid`:: A universally unique identifier for the alert. While the alert is active, the UUID value remains unchanged each time the rule runs.  preview:[]
 
 [float]
 [[defining-rules-actions-variable-context]]

package.json

@@ -133,6 +133,7 @@
     "@kbn/alerting-example-plugin": "link:x-pack/examples/alerting_example",
     "@kbn/alerting-fixture-plugin": "link:x-pack/test/functional_with_es_ssl/plugins/alerts",
     "@kbn/alerting-plugin": "link:x-pack/plugins/alerting",
+    "@kbn/alerting-state-types": "link:x-pack/packages/kbn-alerting-state-types",
     "@kbn/alerts": "link:packages/kbn-alerts",
     "@kbn/alerts-as-data-utils": "link:packages/kbn-alerts-as-data-utils",
     "@kbn/alerts-restricted-fixtures-plugin": "link:x-pack/test/alerting_api_integration/common/plugins/alerts_restricted",

src/core/server/integration_tests/saved_objects/migrations/group2/check_registered_types.test.ts

@@ -141,7 +141,7 @@ describe('checking migration metadata changes on all registered SO types', () =>
         "synthetics-param": "9776c9b571d35f0d0397e8915e035ea1dc026db7",
         "synthetics-privates-locations": "7d032fc788905e32152029ae7ab3d6038c48ae44",
         "tag": "87f21f07df9cc37001b15a26e413c18f50d1fbfe",
-        "task": "ebcc113df12f14bf627dbd335ba78507187b48a3",
+        "task": "ff760534a44c4cfabcf4baf8cfe8283f717cab02",
         "telemetry": "561b329aaed3c15b91aaf2075645be3097247612",
         "ui-metric": "410a8ad28e0f44b161c960ff0ce950c712b17c52",
         "upgrade-assistant-ml-upgrade-operation": "d8816e5ce32649e7a3a43e2c406c632319ff84bb",

tsconfig.base.json

@@ -30,6 +30,8 @@
       "@kbn/alerting-fixture-plugin/*": ["x-pack/test/functional_with_es_ssl/plugins/alerts/*"],
       "@kbn/alerting-plugin": ["x-pack/plugins/alerting"],
       "@kbn/alerting-plugin/*": ["x-pack/plugins/alerting/*"],
+      "@kbn/alerting-state-types": ["x-pack/packages/kbn-alerting-state-types"],
+      "@kbn/alerting-state-types/*": ["x-pack/packages/kbn-alerting-state-types/*"],
       "@kbn/alerts": ["packages/kbn-alerts"],
       "@kbn/alerts/*": ["packages/kbn-alerts/*"],
       "@kbn/alerts-as-data-utils": ["packages/kbn-alerts-as-data-utils"],

x-pack/packages/kbn-alerting-state-types/README.md

@@ -0,0 +1,8 @@
+# @kbn/alerting-state-types
+
+Contains type information for the alerting data persisted in task
+manager documents as state.  
+
+Because task manager migrations sometimes need this data, it needs
+to be in a package outside of alerting.
+

x-pack/packages/kbn-alerting-state-types/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+export type {
+  ThrottledActions,
+  LastScheduledActions,
+  AlertInstanceMeta,
+  AlertInstanceState,
+  AlertInstanceContext,
+  RawAlertInstance,
+} from './src/alert_instance';
+export { rawAlertInstance } from './src/alert_instance';
+
+export { DateFromString } from './src/date_from_string';
+
+export type { TrackedLifecycleAlertState, WrappedLifecycleRuleState } from './src/lifecycle_state';
+export { wrappedStateRt } from './src/lifecycle_state';
+
+export type { RuleTaskState, RuleTaskParams } from './src/rule_task_instance';
+export { ActionsCompletion, ruleStateSchema, ruleParamsSchema } from './src/rule_task_instance';

x-pack/packages/kbn-alerting-state-types/jest.config.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+module.exports = {
+  preset: '@kbn/test/jest_node',
+  rootDir: '../../..',
+  roots: ['<rootDir>/x-pack/packages/kbn-alerting-state-types'],
+};

x-pack/packages/kbn-alerting-state-types/kibana.jsonc

@@ -0,0 +1,5 @@
+{
+  "type": "shared-common",
+  "id": "@kbn/alerting-state-types",
+  "owner": "@elastic/response-ops"
+}

x-pack/packages/kbn-alerting-state-types/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@kbn/alerting-state-types",
+  "private": true,
+  "version": "1.0.0",
+  "license": "Elastic License 2.0"
+}

x-pack/plugins/alerting/common/alert_instance.ts → x-pack/packages/kbn-alerting-state-types/src/alert_instance.ts

@@ -37,6 +37,7 @@ const metaSchema = t.partial({
   // flapping flag that indicates whether the alert is flapping
   flapping: t.boolean,
   pendingRecoveredCount: t.number,
+  uuid: t.string,
 });
 export type AlertInstanceMeta = t.TypeOf<typeof metaSchema>;
 

x-pack/packages/kbn-alerting-state-types/src/lifecycle_state.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import * as t from 'io-ts';
+
+const trackedAlertStateRt = t.type({
+  alertId: t.string,
+  alertUuid: t.string,
+  started: t.string,
+  // an array used to track changes in alert state, the order is based on the rule executions
+  // true - alert has changed from active/recovered
+  // false - alert is new or the status has remained either active or recovered
+  flappingHistory: t.array(t.boolean),
+  // flapping flag that indicates whether the alert is flapping
+  flapping: t.boolean,
+  pendingRecoveredCount: t.number,
+});
+
+export type TrackedLifecycleAlertState = t.TypeOf<typeof trackedAlertStateRt>;
+
+type RuleTypeState = Record<string, unknown>;
+
+export const alertTypeStateRt = <State extends RuleTypeState>() =>
+  t.record(t.string, t.unknown) as t.Type<State, State, unknown>;
+
+export const wrappedStateRt = <State extends RuleTypeState>() =>
+  t.type({
+    wrapped: alertTypeStateRt<State>(),
+    // tracks the active alerts
+    trackedAlerts: t.record(t.string, trackedAlertStateRt),
+    // tracks the recovered alerts
+    trackedAlertsRecovered: t.record(t.string, trackedAlertStateRt),
+  });
+
+/**
+ * This is redefined instead of derived from above `wrappedStateRt` because
+ * there's no easy way to instantiate generic values such as the runtime type
+ * factory function.
+ */
+export type WrappedLifecycleRuleState<State extends RuleTypeState> = RuleTypeState & {
+  wrapped: State;
+  trackedAlerts: Record<string, TrackedLifecycleAlertState>;
+  trackedAlertsRecovered: Record<string, TrackedLifecycleAlertState>;
+};

x-pack/packages/kbn-alerting-state-types/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "target/types",
+    "types": [
+      "jest",
+      "node"
+    ]
+  },
+  "include": [
+    "**/*.ts",
+  ],
+  "exclude": [
+    "target/**/*"
+  ],
+  "kbn_references": []
+}

x-pack/plugins/alerting/README.md

@@ -766,6 +766,7 @@ This factory returns an instance of `Alert`. The `Alert` class has the following
 
 |Method|Description|
 |---|---|
+|getUuid()|Get the UUID of the alert.|
 |getState()|Get the current state of the alert.|
 |scheduleActions(actionGroup, context)|Call this to schedule the execution of actions. The actionGroup is a string `id` that relates to the group of alert `actions` to execute and the context will be used for templating purposes. `scheduleActions` should only be called once per alert.|
 |replaceState(state)|Used to replace the current state of the alert. This doesn't work like React, the entire state must be provided. Use this feature as you see fit. The state that is set will persist between rule executions whenever you re-create an alert with the same id. The alert state will be erased when `scheduleActions`isn't called during an execution.|
@@ -790,6 +791,8 @@ When an alert executes, the first argument is the `group` of actions to execute
 
 The templating engine is [mustache]. General definition for the [mustache variable] is a double-brace {{}}. All variables are HTML-escaped by default and if there is a requirement to render unescaped HTML, it should be applied with the triple mustache: `{{{name}}}`. Also, `&` can be used to unescape a variable.
 
+The complete list of variables available has grown, and difficult to keep in synch here as well, so refer to the published documentation for the variables available: https://www.elastic.co/guide/en/kibana/master/rule-action-variables.html
+
 ### Examples
 
 The following code would be within a rule type. As you can see `cpuUsage` will replace the state of the alert and `server` is the context for the alert to execute. The difference between the two is that `cpuUsage` will be accessible at the next execution.

x-pack/plugins/alerting/common/alert_summary.ts

@@ -32,6 +32,7 @@ export interface AlertSummary {
 }
 
 export interface AlertStatus {
+  uuid?: string;
   status: AlertStatusValues;
   muted: boolean;
   actionGroupId?: string;

x-pack/plugins/alerting/common/index.ts

@@ -13,8 +13,26 @@ import { AlertsHealth } from './rule';
 export * from './rule';
 export * from './rules_settings';
 export * from './rule_type';
-export * from './rule_task_instance';
-export * from './alert_instance';
+export type {
+  ThrottledActions,
+  LastScheduledActions,
+  AlertInstanceMeta,
+  AlertInstanceState,
+  AlertInstanceContext,
+  RawAlertInstance,
+  TrackedLifecycleAlertState,
+  WrappedLifecycleRuleState,
+  RuleTaskState,
+  RuleTaskParams,
+} from '@kbn/alerting-state-types';
+export {
+  rawAlertInstance,
+  DateFromString,
+  wrappedStateRt,
+  ActionsCompletion,
+  ruleStateSchema,
+  ruleParamsSchema,
+} from '@kbn/alerting-state-types';
 export * from './alert_summary';
 export * from './builtin_action_groups';
 export * from './bulk_edit';

x-pack/plugins/alerting/server/alert/alert.test.ts

@@ -8,6 +8,7 @@
 import sinon from 'sinon';
 import { Alert } from './alert';
 import { AlertInstanceState, AlertInstanceContext, DefaultActionGroupId } from '../../common';
+import { alertWithAnyUUID } from '../test_utils';
 
 let clock: sinon.SinonFakeTimers;
 
@@ -231,6 +232,23 @@ describe('getState()', () => {
   });
 });
 
+describe('getUUID()', () => {
+  test('returns a UUID for a new alert', () => {
+    const alert = new Alert<AlertInstanceState, AlertInstanceContext, DefaultActionGroupId>('1');
+    const uuid = alert.getUuid();
+    expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  test('returns same uuid from previous run of alert', () => {
+    const uuid = 'previous-uuid';
+    const meta = { uuid };
+    const alert = new Alert<AlertInstanceState, AlertInstanceContext, DefaultActionGroupId>('1', {
+      meta,
+    });
+    expect(alert.getUuid()).toEqual(uuid);
+  });
+});
+
 describe('scheduleActions()', () => {
   test('makes hasScheduledActions() return true', () => {
     const alert = new Alert<AlertInstanceState, AlertInstanceContext, DefaultActionGroupId>('1', {
@@ -320,6 +338,7 @@ describe('updateLastScheduledActions()', () => {
     expect(alert.toJSON()).toEqual({
       state: {},
       meta: {
+        uuid: expect.any(String),
         lastScheduledActions: {
           date: new Date().toISOString(),
           group: 'default',
@@ -338,6 +357,7 @@ describe('updateLastScheduledActions()', () => {
       state: {},
       meta: {
         flappingHistory: [],
+        uuid: expect.any(String),
         lastScheduledActions: {
           date: new Date().toISOString(),
           group: 'default',
@@ -367,6 +387,7 @@ describe('updateLastScheduledActions()', () => {
       state: {},
       meta: {
         flappingHistory: [],
+        uuid: expect.any(String),
         lastScheduledActions: {
           date: new Date().toISOString(),
           group: 'default',
@@ -468,9 +489,22 @@ describe('toJSON', () => {
         },
       }
     );
-    expect(JSON.stringify(alertInstance)).toEqual(
-      '{"state":{"foo":true},"meta":{"lastScheduledActions":{"date":"1970-01-01T00:00:00.000Z","group":"default"},"flappingHistory":[false,true],"flapping":false,"pendingRecoveredCount":2}}'
-    );
+
+    expect(alertInstance).toMatchObject({
+      state: {
+        foo: true,
+      },
+      meta: {
+        lastScheduledActions: {
+          date: expect.any(Date),
+          group: 'default',
+        },
+        uuid: expect.any(String),
+        flappingHistory: [false, true],
+        flapping: false,
+        pendingRecoveredCount: 2,
+      },
+    });
   });
 });
 
@@ -514,6 +548,7 @@ describe('toRaw', () => {
       meta: {
         flappingHistory: [false, true, true],
         flapping: false,
+        uuid: expect.any(String),
       },
     });
   });
@@ -529,12 +564,13 @@ describe('setFlappingHistory', () => {
     );
     alertInstance.setFlappingHistory([false]);
     expect(alertInstance.getFlappingHistory()).toEqual([false]);
-    expect(alertInstance.toRaw()).toMatchInlineSnapshot(`
+    expect(alertWithAnyUUID(alertInstance.toRaw())).toMatchInlineSnapshot(`
       Object {
         "meta": Object {
           "flappingHistory": Array [
             false,
           ],
+          "uuid": Any<String>,
         },
         "state": Object {},
       }
@@ -561,11 +597,12 @@ describe('setFlapping', () => {
     );
     alertInstance.setFlapping(false);
     expect(alertInstance.getFlapping()).toEqual(false);
-    expect(alertInstance.toRaw()).toMatchInlineSnapshot(`
+    expect(alertWithAnyUUID(alertInstance.toRaw())).toMatchInlineSnapshot(`
       Object {
         "meta": Object {
           "flapping": false,
           "flappingHistory": Array [],
+          "uuid": Any<String>,
         },
         "state": Object {},
       }