Mercurial > prosody-modules

annotate mod_sentry/README.md @ 5679:e274431bf4ce

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_status: Add IP allowlisting capabilities Based on mod_http_openmetrics
author Kim Alvefur <zash@zash.se>
date Wed, 25 Oct 2023 17:18:50 +0200
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.