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

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:

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

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

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": {
        "content-length": "103",
        "accept": "application/json, text/plain, */*",
        "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",
        "content-type": "application/json;charset=UTF-8",
        "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
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
```