Mercurial > prosody-modules

comparison mod_log_ringbuffer/README.md @ 5975:fe081789f7b5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
All community modules: Unify file extention of Markdown files to .md
author Menel <menel@snikket.de>
date Tue, 22 Oct 2024 10:26:01 +0200
parents mod_log_ringbuffer/README.markdown@133b23758cf6
children 8a47791338fc
comparison
equal deleted inserted replaced
5974:5a65a632d5b9 5975:fe081789f7b5
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 { to = "ringbuffer", size = 1024*1024*2, filename_template = "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 `levels`
47 : The log levels to capture, e.g. `{ min = "debug" }`. By default, all levels are captured.
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 `lines`
54 : If specified, preserves the latest N complete lines in the
55 buffer. The `size` option is ignored when this option is set.
56
57 `filename`
58 : The name of the file to dump logs to when triggered.
59
60 `filename_template`
61 : This parameter may optionally be specified instead of `filename. It
62 may contain a number of variables, described below. Defaults to
63 `"{paths.data}/ringbuffer-logs-{pid}-{count}.log"`.
64
65 Only one of the following triggers may be specified:
66
67 `signal`
68 : A signal that will cause the buffer to be dumped, e.g. `"SIGUSR2"`.
69 Do not use any signal that is used by any other Prosody module, to
70 avoid conflicts.
71
72 `event`
73 : Alternatively, the name of a Prosody global event that will trigger
74 the logs to be dumped, e.g. `"config-reloaded"`.
75
76 ## Filename variables
77
78 If `filename_template` is specified instead of `filename`, it may contain
79 any of the following variables in curly braces, e.g. `{pid}`.
80
81 `pid`
82 : The PID of the current process
83
84 `count`
85 : A counter that begins at 0 and increments for each dump made by
86 the current process.
87
88 `time`
89 : The unix timestamp at which the dump is made. It can be formatted
90 to human-readable local time using `{time|yyyymmdd}` and `{time|hhmmss}`.
91
92 `paths`
93 : Allows access to Prosody's known filesystem paths, use e.g. `{paths.data}`
94 for the path to Prosody's data directory.
95
96 The filename does not have to be unique for every dump - if a file with the same
97 name already exists, it will be appended to.
98
99 ## Integration with mod_debug_traceback
100
101 This module can be used in combination with [mod_debug_traceback] so that debug
102 logs are dumped at the same time as the traceback. Use the following configuration:
103
104 ``` {.lua}
105 log = {
106 ---
107 -- other optional logging config here --
108 ---
109
110 {
111 to = "ringbuffer";
112 filename_template = "{paths.data}/traceback-{pid}-{count}.log";
113 event = "debug_traceback/triggered";
114 };
115 }
116 ```
117
118 If the filename template matches the traceback path, both logs and traceback will
119 be combined into the same file. Of course separate files can be specified if preferred.
120
121 # Compatibility
122
123 0.12 and later.