1 ---

     2 labels:

     3 - 'Stage-Beta'

     4 summary: 'Log to in-memory ringbuffer'

     5 ...

     6 

     7 Introduction

     8 ============

     9 

    10 Sometimes debug logs are too verbose for continuous logging to disk. However

    11 occasionally you may be interested in the debug logs when a certain event occurs.

    12 

    13 This module allows you to store all logs in a fixed-size buffer in Prosody's memory,

    14 and dump them to a file whenever you want.

    15 

    16 # Configuration

    17 

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

    19 

    20 ``` {.lua}

    21 modules_enabled = {

    22     ...

    23     "log_ringbuffer";

    24     ...

    25 }

    26 ```

    27 

    28 By default the module will do nothing - you need to configure a log sink, using Prosody's

    29 usual [logging configuration](https://prosody.im/doc/advanced_logging).

    30 

    31 ``` {.lua}

    32 log = {

    33     -- Log errors to a file

    34     error = "/var/log/prosody/prosody.err";

    35 

    36     -- Log debug and higher to a 2MB buffer

    37     { level = "debug", to = "ringbuffer", size = 1024*1024*2, filename = "debug-logs-{pid}-{count}.log", signal = "SIGUSR2" };

    38 }

    39 ```

    40 

    41 The possible fields of the logging config entry are:

    42 

    43 `to`

    44 :   Set this to `"ringbuffer"`.

    45 

    46 `level`

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

    48 

    49 `size`

    50 :   The size, in bytes, of the buffer. When the buffer fills,

    51     old data will be overwritten by new data.

    52 

    53 `filename`

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

    55     contain a number of variables, described below.

    56 

    57 Only one of the following triggers may be specified:

    58 

    59 `signal`

    60 :   A signal that will cause the buffer to be dumped, e.g. `"SIGUSR2"`.

    61     Do not use any signal that is used by any other Prosody module, to

    62     avoid conflicts.

    63 

    64 `event`

    65 :   Alternatively, the name of a Prosody global event that will trigger

    66     the logs to be dumped, e.g. `"config-reloaded"`.

    67 

    68 ## Filename variables

    69 

    70 `pid`

    71 :   The PID of the current process

    72 

    73 `count`

    74 :   A counter that begins at 0 and increments for each dump made by

    75     the current process.

    76 

    77 `time`

    78 :   The unix timestamp at which the dump is made. It can be formatted

    79     to human-readable local time using `{time|yyyymmdd}` and `{time|hhmmss}`.

    80 

    81 `paths`

    82 :   Allows access to Prosody's known filesystem paths, use e.g. `{paths.data}`

    83     for the path to Prosody's data directory.

    84 

    85 The filename does not have to be unique for every dump - if a file with the same

    86 name already exists, it will be appended to.

    87 

    88 # Compatibility

    89 

    90 0.11 and later.