Mercurial > prosody-modules

annotate mod_log_ringbuffer/README.markdown @ 4205:481c4d75e77d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
author Matthew Wild <mwild1@gmail.com>
date Thu, 15 Oct 2020 16:47:21 +0100
parents
children 86f8ece24029
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4205
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Log to in-memory ringbuffer'
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Introduction
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 ============
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 Sometimes debug logs are too verbose for continuous logging to disk. However
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 occasionally you may be interested in the debug logs when a certain event occurs.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 This module allows you to store all logs in a fixed-size buffer in Prosody's memory,
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 and dump them to a file whenever you want.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 # Configuration
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 First of all, you need to load the module by adding it to your global `modules_enabled`:
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 ``` {.lua}
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 modules_enabled = {
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 ...
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 "log_ringbuffer";
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 ...
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 }
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 ```
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 By default the module will do nothing - you need to configure a log sink, using Prosody's
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 usual [logging configuration](https://prosody.im/doc/advanced_logging).
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 ``` {.lua}
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 log = {
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 -- Log errors to a file
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 error = "/var/log/prosody/prosody.err";
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 -- Log debug and higher to a 2MB buffer
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 { level = "debug", to = "ringbuffer", size = 1024*1024*2, filename = "debug-logs-{pid}-{count}.log", signal = "SIGUSR2" };
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 }
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 ```
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 The possible fields of the logging config entry are:
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 `to`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 : Set this to `"ringbuffer"`.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 `level`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 : The minimum log level to capture, e.g. `"debug"`.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 `size`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 : The size, in bytes, of the buffer. When the buffer fills,
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 old data will be overwritten by new data.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 `filename`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 : The name of the file to dump logs to when triggered. The filename may
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 contain a number of variables, described below.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 Only one of the following triggers may be specified:
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 `signal`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 : A signal that will cause the buffer to be dumped, e.g. `"SIGUSR2"`.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 Do not use any signal that is used by any other Prosody module, to
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 avoid conflicts.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 `event`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 : Alternatively, the name of a Prosody global event that will trigger
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 the logs to be dumped, e.g. `"config-reloaded"`.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 ## Filename variables
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 `pid`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 : The PID of the current process
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 `count`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 : A counter that begins at 0 and increments for each dump made by
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 the current process.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 `time`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 : The unix timestamp at which the dump is made. It can be formatted
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 to human-readable local time using `{time|yyyymmdd}` and `{time|hhmmss}`.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81 `paths`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82 : Allows access to Prosody's known filesystem paths, use e.g. `{paths.data}`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 for the path to Prosody's data directory.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 The filename does not have to be unique for every dump - if a file with the same
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 name already exists, it will be appended to.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88 # Compatibility
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90 0.11 and later.