Mercurial > prosody-modules

comparison mod_sentry/README.md @ 4283:2ae71126e379

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