annotate mod_log_json/README.markdown @ 5271:3a1df3adad0c

mod_http_oauth2: Allow user to decide which requested scopes to grant These should at the very least be shown to the user, so they can decide whether to grant them. Considered whether to filter the requested scopes down to actually understood scopes that would be granted, but decided that this was a bit complex for a first step, since role role selection and other kinds of scopes are mixed into the same field here.
author Kim Alvefur <zash@zash.se>
date Thu, 23 Mar 2023 16:28:08 +0100
parents 4356088ad675
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3735
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 summary: JSON Log Sink
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 ---
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 Conifiguration
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 ==============
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7
3745
e43a82ddde12 mod_log_json/README: Add a sentence about the first example
Kim Alvefur <zash@zash.se>
parents: 3736
diff changeset
8 Here we log to `/var/log/prosody/prosody.json`:
e43a82ddde12 mod_log_json/README: Add a sentence about the first example
Kim Alvefur <zash@zash.se>
parents: 3736
diff changeset
9
3735
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 ``` {.lua}
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 log = {
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 -- your other log sinks
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 info = "/var/log/prosody/prosody.log"
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 -- add this:
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 { to = "json", filename = "/var/log/prosody/prosody.json" };
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 }
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 ```
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
3746
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
19 ## UDP
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
20
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
21 Alternatively, it can send logs via UDP:
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
22
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
23 ```lua
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
24 log = {
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
25 { to = "json", udp_host = "10.1.2.3", udp_port = "9999" };
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
26 }
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
27 ```
bc865568ff02 mod_log_json: Add UDP support
Kim Alvefur <zash@zash.se>
parents: 3745
diff changeset
28
3735
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29 Format
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 ======
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 JSON log files consist of a series of `\n`-separated JSON objects,
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 suitable for mangling with tools like
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 [`jq`](https://stedolan.github.io/jq/).
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
3736
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
36 Example (with whitespace and indentation for readability):
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
37
3735
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 ``` {.json}
3736
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
39 {
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
40 "args" : [],
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
41 "datetime" : "2019-11-03T13:38:28Z",
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
42 "level" : "info",
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
43 "message" : "Client connected",
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
44 "source" : "c2s55f267f5b9d0"
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
45 }
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
46 {
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
47 "args" : [
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
48 "user@example.net"
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
49 ],
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
50 "datetime" : "2019-11-03T13:38:28Z",
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
51 "level" : "debug",
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
52 "message" : "load_roster: asked for: %s",
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
53 "source" : "rostermanager"
3784bbcbb8ff mod_log_json: Prettify JSON for readability
Kim Alvefur <zash@zash.se>
parents: 3735
diff changeset
54 }
3735
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 ```
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57 `datetime`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 : [XEP-0082]-formatted timestamp.
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 `source`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 : Log source, usually a module or a connected session.
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63 `level`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 : `debug`, `info`, `warn` or `error`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66 `message`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 : The log message in `printf` format. Combine with `args` to get the
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 final message.
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 `args`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 : Array of extra arguments, corresponding to `printf`-style `%s`
06b640473cda mod_log_json: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 formatting in the `message`.
4462
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
73
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
74 Formatted message
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
75 -----------------
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
76
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
77 If desired, at the obvious expense of performance, the formatted version of
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
78 the string can be included in the JSON object by specifying the `formatted_as`
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
79 key in the logger config:
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
80
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
81 ``` {.lua}
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
82 log = {
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
83 -- ... other sinks ...
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
84 { to = "json", formatted_as = "msg_formatted", filename = "/var/log/prosody/prosody.json" };
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
85 }
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
86
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
87 ```
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
88
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
89 This will expose the formatted message in the JSON as separate `msg_formatted`
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
90 key. It is possible to override existing keys using this (for example, the
4356088ad675 mod_log_json: allow logging of formatted message
Jonas Schäfer <jonas@wielicki.name>
parents: 3746
diff changeset
91 `message` key), but not advisible.