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:

ParameterTypeDefaultDescription
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
➡️
note

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.

Syslog

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

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

Webhooks

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.

ParameterTypeDefaultDescription
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
Generic'generic'
Microsoft Teams'msteams'
Slack'slack'

Authentication

Basic and API key authentication are supported.

ParameterTypeDefaultDescription
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.
important

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": "1.1.1.0/24",
"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": "192.0.2.1",
"network": {
"prefix": "192.0.2.0/24",
"asns": ["64496"]
}
}

Full example

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