Alerting: Extend server API type AlertType with property actionVariables: string[]

[YulNaumenko]

Each Alert Type should has a possibility to provide a set of application specific variables, that could be added to the action message in UI.

[elasticmachine]

Pinging @elastic/kibana-alerting-services (Team:Alerting Services)

[pmuellr]

Ya, we need something like this. We currently call them context variables, here are the ones from the index threshold:

kibana/x-pack/plugins/alerting_builtins/server/alert_types/index_threshold/action_context.ts

Lines 12 to 35 in 9bdd23a

	export interface ActionContext extends BaseActionContext {
	// a short generic message which may be used in an action message
	subject: string;
	// a longer generic message which may be used in an action message
	message: string;
	}
	export interface BaseActionContext {
	// the alert name
	name: string;
	// the spaceId of the alert
	spaceId: string;
	// the namespace of the alert (spaceId === (namespace || 'default')
	namespace?: string;
	// the alert tags
	tags?: string[];
	// the aggType used in the alert
	// the value of the aggField, if used, otherwise 'all documents'
	group: string;
	// the date the alert was run as an ISO date
	date: string;
	// the value that met the threshold
	value: number;
	}

The alerting framework itself adds some additional top-level properties available, not under context:

kibana/x-pack/plugins/alerting/server/task_runner/transform_action_params.ts

Lines 19 to 25 in 9bdd23a

	export function transformActionParams({
	alertId,
	alertInstanceId,
	context,
	params,
	state,
	}: TransformActionParamsOptions): AlertActionParams {

One issue is that these is the typing. You can basically think of the complete set of variables that we provide being a Record<string, any>, where you can have objects, arrays, numbers, Dates, etc in the leaf property values.

I'm not sure the best way to represent this type data. I'm not sure the final leaf property value types matter that much - we can stringify them if needed. Arrays seem to be the biggest problem. If you imagine we didn't allow arrays anywhere in the tree of variables, then each alert type could represent it's variables as a list of flattened keys, or perhaps with the object structure, and the property values being a "type" of the data.

Eg, from the index threshold alert type, here's a flat list of properties (none are nested):

'subject message name spaceId namespace tags group date value'.split(' ')

Here's a "structure" version:

subject: 'string',
message: 'string',
name: 'string',
spaceId: 'string',
namespace?: 'string',
tags?: 'string[]',
group: 'string',
date: 'string',
value: 'number',

Note that tags is already problematic, as it's an array. Also, the following instance threshold context vars really should be added to all alerts, in the alerting lib: spaceId, namespace, tags. The state variable already provided by the alert lib is also a little problematic, as the state is just a JSON-able object that the alertType can use for whatever it wants. We'd need to provide a similar sort of "schema" like I proposed for the context, for that particular structure.

[pmuellr]

I'm currently thinking that alertTypes should probably define an array of strings of context variable names. The values for these, when expanded, would always be strings. So, tags will have to be pre-expanded to tags.join(", ") or similar, by the alert, before sending as a context variable value.

In the future, instead of array of strings, an element could be an object instead of a string, where the object would define the name, and some kind of typing information that an editor could make use of: is it an array? is it a number? etc.

Seems like this is a nice 90% solution, and fairly easy to implement, and keep up to date, perhaps expandable in the future.

[mikecote]

In the future, instead of array of strings, an element could be an object instead of a string, where the object would define the name, and some kind of typing information that an editor could make use of: is it an array? is it a number? etc.

If ever we really want to support nested objects / arrays. I wonder if we could add support for something like foo.bar or even foo[0].bar with the usage of _.get(...). It would support nested objects and arrays while keeping it an array of strings in the definition.

Though maybe we want to put pretty names on those so they can also be localized.

[pmuellr]

I just did a little mustache test, rendering an array by it's name:

$ node
> mustache = require('mustache')
{ ... }
> mustache.render('hi')
'hi'
> mustache.render('hi {{{name}}}', {name: 'bob'})
'hi bob'
> mustache.render('hi {{{name}}}', {name: ['bob']})
'hi bob'
> mustache.render('hi {{{name}}}', {name: ['bob', 'jim']})
'hi bob,jim'
> mustache.render('{{#name}}{{.}}, {{/name}}', {name: ['bob', 'jim']})
'bob, jim, '

That last one is an example of "looping" through an array with mustache sections. So that works as well, but I don't think we need to provide UI help for it, as it could get quite elaborate.

I think that may be good enough for now, to deal with arrays. Just make them available as a variable with their name, let mustache do the join on them.

[pmuellr]

Though maybe we want to put pretty names on those so they can also be localized.

I'm not sure we want the "names" of the context variables localized, we should allow customers to enter any reasonable mustache-able template, should be the same across localization. However, it probably makes a ton of sense to provide a short description for each variable, that we would localize, that could be used as a tooltip or otherwise.