Reporting errors to Bugsnag.
Bugsnag uses Stacked (which depends on 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:
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:
First add the tap:
brew tap nodes-vapor/homebrew-tap
And next, install the library by running:
brew install cstack
To install CStack on Linux using APT, you first need to setup the Vapor APT repository. The guide for this can be found here. After that, CStack can be installed by doing:
apt-get update
And then:
apt-get install cstack
Update your Package.swift
file.
.Package(url: "https://github.com/nodes-vapor/bugsnag.git", majorVersion: 2)
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:
-Xlinker --export-dynamic
Create a bugsnag.json
configuration file with your Bugsnag credentials and configuration.
{
"apiKey": "my-bugsnag-key",
"endpoint": "https://notify.bugsnag.com",
"notifyReleaseStages": [
"staging",
"production"
],
"filters": [
"password",
"newPassword",
"repeat_password"
],
"stackTraceSize": 100
}
See the configuration section for an explanation of the different options.
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.
To setup the middleware, then first make sure to import the package (in e.g. Config+Setup.swift
):
import Bugsnag
Next, add the middleware:
addConfigurable(middleware: Bugsnag.Middleware.init, name: "bugsnag")
Don't forget to add the middleware to your droplet.json
config as well.
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.
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:
try addProvider(Bugsnag.Provider.self)
You're now able to get a reference to a Reporter
through the Droplet
. You can then use this Reporter
to manually report errors:
myDroplet.bugsnag?.report(error: Abort.badRequest, request: myRequest)
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.
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.
Abort.init(.internalServerError, metadata: ["userId": 1337], reason: "User failed to login.")
Key | Example value | Required | Description |
---|---|---|---|
apiKey |
23487897ADIUHASIUDH3247 |
Yes | Bugsnag API key for reporting errors. |
endpoint |
https://notify.bugsnag.com |
Yes | The endpoint to hit when reporting errors. |
notifyReleaseStages |
["staging", "production"] |
No | The environments in which errors should be reported. Environments not in the list will not report errors. |
filters |
["password", "repeatPassword"] |
No | Keys to filter out from a requests url-, query-, form and JSON parameters. |
stackTraceSize |
100 |
No | The default size of the stacktrace to report together with the error. This value can be overruled when reporting errors manually. |
This package is developed and maintained by the Vapor team at Nodes. The package owner for this project is Steffen.
This package is open-sourced software licensed under the MIT license