prosody-modules: mod_log_ringbuffer/README.markdown annotate

annotate mod_log_ringbuffer/README.markdown @ 5799:c75328aeaba3

mod_http_oauth2: Reduce log level for error delivery via redirect This is supposed to be normal in OAuth2, not really deserving a warning log message.

author	Kim Alvefur <zash@zash.se>
date	Sat, 23 Dec 2023 00:06:35 +0100
parents	893b9c3c0d20
children	133b23758cf6

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
5363 893b9c3c0d20 mod_log_ringbuffer: Fix description and examples of level configuration Matthew Wild <mwild1@gmail.com> parents: 5362 diff changeset	37 { to = "ringbuffer", size = 102410242, filename_template = "debug-logs-{pid}-{count}.log", signal = "SIGUSR2" };
4205 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
5363 893b9c3c0d20 mod_log_ringbuffer: Fix description and examples of level configuration Matthew Wild <mwild1@gmail.com> parents: 5362 diff changeset	46 `levels`
893b9c3c0d20 mod_log_ringbuffer: Fix description and examples of level configuration Matthew Wild <mwild1@gmail.com> parents: 5362 diff changeset	47 : The log levels to capture, e.g. `{ min = "debug" }`. By default, all levels are captured.
4205 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
4226 df2ccb42a241 mod_log_ringbuffer: Add 'lines' option (actually an alternative ringbuffer implementation) Matthew Wild <mwild1@gmail.com> parents: 4220 diff changeset	53 `lines`
df2ccb42a241 mod_log_ringbuffer: Add 'lines' option (actually an alternative ringbuffer implementation) Matthew Wild <mwild1@gmail.com> parents: 4220 diff changeset	54 : If specified, preserves the latest N complete lines in the
df2ccb42a241 mod_log_ringbuffer: Add 'lines' option (actually an alternative ringbuffer implementation) Matthew Wild <mwild1@gmail.com> parents: 4220 diff changeset	55 buffer. The `size` option is ignored when this option is set.
df2ccb42a241 mod_log_ringbuffer: Add 'lines' option (actually an alternative ringbuffer implementation) Matthew Wild <mwild1@gmail.com> parents: 4220 diff changeset	56
4205 481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	57 `filename`
4219 b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	58 : The name of the file to dump logs to when triggered.
b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	59
b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	60 `filename_template`
b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	61 : This parameter may optionally be specified instead of `filename. It
b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	62 may contain a number of variables, described below. Defaults to
4215 86f8ece24029 mod_log_ringbuffer: Update default filename to include data path Matthew Wild <mwild1@gmail.com> parents: 4205 diff changeset	63 `"{paths.data}/ringbuffer-logs-{pid}-{count}.log"`.
4205 481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	64
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	65 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	66
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	67 `signal`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	68 : 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	69 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	70 avoid conflicts.
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	71
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	72 `event`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	73 : 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	74 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	75
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	76 ## Filename variables
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	77
4219 b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	78 If `filename_template` is specified instead of `filename`, it may contain
b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	79 any of the following variables in curly braces, e.g. `{pid}`.
b3dd77f2d0d7 mod_log_ringbuffer: Switch `filename` to not be interpolated, add filename_template which is Matthew Wild <mwild1@gmail.com> parents: 4215 diff changeset	80
4205 481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	81 `pid`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	82 : 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	83
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	84 `count`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	85 : 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	86 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	87
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	88 `time`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	89 : 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	90 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	91
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	92 `paths`
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	93 : 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	94 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	95
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	96 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	97 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	98
4220 0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	99 ## Integration with mod_debug_traceback
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	100
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	101 This module can be used in combination with [mod_debug_traceback] so that debug
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	102 logs are dumped at the same time as the traceback. Use the following configuration:
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	103
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	104 ``` {.lua}
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	105 log = {
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	106 ---
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	107 -- other optional logging config here --
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	108 ---
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	109
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	110 {
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	111 to = "ringbuffer";
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	112 filename_template = "{paths.data}/traceback-{pid}-{count}.log";
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	113 event = "debug_traceback/triggered";
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	114 };
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	115 }
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	116 ```
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	117
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	118 If the filename template matches the traceback path, both logs and traceback will
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	119 be combined into the same file. Of course separate files can be specified if preferred.
0b1b7d671448 mod_log_ringbuffer: Document how to integrate with mod_debug_traceback Matthew Wild <mwild1@gmail.com> parents: 4219 diff changeset	120
4205 481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	121 # Compatibility
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	122
481c4d75e77d mod_log_ringbuffer: New module to send logs to an in-memory ringbuffer Matthew Wild <mwild1@gmail.com> parents: diff changeset	123 0.11 and later.

Mercurial > prosody-modules

annotate mod_log_ringbuffer/README.markdown @ 5799:c75328aeaba3