---
id: logging
title: Logging & Webhooks
sidebar_label: Logging & Webhooks
keywords: [hyperglass, logging, webhook, hooks, syslog]
description: hyperglass Logging
---

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

<div class="table--full-width" />

## 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:

| Parameter   |  Type  | Default  | Description                                        |
| :---------- | :----: | :------- | :------------------------------------------------- |
| `directory` | String | `'/tmp'` | Valid directory where the log file can be written. |
| `format`    | String | `'text'` | Log format - may be either `'text'` or `'json'`.   |
| `max_size`  | String | `'50MB'` | Maximum log file size before logs are rotated.     |

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

| Section  | Description           |              All Options               |
| :------- | :-------------------- | :------------------------------------: |
| `syslog` | Syslog settings       |  <PageLink to="#syslog">➡️</PageLink>  |
| `http`   | HTTP webhook settings | <PageLink to="#webhooks">➡️</PageLink> |

:::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.

| Parameter |  Type   | Default | Description                                       |
| :-------- | :-----: | :------ | :------------------------------------------------ |
| `enable`  | Boolean | `true`  | Optionally disable syslogging even if configured. |
| `host`    | String  |         | Syslog target IP address or hostname.             |
| `port`    | Integer | `514`   | Syslog 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.

| Parameter    |  Type   | Default     | Description                                                                                               |
| :----------- | :-----: | :---------- | :-------------------------------------------------------------------------------------------------------- |
| `enable`     | Boolean | `true`      | Optionally disable webhooks even if configured.                                                           |
| `host`       | String  |             | HTTP URL to webhook target.                                                                               |
| `headers`    | Mapping |             | Any arbitrary mappings, which will be sent as HTTP headers.                                               |
| `params`     | Mapping |             | Any arbitrary mappings, which will be sent as URL parameters (e.g. `http://example.com/log?param=value`). |
| `verify_ssl` | Boolean | `true`      | Verify SSL certificate of target.                                                                         |
| `timeout`    | Integer | `5`         | Time in seconds before request times out.                                                                 |
| `provider`   | String  | `'generic'` | Webhook provider.                                                                                         |

### Supported Providers

| Provider                                                                                             | Parameter Value |
| :--------------------------------------------------------------------------------------------------- | --------------: |
| Generic                                                                                              |     `'generic'` |
| [Microsoft Teams](https://www.microsoft.com/en-us/microsoft-365/microsoft-teams/group-chat-software) |     `'msteams'` |
| [Slack](https://slack.com/)                                                                          |       `'slack'` |

### Authentication

Basic and API key authentication are supported.

| Parameter  |  Type  | Default   | Description                                                               |
| :--------- | :----: | :-------- | :------------------------------------------------------------------------ |
| `mode`     | String | `'basic'` | Authentication mode. Must be `'basic'` or `'api_key'`                     |
| `username` | String |           | Username for basic authentication.                                        |
| `password` | String |           | Password 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:

```json
{
  "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

```yaml title="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
```
