Mercurial > prosody-modules

annotate mod_sentry/README.md @ 5237:3354f943c1fa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Require URL to client informational page in registration Since it's used without fallback in the template, seems someone expected this to always be there, and we might as well.
author Kim Alvefur <zash@zash.se>
date Sat, 11 Mar 2023 21:13:00 +0100
parents ae8191d9d533
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4283
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Send errors to a Sentry server'
4294
ae8191d9d533 mod_sentry: Include sentry.lib in luarock
Kim Alvefur <zash@zash.se>
parents: 4283
diff changeset
5 rockspec:
ae8191d9d533 mod_sentry: Include sentry.lib in luarock
Kim Alvefur <zash@zash.se>
parents: 4283
diff changeset
6 build:
ae8191d9d533 mod_sentry: Include sentry.lib in luarock
Kim Alvefur <zash@zash.se>
parents: 4283
diff changeset
7 modules:
ae8191d9d533 mod_sentry: Include sentry.lib in luarock
Kim Alvefur <zash@zash.se>
parents: 4283
diff changeset
8 mod_sentry.sentry: sentry.lib.lua
4283
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 ---
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 # Introduction
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 This module forwards select events to a [Sentry](https://sentry.io/) server.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 # Configuration
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 There is a single configuration option, `sentry`, which should be a table
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 containing the following parameters (optional unless otherwise stated):
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 `dsn`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 : **Required.** The DSN of the project in Sentry.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 `insecure`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 : Whether to allow untrusted HTTPS certificates.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 `server_name`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 : The name of the current server (defaults to the system hostname).
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 `tags`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 : An optional table of tags that will be used as the default for all
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 events from this module.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 `extra`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 : An optional table of custom extra data to attach to all events from
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 this module.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 Example configuration:
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 sentry = {
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 dsn = "https://37iNFnR4tferFhoTPNe8X0@example.com/11";
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 tags = {
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 environment = "prod";
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 };
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 }
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 ## Log forwarding
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 You can configure log messages to be automatically forwarded to Sentry.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 This example will send all "warn" and "error" messages to Sentry, while
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 sending all "info" and higher messages to syslog:
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 log = {
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 info = "*syslog";
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 { levels = "warn", to = "sentry" };
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 }
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 # Developers
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 In addition to the automatic log forwarder, you can integrate Sentry
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 forwarding directly into modules using the API.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 ## API
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 Usage example:
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 local sentry = module:depends("sentry").new({
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 logger = module.name;
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 });
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 sentry:event("warning")
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76 :message("This is a sample warning")
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 :send();
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 ### Events
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82 Event objects have a number of methods you can call to add data to them.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 All methods return the event itself, which means you can chain multiple
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84 calls together for convenience.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 After attaching all the data you want to include in the event, simply
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 call `event:send()` to submit it to the server.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89 #### set(key, value)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
91 Directly set a property of the event to the given value.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
93 #### tag(name, value)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
94
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95 Set the specified tag to the given value.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
96
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
97 May also be called with a table of key/value pairs.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
98
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
99 #### extra(name, value)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
100
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
101 Sets the specified 'extra' data. May also be called
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
102 with a table of key/value pairs.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
103
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
104 #### message(text)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
105
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
106 Sets the message text associated with the event.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
107
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
108 #### set_request(request)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
109
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
110 Sets the HTTP request associated with the event.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
111
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
112 This is used to indicate what incoming HTTP request
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
113 was being processed at the time of the event.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
114
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
115 #### add_exception(e)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
116
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
117 Accepts an error object (from util.error or any arbitrary value)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
118 and attempts to map it to a Sentry exception.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
119
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
120 May be called multiple times on the same event, to represent
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
121 nested exceptions (the outermost exception should be added first).
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
122
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
123 #### add_breadcrumb(timestamp, type, category, message, data)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
124
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
125 Add a breadcrumb to the event. A breadcrumb represents any useful
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
126 piece of information that led up to the event. See Sentry documentation
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
127 for allowable types and categories.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
128
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
129 #### add_http_request_breadcrumb(request, message)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
130
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
131 Helper to add a breadcrumb representing a HTTP request that was made.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
132
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
133 The `message` parameter is an optional human-readable text description
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
134 of the request.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
135
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
136 #### send()
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
137
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
138 Sends the event to the Sentry server. Returns a promise that resolves
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
139 to the response from the server.