Skip to main content

addTempus

A Graze API POST request that adds a new Tempus Moolet.

Back to Graze API EndPoint Reference.

Request arguments

Endpoint addTempus takes the following request arguments:

Name

Type

Required

Description

auth_token

String

Yes

A valid auth_token returned from the authenticate request. Alternatively, basic authenticate headers can be used in place of this parameter. See the authenticate endpoint for more information and usage examples.

name

String

Yes

Name of the Tempus algorithm. Must be unique.

description

String

No

Description of the Situations Tempus generates. Default is 'A Tempus Situation'.

entropy_threshold

Number

No

Minimum entropy value an alert must have for Tempus to consider it for clustering into a Situation. A value between 0 and 1. Only relevant if threshold_type is set to explicit_value. If used, Tempus does not cluster any alerts with an entropy value below the threshold into Situations. Default is 0.0 which means that Tempus processes all alerts.

threshold_type

String

No

execution_interval

Number

No

Executes Tempus after a defined number of seconds. Default is 120.

window_size

Number

No

Determines the length of time, in seconds, when Tempus analyzes alerts and clusters them into a Situation each time it runs. Default window size is 1200 seconds (20 minutes). The default window size and bucket size provides 240 buckets per time period.

bucket_size

Number

No

Determines the time span, in seconds, of each bucket in which alerts are captured. Default bucket size is 5 seconds. The default window size and bucket size provides 240 buckets per time period.

arrival_spread

Number

No

Sets the acceptable latency or arrival window for each alert, in seconds. Use this to minimise or reduce the impact of multiple alerts arriving over a small amount of time and landing in separate buckets. This is a value between 1 and 60. Default is 15.

minimum_arrival_similarity

Number

No

How similar alerts must be for Tempus to consider them for clustering. Default is 0.6667.

alert_threshold

Number

No

Minimum number of alerts that match the clustering criteria before the Tempus algorithm creates a Situation. Default is 4.

When Tempus determines the number of alerts required to create a Situation, it compares the alert threshold values in Tempus and in the merge group that Tempus belongs to, and it uses the higher value. If you are using the default merge group which has an alert threshold of 2, Tempus will never create a Situation containing a single alert. If you want Moogsoft Onprem to create Situations with a single alert, consider changing the alert threshold in the default merge group to 1 or creating custom merge groups. See Merge Groups for more information on updating the default merge group and setting up custom merge groups.

process_output_of

Array of Strings

Yes

Defines the source of the alerts that Tempus processes. You can specify none, one or more Moolets. Typically Tempus processes the output of its direct upstream neighbor in the processing chain. Usually this is "Alert Workflows" which are the output from the Alert Workflow Engine.

run_on_startup

Boolean

No

Whether Tempus should start when Moogfarmd starts. Default is true.

partition_by

String

No

Splits clustering according to the entered component. After alerts have been clustered and before they enter merging and resolution, you can split clusters into sub-clusters based on a component of the events. For example, you can use the manager parameter to ensure that Situations only contain events from the same manager. The default of null means that no partitioning occurs.

Note

Moogsoft does not recommend partitioning by components.

pre_partition

Boolean

No

Partitions event streams before clustering. You specify a component field on which the event stream will be partitioned before clustering occurs. The alerts in the resulting Situations each contain a single value for the component field chosen. The default of null means that no pre-partitioning occurs.

significance_test

String

No

Calculation that determines how significant a cluster of alerts or a potential Situation must be for Tempus to detect it. The default, Poisson1, looks at the data of a single alert cluster to calculate how significant it is. The default is more likely to detect all significant alert clusters but with a higher risk of creating insignificant alert clusters. Use this option when your alerts originate from different networks or unrelated topologies. Poisson2 is a more thorough test that looks at an alert cluster and all alerts outside the cluster with a similar event rate. It is more likely to exclude all insignificant alert clusters but with a high risk of excluding significant alert clusters. Use this option if you expect all of your alerts to come from the same connected network. See Poisson distribution for more information.

significance_threshold

Number

No

Sets the maximum significance score for Tempus to create a Situation. The score is proportional to the probability that the alert cluster or potential Situation was coincidence. The lower the score, the more significant the cluster and the least likely it was a coincidence. This score ranges from 0 to 100. Default is 1.

detection_algorithm

String

No

Detection algorithm that Tempus uses, one of: Louvain, LouvainMulti, or SmartLocal. Default is Louvain.

Response

Endpoint addTempus returns the following response:

This endpoint returns an error code if the values of entropy_threshold and threshold_type are inconsistent. For example, if the entropy_threshold is set to 0.4 and threshold_type is set to global.

Examples

The following examples demonstrate typical use of endpoint addTempus:

Request example

Example cURL request to create a new Tempus algorithm:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addTempus" -H "Content-Type: application/json; charset=UTF-8" -d \
'{ \
"name":"GrazeTempus1", \
"description":"Situation Generated by Tempus", \
"process_output_of":"Alert Workflows", \
"run_on_startup":false, \
"entropy_threshold":0.3, \
"threshold_type":"explicit_value", \
"execution_interval":60, \
"window_size":240, \
"bucket_size":3, \
"arrival_spread":9, \
"minimum_arrival_similarity":0.5, \
"alert_threshold":5, \
"partition_by":"manager", \
"significance_test":"Poisson2", \
"significance_threshold":3, \
"detection_algorithm":"LouvainMulti" \
}'

Response example