# `synapse` logging configuration

Synapse uses a `buffer` handler per default, which flushes
periodically, but flushes logs immediately for log events
with a level greater or equal to WARNING.

To set your desired log level, specify it in `synapse_log_config_root_level`.

## Formatters

By default, the upstream `precise` formatter is availabe. To define and use
more formatters, extend `synapse_log_config_formatters` like this:

```yaml
synapse_log_config_formatters_custom_json:
  custom_json:
    format: >-
      {"lineno": %(lineno)d, "level": "%(levelname)s", "req_id": "%(request)s", "msg": "%(message)s"}
synapse_log_config_formatters: >-2
  {{
    ({ synapse_log_config_formatters_precise_name: synapse_log_config_formatters_precise })
    | combine(synapse_log_config_formatters_custom_json)
  }}

# Set handlers to use your formatter like this
synapse_log_config_handlers_file_formatter: custom_json
synapse_log_config_handlers_console_formatter: custom_json
```

## Handlers

For modifying the built-in `file`/`buffer`/`console` handlers, see
[the defaults in `../defaults/main/log.config.yml`](../defaults/main/log.config.yml).

### Containers

For typical container setups, it is often recommended to log all
logs to `stdout`/`stderr`. This can be easily archieved by setting
`synapse_log_config_root_handlers: [ synapse_log_config_handlers_console_name ]`.

## Child loggers

To set a different configuration / log level for child loggers of
the root logger (currently, this is only `synapse.storage.SQL`),
override `synapse_log_config_loggers` directly or for the SQL loggers,
set the level in `synapse_log_config_loggers_synapse_storage_sql_level`
(which defaults to `synapse_log_config_root_level`).