Mercurial > prosody-modules

annotate mod_log_ringbuffer/README.markdown @ 4211:0f26ae2f2a74

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites_page: Change client selection button text from 'Install' to 'Select' by default This also allows specific clients entries to override the text via the 'select_text' field. Rationale: 1) users may already have the software installed, we still want them to select it anyway for the tailored setup experience. 2) some clients (e.g. web clients) are not really "installed" so the text was misleading
author Matthew Wild <mwild1@gmail.com>
date Fri, 16 Oct 2020 11:06:25 +0100
parents 481c4d75e77d
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.