# Logging

faucet takes care of logging both HTTP requests and responses, as well as
the `stdout` and `stderr` of the worker processes. This section describes
how logging works in faucet and how to filter the logs.

## Basic structure

All logs generated by faucet take the following form:

```
[<time stamp> level <source>] <message>
```

 - The time stamp is the format `YYYY-MM-DDTHH:MM:SSZ` and is in UTC.
 - The level is one of:
    - `ERROR`
    - `WARN`
    - `INFO`
    - `DEBUG`
    - `TRACE`
 - The source is either `faucet` or the name of the worker `Worker::<id>`.


## HTTP logging

HTTP logs are all logged at the `INFO` level. The source is the worker in
charge of handling the request. The message has the following form:

```
<ip> "<method> <path> <protocol>" <status> "<user-agent>" <duration>
```

 - `ip` is the IP address of the client (determined by the `--ip-from` option).
 - `method` is the HTTP method used.
 - `path` is the path of the request.
 - `protocol` is the HTTP protocol version used.
 - `status` is the HTTP status code returned.
 - `user-agent` is the user agent of the client.
 - `duration` is the time it took to handle the request in milliseconds.

## Worker logging

Worker logs are divided into two components: `stdout` and `stderr`.
`stdout` is logged at the `INFO` level and `stderr` is logged at the `WARN`
level. The source is the worker who owns the underlying process. The message
is the line of output from the process.

## Filtering logs

By default, faucet logs at the `INFO` level, which means that `ERROR`,
`WARN`, and `INFO` logs are shown. To change the log level, use the
`FAUCET_LOG` environment variable.

> **Note:** Plumber prints errors that occur on endpoints to `stdout`, so
> if you want to see those errors, you will need to set the log level to
> `INFO` or lower. Shiny on the other hand prints errors to `stderr`, so
> you will need to set the log level to `WARN` or lower to see those errors.

## Writing logs a file

faucet allows you to redirect log output to a file. This will disable colors
on `stderr`.

You can redirect to a file by specifying the path on the `FAUCET_LOG_FILE`
environment variable or by passing the `--log-file` argument to `faucet start`
or `faucet router`.