prosody-modules: mod_log_ringbuffer/README.markdown annotate

annotate mod_log_ringbuffer/README.markdown @ 5442:7480dde4cd2e

mod_auth_oauth_external: Stub not implemented auth module methods Not providing some of these may trigger errors on use, which is something that would be nice to fix on the Prosody side, one day.

author	Kim Alvefur <zash@zash.se>
date	Wed, 10 May 2023 19:11:25 +0200
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 @ 5442:7480dde4cd2e