Logging & Webhooks

hyperglass supports multiple types of logging, for both application troubleshooting and general reporting.

File Logging

By default, hyperglass writes all log messages to a log file located at /tmp/hyperglass.log. This behavior and other file logging parameters may be overridden if needed:

directoryString'/tmp'Valid directory where the log file can be written.
formatString'text'Log format - may be either 'text' or 'json'.
max_sizeString'50MB'Maximum log file size before logs are rotated.

The logging subsection contains additional subsections of its own for configuring other logging methods:

SectionDescriptionAll Options
syslogSyslog settings
httpHTTP webhook settings

You do not have to set enable: false to disable syslogging or webhooks - if there is no configuration under the syslog or http subsections, it the option is disabled by default. The enable option exists for easy toggling without having to delete the other settings.


If syslogging is enabled, all of the same log messages written to the file and/or stdout will be forwarded to the syslog server.

enableBooleantrueOptionally disable syslogging even if configured.
hostStringSyslog target IP address or hostname.
portInteger514Syslog target UDP port number.


If http logging is enabled, an HTTP POST will be sent to the configured target every time a query is submitted, after it is validated.

enableBooleantrueOptionally disable webhooks even if configured.
hostStringHTTP URL to webhook target.
headersMappingAny arbitrary mappings, which will be sent as HTTP headers.
paramsMappingAny arbitrary mappings, which will be sent as URL parameters (e.g. http://example.com/log?param=value).
verify_sslBooleantrueVerify SSL certificate of target.
timeoutInteger5Time in seconds before request times out.
providerString'generic'Webhook provider.

Supported Providers

ProviderParameter Value
Microsoft Teams'msteams'


Basic and API key authentication are supported.

modeString'basic'Authentication mode. Must be 'basic' or 'api_key'
usernameStringUsername for basic authentication.
passwordStringPassword for basic authentication, or API Key for API key authentication.

If api_key is used, the header X-API-Key: {key} is added to the request, where {key} is the password.

Webhook Data Structure

If the provider field is set to 'generic', the webhook will POST JSON data in the following format:

"query_location": "router01",
"query_type": "bgp_route",
"query_vrf": "default",
"query_target": "",
"headers": {
"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.163 Safari/537.36",
"referer": "http://lg.example.com/",
"accept-encoding": "gzip, deflate, br",
"accept-language": "en-US,en;q=0.9,fr;q=0.8,lb;q=0.7,la;q=0.6"
"source": "",
"network": {
"prefix": "",
"asns": ["64496"]

Full example

directory: /var/log
format: json
max_size: 10 MB
host: syslog.example.com
host: "https://example.com/logs"
mode: basic
username: your username
password: your password
X-Special-Header: your header value
app: hyperglass # URL would be https://example.com/logs?app=hyperglass
verify_ssl: false