search

elastic / kibana

Your window into the Elastic Stack
https://www.elastic.co/products/kibana
Other
19.67k stars 8.23k forks source link

[ResponseOps][docs] add information on "correlation ids" to connectors that make use of the concept #196434

Open pmuellr opened 1 month ago

pmuellr commented 1 month ago

We have some connectors that have a notion of a "correlation id", which is used to indicate which objects to target in the connector's system. They aren't all called correlation id, and here are few of the connectors:

For these fields, the resulting value is basically used as a key in the connector's system to identify either a new object, or an existing one. Sometimes you want to always create a new object when an alert fires, sometimes you just want to update an existing object when the same object should be updated.

The https://www.elastic.co/guide/en/kibana/current/servicenow-sir-action-type.html doc has a pretty good description of this under "Correlation ID". Though the mustache variables don't appear to be correct. I think it should be {{rule.id}}:{alert.id}}.

Using alert.id in the correlation allows you to deal with grouped alerts nicely. For instance, if you group over host name (common), the alert.id value will be the host name. The correlation id would then be something like:

So anytime host-name-1 is the cause of the alert, it will be referencing the same service now object.

However, if you want a new servicenow object for every alert, you can use {{rule.id}}:{alert.uuid}}. alert.uuid is unique to every alert, so this will reference a new unique servicenow object every time.

What we're missing here is doc :-). We should identify all the connector types that have a notion of a correlation id like this (probably more than the 3 I referenced at the top). Then create some common doc explaining how this works (like above, but readable by humans :-). Whether we'd have it in another doc and reference it from the specific connector pages, or embed it in each page, probably doesn't matter.

I assume we will likely have more connectors in the future that will also have correlation ids like this, so the list will grow ...

Side note: I was just explaining somewhere else about how alert.id will be set to the "grouped over" value when a rule allows grouping. I'm not sure we talk about that anywhere in the docs, but maybe we need to add something there as well, in the rules doc, to complete the picture. alert.id is doc'd here, but doesn't really describe what it is. We would probably need a little doc in the rules that support grouping explaining the alert.id will be the value of the group that is being alerted on: https://www.elastic.co/guide/en/kibana/current/rule-action-variables.html#alert-action-variables

elasticmachine commented 1 month ago

Pinging @elastic/response-ops (Team:ResponseOps)