Mercurial > prosody-modules

annotate mod_sentry/README.md @ 4290:2c73544e33ea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_sentry: Automatically attach exceptions for errors used in log parameters
author Matthew Wild <mwild1@gmail.com>
date Wed, 09 Dec 2020 16:30:21 +0000
parents 2ae71126e379
children ae8191d9d533
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'
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ---
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 # Introduction
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 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
10
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 # Configuration
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 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
14 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
15
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 `dsn`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 : **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
18
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 `insecure`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 : 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
21
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 `server_name`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 : 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
24
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 `tags`
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 : 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
27 events from this module.
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 `extra`
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 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
31 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 Example configuration:
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 sentry = {
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 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
38 tags = {
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 environment = "prod";
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 };
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 }
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 ## Log forwarding
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 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
47 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
48 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
49
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 log = {
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 info = "*syslog";
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 { levels = "warn", to = "sentry" };
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 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 # Developers
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 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
60 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
61
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 ## API
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 Usage example:
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 ```
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 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
68 logger = module.name;
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 sentry:event("warning")
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 :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
73 :send();
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
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76 ### Events
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 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
79 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
80 calls together for convenience.
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 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
83 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
84
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 #### set(key, value)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 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
88
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89 #### tag(name, 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 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
92
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
93 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
94
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95 #### extra(name, 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 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
98 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
99
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
100 #### message(text)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
101
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
102 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
103
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
104 #### set_request(request)
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 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
107
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
108 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
109 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
110
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
111 #### add_exception(e)
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
112
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
113 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
114 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
115
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
116 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
117 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
118
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
119 #### 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
120
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
121 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
122 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
123 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
124
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
125 #### 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
126
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
127 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
128
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
129 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
130 of the request.
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
131
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
132 #### send()
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
133
2ae71126e379 mod_sentry: New module to forward errors to a Sentry server
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
134 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
135 to the response from the server.