Version: 7.x-36.0.0

This is a technical preview. Technical preview features are not fully supported, may not be functionally complete, and are not suitable for deployment in production. We encourage you to try them out and provide your feedback, good and bad, on the Search Guard forum. This will help us improve and add any features you might be missing.

Calculations

A calculation is a script that

  • has access to the execution context payload data
  • performs one or more painless statements
  • writes data back to the execution context

As opposed to Transformations, Calculation scripts do not have a return statement and do not need to define a target.

Instead, they access and manipulate the watch runtime data directly.

Calculations can be used

  • in the checks section of a watch definition
    • the calculation is executed before any actions are executed. Changes to the execution context payload data are visible for all subsequent steps and for all actions
  • in the checks section of any action
    • the calculation is executed before the action is executed. Changes to the execution context payload data are only applied to the payload for that specific action.

Using inline scripts

A calculation painless script can be defined as inline script within the calculation definition. For example, the next calculation iterates over the hits of a query stored under the key logs in the execution context, calculates the average memory usage, and makes it available under the new key average_memory in the execution context. All subsequent steps can access this value.

{
  "type": "calc",
  "name": "avg_memory",
  "source": "int total = 0; for (int i = 0; i < data.logs.hits.hits.length; ++i) { total += data.logs.hits.hits[i]._source.memory; } data.average_memory = total / data.logs.hits.hits.length;"
}
Name Description
type calc, defines this script as calculation. Mandatory.
name name of this calculation. Can be chosen freely. Mandatory.
source The painless script to execute. Mandatory

Using stored scripts

{
  "type": "calc",
  "name": "mean_memory",
  "script_id": "calculate_mean_memory"
}
Name Description
type calc, defines this script as calculation. Mandatory.
name name of this caclulation. Can be chosen freely. Mandatory.
script_id The ID of the stored script. Mandatory.

Accessing the execution context data

All scripts have full access to the data stored in the execution context. The data in the execution context is available via the data prefix, followed by the target name of the data.

Using calculations with actions

Caclulations can also be used with actions. Each action can define it’s own chain of checks, including calculations. The following snippets shows how to combine a calculation and a condition specific to an action. The calculation is the same as above, and the condition will execute the action only if the average memory consumption is above a certain threshold.

Note that you can also use the calculated value in the text_body of the email action. Actions use Mustache to render the output. Mustache has the same access to the execution context data as scripts and conditions.

{ 
  "trigger":{},
  "checks":[],
  "actions":[ 
    {
         "type":"email",
         "name":"standard_admin",
         "account":"it_smtp",
         "to": ["management@example.com"],
         "subject": "Warning: Critical average memory consumption",
         "checks": [
          {
            "type": "calc",
            "name": "avg_memory",
            "source": "int total = 0; for (int i = 0; i < data.logs.hits.hits.length; ++i) { total += data.logs.hits.hits[i]._source.memory; } data.average_memory = total / data.logs.hits.hits.length;"
           },
           {
               "type": "condition.script",
               "name": "escalation_level_1",
               "source": "return data.average_memory > 10000"
           }
         ]
         "text_body":"Average memory consumption: ",
    }    
  ]
}

Not what you were looking for? Try the search.