Mercurial > prosody-modules
annotate mod_log_ringbuffer/README.markdown @ 4205:481c4d75e77d
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 |
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. |