Learn more about Streama© – the foundational technology behind our stateful streaming data platform. Learn More

Rules API

This guide will help you use our Rules CRUD-API to create, read, update or delete rules and rule groups using an API.

In order to send an external request, the request headers should contain the following:

  1. Content-Type: application/JSON
  2. Authorization: Bearer {an auto-generated API key, which can be found under Settings –> Account –> ‘API access’ and generate a new API key}

** Note that only admin users have access to the API, So the option above will be visible only to admin users.

Groups API

 Request typeURLBody
CreatePOSThttps://api.coralogix.com/api/v1/external/group"name" (string) - the name for the rules group (Mandatory)

"description" (string) - the description for the rules group (an empty string is set on default)

"enabled" (boolean) - indicates rather the group will be enabled or not when created (set to true on default)

"creator" (string) - the name of the group creator (set to "Coralogix external API" on default)

"ruleMatchers" (array of objects) - the group filters for passing through the group rules only a subset of logs. Each object in the array should contain the field for the matcher and the constraint. The field must be one of applicationName, subsystemName, or severity, and the constraint (string) that will be the value for the chosen field (if the field is severity, the value should be one: debug, verbose, info, warning, error, critical)
E.g
[
{
"field":"applicationName",
"constraint":"prod"
},
{
"field":"severity",
"constraint":"info"
}
]
ReadGEThttps://api.coralogix.com/api/v1/external/group/GROUPID
UpdatePUThttps://api.coralogix.com/api/v1/external/group/GROUPID"name" (string) - the updated name for the rules group

"description" (string) - the updated description for the rules group

"enabled" (boolean) - indicates rather the group will be enabled or not after the update

"ruleMatchers" (array of objects) - the group filters for passing through the group rules only a subset of logs. Each object in the array should contain the field for the matcher and the constraint. The field must be one of applicationName, subsystemName, or severity, and the constraint (string) that will be the value for the chosen field (if the field is severity, the value should be one: debug, verbose, info, warning, error, critical)
E.g
[
{
"field":"applicationName",
"constraint":"prod"
},
{
"field":"severity",
"constraint":"info"
}
]
DeleteDELETEhttps://api.coralogix.com/api/v1/external/group/GROUPID

Rules API

 Request typeURLBody
CreatePOSThttps://api.coralogix.com/api/v1/external/rule/GROUPID"Type" [string] (block, extract, parse, jsonextract, replace, timestampextract, removefields)

"Name" [string] - The name of the rule to create

"Rule" [string] - The regex of the rule [must be a regex that can be compiled except for "removefields" in which it must be a comma-separated list of fields to be removed]
timestampextract rule's body must not contain the "rule" field

(Optional) The body is allowed to contain: "SourceField" [string] - If not stated in the body then the default source field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2...

(Optional) The body is allowed to contain: "DestinationField" [string] - If not stated in the body then the default destination field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2...

In case the rule type is 'extract' or 'block' :
The body is not allowed to contain: "ReplaceNewVal" and "DestinationField"

In case the rule type is 'parse' :
The body is not allowed to contain: "ReplaceNewVal"

In case the rule type is 'jsonextract' :

  • The body is not allowed to contain: "ReplaceNewVal"

  • The body must contain "DestinationField" [string] (one of those strings "category", "className", "methodName", "severity", "threadId")


In case the rule type is 'replace' :
The body must contain: "ReplaceNewVal"

In case the rule type is 'timestampextract' :

  • The body is not allowed to contain: "rule"

  • The body is not allowed to contain: "DestinationField"

  • The body should contain meaningful "SourceField" [string] (if not specified by default text field will be set as the source field and the rule will not work. You should set the value as text.Your_Time_Field_Name)

  • The body must contain "formatStandard" [string] (javasdf, golang, strftime, secondsts, millits, microts, nanots)

  • The body must contain "timeFormat" [string] (you can see our suggestion for each type of standard, normally you will need to change the format to match your time field string pattern with the while comply to the standard)



In case the rule type is 'removefields' :
The body must contain: "rule" [string] (comma-separated list of fields)

The body may always contain (regardless of type) :

"Description" [string] - a description for the rule

"Enabled" [boolean] - a boolean indicator for rather the rule is activated or not
ReadGEThttps://api.coralogix.com/api/v1/external/rule/RULEID/group/GROUPID
UpdatePUThttps://api.coralogix.com/api/v1/external/rule/RULEID/group/GROUPID"Name" [string] - The updated name for the rule

"Rule" [string] - The regex of the rule [must be a regex that can be compiled except for "removefields" in which it must be a comma-separated list of fields to be removed]
timestampextract rule's body must not contain the "rule" field

(Optional) The body is allowed to contain: "SourceField" [string] - If not stated in the body then the default source field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2...

(Optional) The body is allowed to contain: "DestinationField" [string] - If not stated in the body then the default destination field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2...

In case the rule type is 'extract' or 'block' :
The body is not allowed to contain: "ReplaceNewVal" and "DestinationField"

In case the rule type is 'parse' :
The body is not allowed to contain: "ReplaceNewVal"

In case the rule type is 'jsonextract' :

  • The body is not allowed to contain: "ReplaceNewVal"

  • The body may contain "DestinationField" [string] ( one of those strings "category", "className", "methodName", "severity", "threadId")


In case the rule type is 'replace' :
The body may contain: "ReplaceNewVal"

In case the rule type is 'timestampextract' :

  • The body is not allowed to contain: "rule"

  • The body is not allowed to contain: "DestinationField"

  • The body should contain meaningful "SourceField" [string] (if not specified by default text field will be set as the source field and the rule will not work. You should set the value as text.Your_Time_Field_Name)

  • The body must contain "formatStandard" [string] (javasdf, golang, strftime, secondsts, millits, microts, nanots)

  • The body must contain "timeFormat" [string] (you can see our suggestion for each type of standard, normally you will need to change the format to match your time field string pattern with the while comply to the standard)



In case the rule type is 'removefields' :
The body must contain: "rule" [string] (comma-separated list of fields)

The body may always contain (regardless of type) :

"Description" [string] - a description for the rule

"Enabled" [boolean] - a boolean indicator for rather the rule is activated or not
DeleteDELETEhttps://api.coralogix.com/api/v1/external/rule/RULEID/group/GROUPID

Exporting multiple Rules and Groups

 Request typeURLHeaders
Get all RulesGEThttps://api.coralogix.com/api/v1/external/rulesContent-Type: application/json

Authorization: Bearer { API KEY of team A }

The result will be a JSON object containing all the company Rules and Groups information
Transfer rulesPOSThttps://api.coralogix.com/api/v1/external/rules/exportContent-Type: application/json

Authorization: Bearer { API KEY of team B }

The body should contain the JSON object you got from executing the GET request (copy and paste the output of the GET request to the body of the POST request *without changing anything*)

A message stating "Group and Rules transformed successfully" will be prompt once the transfer completed.

NOTE
When moving rules from one account to another keep in mind that the rules groups you imported are concatenated after the existing rules groups, we do not override existing groups by default. If you want to override the existing groups you should first remove them entirely and then import

In order to get the groupId so you could use it with the different requests’ URLs, enter your account settings –> Rules. Click on any group and the browser URL will show the groupId. The ruleId on the other hand can only be retrieved when executing a GET request to get a certain rule/group or when getting all the rules of the account.

To learn more about log parsing in Coralogix, read the tutorial.

Read our Regular Expressions 101 guide if you need some pointers on RegEx.