|
1 | 1 | # Bugsnag 🐛 |
2 | | -[](http://swift.org) |
3 | | -[](http://vapor.codes) |
| 2 | +[](http://swift.org) |
| 3 | +[](http://vapor.codes) |
4 | 4 | [](https://circleci.com/gh/nodes-vapor/bugsnag) |
5 | 5 | [](https://codebeat.co/projects/github-com-nodes-vapor-bugsnag-master) |
6 | 6 | [](https://codecov.io/gh/nodes-vapor/bugsnag) |
7 | 7 | [](http://clayallsopp.github.io/readme-score?url=https://github.com/nodes-vapor/bugsnag) |
8 | 8 | [](https://raw.githubusercontent.com/nodes-vapor/bugsnag/master/LICENSE) |
9 | 9 |
|
10 | | - |
11 | 10 | Reporting errors to [Bugsnag](https://www.bugsnag.com/). |
12 | 11 |
|
13 | 12 | ## 📦 Installation |
14 | 13 |
|
15 | | -### Installing CStack |
16 | | - |
17 | | -Bugsnag uses [Stacked](https://github.com/nodes-vapor/stacked) (which depends on [CStack](https://github.com/nodes-vapor/cstack)) in order to provide unified stack traces across macOS and Linux. For this to work, there's some installation to be done on the machine running the project. See the Stacked repo for more information, but here's a short copy/pasta: |
18 | | - |
19 | | -#### macOS and Homebrew |
20 | | - |
21 | | -Currently the CStack library can be installed through the Vapor tap (by running `brew install cstack`). If that doesn't work for some reason or Vapor decides to remove the library from their tap, it can be installed through the Nodes tap by following these steps: |
22 | | - |
23 | | -First add the tap: |
24 | | - |
25 | | -``` |
26 | | -brew tap nodes-vapor/homebrew-tap |
27 | | -``` |
28 | | - |
29 | | -And next, install the library by running: |
30 | | - |
31 | | -``` |
32 | | -brew install cstack |
33 | | -``` |
34 | | - |
35 | | -#### Linux and APT |
36 | | - |
37 | | -To install CStack on Linux using APT, you first need to setup the Vapor APT repository. The guide for this can be found [here](https://github.com/vapor/apt). After that, CStack can be installed by doing: |
38 | | - |
39 | | -``` |
40 | | -apt-get update |
41 | | -``` |
42 | | - |
43 | | -And then: |
44 | | - |
45 | | -``` |
46 | | -apt-get install cstack |
47 | | -``` |
48 | | - |
49 | 14 | ### Integrating Bugsnag in your project |
50 | 15 |
|
51 | 16 | Update your `Package.swift` file. |
52 | 17 |
|
53 | 18 | ```swift |
54 | | -.Package(url: "https://github.com/nodes-vapor/bugsnag.git", majorVersion: 2) |
| 19 | +.package(url: "https://github.com/nodes-vapor/bugsnag.git", .upToNextMinor(from: "3.0.0")) |
55 | 20 | ``` |
56 | 21 |
|
57 | | -### Exporting symbols for the stracktraces |
58 | | - |
59 | | -Unfortunately, we're not able to specify the needed flags for running any project wanting stacktraces through SPM, since it uses a limited set of whitelisted flags. Because of that, you would need to manually add these flags when building your project: |
| 22 | +Update `Sources/App/configure.swift` |
60 | 23 |
|
61 | | -``` |
62 | | --Xlinker --export-dynamic |
63 | | -``` |
64 | | - |
65 | | - |
66 | | -## Getting started 🚀 |
67 | | - |
68 | | -Create a `bugsnag.json` configuration file with your Bugsnag credentials and configuration. |
69 | | - |
70 | | -```json |
71 | | -{ |
72 | | - "apiKey": "my-bugsnag-key", |
73 | | - "endpoint": "https://notify.bugsnag.com", |
74 | | - "notifyReleaseStages": [ |
75 | | - "staging", |
76 | | - "production" |
77 | | - ], |
78 | | - "filters": [ |
79 | | - "password", |
80 | | - "newPassword", |
81 | | - "repeat_password" |
82 | | - ], |
83 | | - "stackTraceSize": 100 |
| 24 | +```swift |
| 25 | +public func configure( |
| 26 | + _ config: inout Config, |
| 27 | + _ env: inout Environment, |
| 28 | + _ services: inout Services |
| 29 | +) throws { |
| 30 | + ... |
| 31 | + // Register provider |
| 32 | + let bugsnagProvider = BugsnagProvider(config: BugsnagConfig( |
| 33 | + apiKey: "<YOUR BUGSNAG API KEY>", |
| 34 | + releaseStage: environment.name, |
| 35 | + shouldReport: environment.name != "local" |
| 36 | + debug: false |
| 37 | + )) |
| 38 | + try services.register(bugsnagProvider) |
| 39 | + |
| 40 | + ... |
| 41 | + |
| 42 | + // Register middleware |
| 43 | + |
| 44 | + var middlewaresConfig = MiddlewareConfig() |
| 45 | + ... |
| 46 | + middlewaresConfig.use(BugsnagMiddleware.self) // Catch errors and report to bugsnag |
| 47 | + ... |
| 48 | + services.register(middlewaresConfig) |
| 49 | + |
| 50 | + ... |
84 | 51 | } |
85 | 52 | ``` |
86 | 53 |
|
87 | | -See the configuration section for an explanation of the different options. |
88 | | - |
89 | | -### Automatic reporting |
90 | | - |
91 | | -This package comes with a middleware that will automatically report any thrown errors to bugsnag. For best error data, please make sure that the errors being thrown conform to Vapor's `AbortError` type. |
| 54 | +### Reporting |
| 55 | +Bugsnag offers three different types of reports: info, warning and error. To make a report just instantiate a `ErrorReporter` and use the respective functions. |
92 | 56 |
|
93 | | -To setup the middleware, then first make sure to import the package (in e.g. `Config+Setup.swift`): |
| 57 | +##### Examples |
| 58 | +```swift |
| 59 | +let reporter = try req.make(ErrorReporter.self) // or `BugsnagReporter.self` |
94 | 60 |
|
95 | | -```Swift |
96 | | -import Bugsnag |
| 61 | +reporter.report(Abort(.upgradeRequired), severity: .info, on: req) |
| 62 | +reporter.report(Abort(.notFound), severity: .warning, on: req) |
| 63 | +reporter.report(Abort(.internalServerError), severity: .error, on: req) // you can omit the `severity` parameter since `.error` is the default |
97 | 64 | ``` |
98 | 65 |
|
99 | | -Next, add the middleware: |
100 | | - |
| 66 | +It's also possible to attach metadata to the report. |
101 | 67 | ```swift |
102 | | -addConfigurable(middleware: Bugsnag.Middleware.init, name: "bugsnag") |
| 68 | +reporter.report( |
| 69 | + Abort(.internalServerError), |
| 70 | + metadata: ["key": "value"], |
| 71 | + on: req |
| 72 | +) |
103 | 73 | ``` |
104 | 74 |
|
105 | | -Don't forget to add the middleware to your `droplet.json` config as well. |
106 | | - |
107 | | -### Manual reporting |
108 | | - |
109 | | -Sometimes it's convenient to report errors silently without letting the client know. For this, the Bugsnag package comes with functionality to manually report errors. |
110 | | - |
111 | | -First, you'll have to make sure to import the package as desribed above (in Automatic reporting), then you need to add the Bugsnag provider: |
| 75 | +Reporting an error returns a discardable future. Just map/flatMap the result if you would like to do more work after the report has been sent. |
112 | 76 |
|
113 | 77 | ```swift |
114 | | -try addProvider(Bugsnag.Provider.self) |
| 78 | +return reporter.error(yourError, on: req).flatMap { |
| 79 | + ... |
| 80 | +} |
115 | 81 | ``` |
116 | 82 |
|
117 | | -You're now able to get a reference to a `Reporter` through the `Droplet`. You can then use this `Reporter` to manually report errors: |
| 83 | +#### Users |
| 84 | +Conforming your `Authenticatable` model to `BugsnagReportableUser` allows you to easily pair the data to a report. The protocol requires your model to have an `id` field that is `CustomStringConvertible`. |
118 | 85 |
|
119 | 86 | ```swift |
120 | | -myDroplet.bugsnag?.report(error: Abort.badRequest, request: myRequest) |
121 | | -``` |
122 | | - |
123 | | -Consider injecting the reporter into the controllers that might need it instead of passing around the `Droplet`. There's also an option to pass in a completion block if you want to get notified when the submission has completed. |
| 87 | +extension YourUser: BugsnagReportableUser {} |
124 | 88 |
|
125 | | -### Metadata |
| 89 | +try reporter.error(userType: YourUser.self, Abort(.notFound), on: req) |
| 90 | +``` |
126 | 91 |
|
127 | | -Remember that when using Vapor's `AbortError` type, you can pass in some metadata on your error which will also be reported to Bugsnag. This is convenient if you want to include information that can help you debug a specific error. |
| 92 | +#### Breadcrumbs |
| 93 | +Breadcrumbs enable you to attach custom events to your reports. Leave a breadcrumb using the convenience function on `Request`. |
128 | 94 |
|
129 | 95 | ```swift |
130 | | -Abort.init(.internalServerError, metadata: ["userId": 1337], reason: "User failed to login.") |
| 96 | +req.breadcrumb( |
| 97 | + name: "Something happened!", |
| 98 | + type: .manual, |
| 99 | + metadata: ["foo": "bar"] |
| 100 | +) |
131 | 101 | ``` |
132 | 102 |
|
133 | | - |
134 | | - |
135 | | -## Configurations 🔧 |
136 | | - |
137 | | -| Key | Example value | Required | Description | |
138 | | -| ---------------------- | -------------------------------- | -------- | ---------------------------------------- | |
139 | | -| `apiKey` | `23487897ADIUHASIUDH3247` | Yes | Bugsnag API key for reporting errors. | |
140 | | -| `endpoint` | ` https://notify.bugsnag.com` | Yes | The endpoint to hit when reporting errors. | |
141 | | -| ` notifyReleaseStages` | `["staging", "production"]` | No | The environments in which errors should be reported. Environments not in the list will not report errors. | |
142 | | -| ` filters` | `["password", "repeatPassword"]` | No | Keys to filter out from a requests url-, query-, form and JSON parameters. | |
143 | | -| ` stackTraceSize` | `100` | No | The default size of the stacktrace to report together with the error. This value can be overruled when reporting errors manually. | |
144 | | - |
| 103 | +The breadcrumb types are provided by Bugsnag: |
| 104 | +```swift |
| 105 | +enum BreadcrumbType { |
| 106 | + case navigation |
| 107 | + case request |
| 108 | + case process |
| 109 | + case log |
| 110 | + case user |
| 111 | + case state |
| 112 | + case error |
| 113 | + case manual |
| 114 | +} |
| 115 | +``` |
145 | 116 |
|
146 | 117 | ## 🏆 Credits |
147 | 118 |
|
148 | 119 | This package is developed and maintained by the Vapor team at [Nodes](https://www.nodesagency.com). |
149 | | -The package owner for this project is [Steffen](https://github.com/steffendsommer). |
150 | | - |
| 120 | +The package owner for this project is [Siemen](https://github.com/siemensikkema). |
151 | 121 |
|
152 | 122 | ## 📄 License |
153 | 123 |
|
154 | | -This package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT) |
| 124 | +This package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT). |
0 commit comments