view mod_log_ringbuffer/README.markdown @ 4362:116c88c28532

mod_http_admin_api: restructure group-related info in API - Return the members of the group right in the get_group_by_id call. This is an O(1) of extra work. - Remove the groups attribute from get_user_by_name as that is O(n) of work and rarely immediately needed. The replacement for the group membership information in the user is for now to use the group API and iterate; future work may fix that.
author Jonas Schäfer <jonas@wielicki.name>
date Wed, 20 Jan 2021 15:30:29 +0100
parents df2ccb42a241
children c0493d3173c1
line wrap: on
line source

---
labels:
- 'Stage-Beta'
summary: 'Log to in-memory ringbuffer'
...

Introduction
============

Sometimes debug logs are too verbose for continuous logging to disk. However
occasionally you may be interested in the debug logs when a certain event occurs.

This module allows you to store all logs in a fixed-size buffer in Prosody's memory,
and dump them to a file whenever you want.

# Configuration

First of all, you need to load the module by adding it to your global `modules_enabled`:

``` {.lua}
modules_enabled = {
    ...
    "log_ringbuffer";
    ...
}
```

By default the module will do nothing - you need to configure a log sink, using Prosody's
usual [logging configuration](https://prosody.im/doc/advanced_logging).

``` {.lua}
log = {
    -- Log errors to a file
    error = "/var/log/prosody/prosody.err";

    -- Log debug and higher to a 2MB buffer
    { level = "debug", to = "ringbuffer", size = 1024*1024*2, filename = "debug-logs-{pid}-{count}.log", signal = "SIGUSR2" };
}
```

The possible fields of the logging config entry are:

`to`
:   Set this to `"ringbuffer"`.

`level`
:   The minimum log level to capture, e.g. `"debug"`.

`size`
:   The size, in bytes, of the buffer. When the buffer fills,
    old data will be overwritten by new data.

`lines`
:   If specified, preserves the latest N complete lines in the
    buffer. The `size` option is ignored when this option is set.

`filename`
:   The name of the file to dump logs to when triggered.

`filename_template`
:   This parameter may optionally be specified instead of `filename. It
    may contain a number of variables, described below. Defaults to
    `"{paths.data}/ringbuffer-logs-{pid}-{count}.log"`.

Only one of the following triggers may be specified:

`signal`
:   A signal that will cause the buffer to be dumped, e.g. `"SIGUSR2"`.
    Do not use any signal that is used by any other Prosody module, to
    avoid conflicts.

`event`
:   Alternatively, the name of a Prosody global event that will trigger
    the logs to be dumped, e.g. `"config-reloaded"`.

## Filename variables

If `filename_template` is specified instead of `filename`, it may contain
any of the following variables in curly braces, e.g. `{pid}`.

`pid`
:   The PID of the current process

`count`
:   A counter that begins at 0 and increments for each dump made by
    the current process.

`time`
:   The unix timestamp at which the dump is made. It can be formatted
    to human-readable local time using `{time|yyyymmdd}` and `{time|hhmmss}`.

`paths`
:   Allows access to Prosody's known filesystem paths, use e.g. `{paths.data}`
    for the path to Prosody's data directory.

The filename does not have to be unique for every dump - if a file with the same
name already exists, it will be appended to.

## Integration with mod_debug_traceback

This module can be used in combination with [mod_debug_traceback] so that debug
logs are dumped at the same time as the traceback. Use the following configuration:

``` {.lua}
log = {
	---
	-- other optional logging config here --
	---

	{
		to = "ringbuffer";
		level = "debug";
		filename_template = "{paths.data}/traceback-{pid}-{count}.log";
		event = "debug_traceback/triggered";
	};
}
```

If the filename template matches the traceback path, both logs and traceback will
be combined into the same file. Of course separate files can be specified if preferred.

# Compatibility

0.11 and later.