---
title: Logging
description: >-
  The logging configuration can be set using the logging key in the HCL
  configuration file.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.page/luizfonseca/super/llms.txt
> Use this file to discover all available pages before exploring further.

## Logging

### HCL Configuration

The logging configuration can be set using the `logging` key in the HCL configuration file. The default configuration is:

**config.hcl**
```hcl
logging {
  level = "info"
  access_logs_enabled = true
  error_logs_enabled = true
  format = "json"
  # path = "/var/log/proksi" # write to files instead of stdout
  rotation = "never"
}
```

You can customize the logging configuration by adding the following keys to the `logging` block:

| Key                   | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| level                 | The logging level (`debug`, `info`, `warn`, `error`, `trace`)   |
| access\_logs\_enabled | Whether to enable access logs (default: true)                   |
| error\_logs\_enabled  | Whether to enable error logs (default: true)                    |
| format                | The logging format (`json`, `pretty`)                           |
| path                  | A directory to write log files to (default: none, stdout)       |
| rotation              | The rotation frequency (`daily`, `hourly`, `minutely`, `never`) |

For example, to set the logging level to `debug`, the format to `pretty`, the path to `/var/log/proksi`, and the rotation to `daily`, you can use the following configuration:

```hcl
logging {
  level = "debug"
  format = "pretty"
  path = "/var/log/proksi"
  rotation = "daily"
}
```

This will then create a log file named `proksi.<date>.log` in the `/var/log/proksi` directory and rotate it daily.

### Access logs

Every request gets an access log line (`access_log: true`) with its method, path, host, status, duration, client and upstream:

```json
{ "method": "GET", "path": "/", "host": "example.com", "status_code": 200, "duration_ms": "1", "proxy_ms": 0.084, "upstream_ms": 0.912, "client_ip": "203.0.113.7", "remote_addr": "172.70.42.10:43120", "x_forwarded_for": "203.0.113.7", "upstream_addr": "10.0.0.5:8080", "reused_connection": "true", "http_version": "http/2", "access_log": true }
```

- `client_ip` is the address of the connection, or behind [`server.trusted_proxies`](/routing/headers), the client they forwarded.
- `remote_addr` is the address of the connection: behind trusted proxies, the last of them (such as a Cloudflare server).
- `x_forwarded_for` is the request's `X-Forwarded-For`, as sent, whether proksi trusts it or not.
- `upstream_addr` is the upstream the request was sent to, and `reused_connection` whether its connection was reused.
- `duration_ms` is the whole request: from its headers to the end of its response (body included).
- `proxy_ms` is the proxy's own time before the request went to an upstream (routing, rules, plugins), or the whole request when no upstream was involved (cache, redirects, plugins that answer). `upstream_ms` is the upstream's time until its response headers came (connecting and retries included). Both have microsecond precision; what's left of `duration_ms` is the response body's transfer. Super only.

Health checks (`/ping`) aren't logged, nor counted in [metrics](/configuration/admin).

Every connection of a [`tcp` block](/routing/tcp) gets one too, once it closes:

```json
{ "protocol": "tcp", "block": "tcp \"db\" in host \"db.example.com\"", "client_ip": "10.0.0.7:51234", "server_name": "db.example.com", "upstream": "10.0.0.5:5432", "duration_ms": 61234, "bytes_in": 5120, "bytes_out": 81920, "access_log": true }
```

`server_name` is set when TLS is terminated, `upstream` once one was chosen, and `error` when the connection couldn't be forwarded (no healthy upstream, or the upstream refused it) or ended with an error. A connection closed before any bytes flowed (a client checking it can connect, then hanging up) has no `error`: it's a normal close. `access_logs_enabled = false` turns both off.

### Logging under heavy load

Logs are written in the background, so writing them never slows down requests. Up to 100,000 log lines can be waiting to be written; if the output can't keep up beyond that (e.g. a slow disk or a stalled pipe), new lines are dropped and a warning with the number of dropped lines is logged once it catches up.

### Failed TLS handshakes

Clients that give up on a TLS handshake (scanners, load balancers' TCP health checks, browsers closing connections they opened ahead of time) are common and aren't a problem with Super, so they're only logged with `level = "debug"` (or `trace`). They're counted in the `proksi_tls_handshake_failures_total` metric (see [Admin API and metrics](/configuration/admin#metrics)).

### Logging Levels (CLI)

The logging level can be set using the `--log.level` flag. The default level is `info`.

| Level | Description                         |
| ----- | ----------------------------------- |
| debug | Shows debug information             |
| info  | Shows information about the service |
| warn  | Shows warnings                      |
| error | Shows errors                        |
| trace | Shows trace information             |

### Logging Format

The logging format can be set using the `--log.format` flag. The default format is `json`.

| Format | Description                     |
| ------ | ------------------------------- |
| json   | Logs in JSON format             |
| pretty | Logs in a human-readable format |

### Logging Path

The logging path can be set using the `--log.path` flag. By default, logs are written to stdout.

If a path is provided, the logs will be written to a file in the specified path. The file name will be prefixed or named `proksi.log.*`.

### Logging Rotation

The logging rotation is set with `rotation` in the `logging` block (it has no command-line flag), for log files written to `path`. The default rotation is `never`.

| Rotation | Description                   |
| -------- | ----------------------------- |
| daily    | Rotates the log file daily    |
| hourly   | Rotates the log file hourly   |
| minutely | Rotates the log file minutely |
| never    | Does not rotate the log file  |

### Logging Examples

Here are some examples of how to set the logging level, format, path, and rotation:

```bash
# Set the logging level to debug
super --log.level debug

# Set the logging format to pretty
super --log.format pretty

# Set the logging path to /var/log/proksi
super --log.path /var/log/proksi

```

Each flag can also be set in the `logging` block, or with environment variables (`PROKSI_LOGGING__LEVEL`...).