Webhook Log Handler Directives

The Webhook Log Handler allows RealityServer to send HTTP requests in response to log messages. Since sending a HTTP request for every log entry would not be practical or useful the log handler provides options to filter which log messages will trigger HTTP requests. Only log messages matching the filters will cause a request to be sent.

Log messages can be filtered by tags, severity, module, and category. These are all specified as comma separated lists of strings. If a given filter is provided, only messages matching at least one of the items in the list will trigger requests. Not providing a filter removes it from consideration when choosing which messages trigger requests.

Additionally the webhook_url, body_template and header directives all support the use of template expansion in their values. This may be any text and variables enclosed with in two sets of curly braces {{}} will be replaced at run time with values from the log message. Valid replacement variables are given in the table below.

Several other options are provided to give complete control over the HTTP request. These include control over certificate validation, redirection behaviour, timeouts and headers. Here is an example configuration for the Webhook Log Handler.

<user log_webhook>
webhook_url https://maker.ifttt.com/trigger/my_event/with/key/apikey?value1={{code}}
method POST
header Content-Type: application/json
header X-MIG-Custom: RealityServer!
header X-MIG-Code: {{code}}
body_template { "value1": "{{module}}", "value2": "{{severity}}", "value3": "{{message}}" }
tags unrecoverable, memory
severity fatal, error
</user>

This example defines a Webhook Log Handler which uses the popular IFTTT service to take an action by sending a HTTP POST request containing JSON data. It also sets a custom header and applies filters to the tags and severity level. It shows how to use template replacement strings in the webhook_url, header and body_template directives.

Multiple webhook endpoints are supported and are configured independently. However to use multiple endpoints you must enclose the configurations in a <user log_webhooks></user> (plural) directive so that the contents of the configurations are not merged together (as occurs when specified in the global context). An endpoint will not be used if its configuration fails. This could be due to missing or invalid configuration directives. Header list and strings are passed in directly to the HTTP request (after template substitution). This means that invalid headers and URLs will not be detected until a log message is forwarded and a request is made.

Booleans are assumed to be off and integers are set to 0 if they cannot be parsed, regardless of their default value. If a HTTP request fails, a runtime error will be logged under category LOGWEB which will always be ignored by the log handler internally. If the request results in a HTTP code in the 4xx or 5xx range a LOGWEB error will also be logged. The sections below provide a complete list of all available configuration options.

webhook_url

This is the URL to which the request will be sent when the defined type of log entry is encountered. The URL may include template variables which will be expanded prior to sending the request.

method

Defines the HTTP method (verb) to be used when making the request. Currently only the GET and POST methods are supported. If the GET method is used the body_template directive will be ignored if supplied.

header

Adds the defined custom header to the request. Multiple header directives can be provided. The directive may include template variables which will be expanded prior to sending the request.

body_template

Defines the body of the request when using the HTTP POST method. The directive may include template variables which will be expanded prior to sending the request.

tags

A comma separated list of log message tags which if encountered will cause a request to be sent. Messages which do not contain any of the listed tags will be ignored. If no tags are specified then tags will not be considered when identifying messages which trigger requests. The table below lists the supported tags.

severity

A comma separated list of log severity levels which if encountered will cause a request to be sent. Messages which do not contain any of the listed severity levels will be ignored. If no severity levels are specified then severity will not be considered when identifying messages which trigger requests. The table below lists the supported severity levels.

module

Log messages have an associated module and category pair. This option is a comma separated list of module names which if encountered will cause a request to be sent. Messages which do not contain any of the listed module names will be ignored. If no module names are specified then module name will not be considered when identifying messages which trigger requests. Module names can be any string which does not contain a colon character and are case sensitive.

category

Log messages have an associated module and category pair. This option is a comma separated list of category names which if encountered will cause a request to be sent. Messages which do not contain any of the listed category names will be ignored. If no category names are specified then category name will not be considered when identifying messages which trigger requests. Category names can be any string and are case sensitive. Iray uses internal category names which differ from those shown in the logs, it is the internal name which is matched against. The valid internal category names are DATABASE, DISK, GEOMETRY, IMAGE, IO, MAIN, MISC, MEMORY, NETWORK, PLUGIN and RENDER. However please note that Iray may also use undocumented category names internally. Therefore it is generally not recommended to filter messages based on category.

timeout

Defines the timeout for the request to complete. The default value of 0 specifies that there will be no timeout.

connect_timeout

Defines the timeout for the connection to complete. The default value is 300 seconds.

follow_redirects

Whether the request should automatically follow redirects. Note that by default, redirects are followed indefinitely. Set redirect_limit to change this behaviour. When following certain 3xx response codes, the original request method is changed to GET to maintain consistency with web browsers. Set the redirect_codes directive to disable this behaviour specific response codes.

max_redirects

The maximum number of redirects allowed when making a request. The default of -1 allows unlimited redirects.

authenticate_redirects

Whether requests that are redirected to other hosts should have authentication information from the original request applied to them.

redirect_codes

The redirect codes that will maintain HTTP method when followed. Provided as a comma separated list of codes. Valid codes are none, 301, 302, 303 and all.

verify_ssl

Determines whether SSL certificates must be verified for a request to succeed.

log_request_errors

If set to on, then extra messages will be logged whenever a request fails using the module LOGWEB. These extra messages will always be ignored by the forwarder internally. If the request results in a http code in the 4xx or 5xx range a LOGWEB error will also be recorded.