prosody-modules: mod_sentry/README.md annotate

annotate mod_sentry/README.md @ 5298:12f7d8b901e0

mod_audit: Support for adding location (GeoIP) to audit events This can be more privacy-friendly than logging full IP addresses, and also more informative to a user - IP addresses don't mean much to the average person, however if they see activity from outside their expected country, they can immediately identify suspicious activity. As with IPs, this field is configurable for deployments that would like to disable it. Location is also not logged when the geoip library is not available.

author	Matthew Wild <mwild1@gmail.com>
date	Sat, 01 Apr 2023 13:11:53 +0100
parents	ae8191d9d533
children

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.

Mercurial > prosody-modules

annotate mod_sentry/README.md @ 5298:12f7d8b901e0