Swiftpack.co - Package - nodes-vapor/bugsnag

Bugsnag 🐛

Swift Version Vapor Version Circle CI codebeat badge codecov Readme Score GitHub license

Reporting errors to Bugsnag.

📦 Installation

Integrating Bugsnag in your project

Update your Package.swift file.

.package(url: "https://github.com/nodes-vapor/bugsnag.git", from: "3.0.0")

Update Sources/App/configure.swift

public func configure(
    _ config: inout Config,
    _ environment: inout Environment,
    _ services: inout Services
) throws {
    ...
    // Register provider
    let bugsnagProvider = BugsnagProvider(config: BugsnagConfig(
        apiKey: "<YOUR BUGSNAG API KEY>",
        releaseStage: environment.name,
        shouldReport: environment.name != "local"
        debug: false
    ))
    try services.register(bugsnagProvider)

    ...

    // Register middleware

    var middlewaresConfig = MiddlewareConfig()
    ...
    middlewaresConfig.use(BugsnagMiddleware.self) // Catch errors and report to bugsnag
    ...
    services.register(middlewaresConfig)

    ...
}

Reporting

Bugsnag offers three different types of reports: info, warning and error. To make a report just instantiate an ErrorReporter and use the respective functions.

Examples
let reporter = try req.make(ErrorReporter.self) // or `BugsnagReporter.self`

reporter.report(Abort(.upgradeRequired), severity: .info, on: req)
reporter.report(Abort(.notFound), severity: .warning, on: req)
reporter.report(Abort(.internalServerError), severity: .error, on: req) // you can omit the `severity` parameter since `.error` is the default

It's also possible to attach metadata to the report.

reporter.report(
    Abort(.internalServerError),
    metadata: ["key": "value"],
    on: req
)

By conforming to the ReportableError protocol you can have full control over how (and if) the BugsnagMiddleware reports your errors. It has the following properties:

| Name | Type | Function | Default | |---|---|---|---| | shouldReport | Bool | Opt out of error reporting by returning false | true | | severity | Severity | Indicate error severity (.info|.warning|.error) | .error | | userId | CustomStringConvertible? | An optional user id associated with the error | nil | | metadata | [String: CustomDebugStringConvertible] | Additional metadata to include in the report | [:] |

Users

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.

extension YourUser: BugsnagReportableUser {}

try reporter.error(userType: YourUser.self, Abort(.notFound), on: req)

Breadcrumbs

Breadcrumbs enable you to attach custom events to your reports. Leave a breadcrumb using the convenience function on Request.

req.breadcrumb(
    name: "Something happened!",
    type: .manual,
    metadata: ["foo": "bar"]
)

The breadcrumb types are provided by Bugsnag:

enum BreadcrumbType {
    case navigation
    case request
    case process
    case log
    case user
    case state
    case error
    case manual
}

Filter out fields from reports

Usually you will receive information such as headers, query params or post body fields in the reports from Bugsnag. To ensure that you do not track sensitive information, you can configure Bugsnag with a list of fields that should be filtered out:

BugsnagConfig(
    apiKey: "apiKey",
    releaseStage: "test",
    keyFilters: ["password", "email", "authorization", "lastname"]
)

In this case Bugsnag Reports won't contain header fields, query params or post body json fields with the keys/names password, email, authorization, lastname.

⚠️ Note: in JSON bodies, this only works for the first level of fields and not for nested children.

🏆 Credits

This package is developed and maintained by the Vapor team at Nodes.

📄 License

This package is open-sourced software licensed under the MIT license.

Github

link
Stars: 36

Dependencies

Used By

Total: 0

Releases

Version 3.1.0 - 2020-02-26 15:54:55

Changed

  • The keyFilters feature does not only filter out fields from the request body, but also from query params and header fields

Added

  • Tests for keyFilters
  • Brief documentation about keyFilters in the README.md

Version 3.0.0 RC 4 - 2019-07-31 14:40:27

Added

  • ReportableError protocol for more control on how the middleware treats your errors
  • An optional version parameter to BugsnagConfig which is sent to Bugsnag and can be used to group errors by releases. One way to use this would be to use the git-hash.

Version 3.0.0 RC 3 - 2019-06-01 12:40:41

Fixed

  • Now reports breadcrumbs metadata to Bugsnag in the correct way

Version 3.0.0 RC 2 - 2019-05-16 08:02:42

Added

  • Included more meta information in case the underlying error is an NSError (domain, user info, error code)

Removed

  • Debug description of the request was removed because it could contain security and privacy sensitive data

Version 3.0.0 RC 1 - 2019-03-06 15:05:51

Changed

  • force explicit handling of return type for BugsnagReporter.report(...)
  • make report extensions on ErrorReporter protocol public
  • use req.client instead of HTTPClient.connect for improved stability

Version 3.0.0 Beta 3 - 2019-02-14 11:55:42

Added

  • Support for filtering out keys from the request (e.g. to remove sensitive information such as passwords)

Changed

  • Reporting now takes in a Container instead of a Request. This allows for reporting in cases where you don't have a request.

Version 3.0.0 Beta 2 - 2019-02-08 14:31:00

Changed

  • the 'Future's you get when reporting to Bugsnag now no longer be ignored unless you explicitly use _ = reporter.report(...)

Fixed

  • BugsnagMiddleware is registered by the provider.

Version 3.0.0 Beta 1 - 2019-02-07 15:09:38

Rewritten for Vapor 3

Version 0.4.2 - 2018-10-19 08:52:36

Fixed:

  • Reporter constructor is now public

Version 1.1.4 - 2018-03-28 11:48:12

Fixed

  • A bug where Bugsnag wouldn't use the correct environment from Vapor.

Version 2.0.2 - 2018-03-27 13:55:42

Fixed

  • A bug where Bugsnag wouldn't use the correct environment from Vapor when using the ReporterFactory (e.g. in a command)

Version 2.0.1 - 2018-01-15 12:24:59

Fixed

  • A bug where Bugsnag wouldn't use the correct environment from Vapor.

Version 2.0.0 - 2017-08-11 12:19:12

New:

  • Stack traceable errors
  • Host is now reported to Bugsnag as well
  • Reporting manually does not throw anymore

Version 1.1.3 - 2017-06-28 10:56:18

Fixed:

  • order in which config is added

Version 1.1.2 - 2017-06-28 10:41:36

New:

  • addConfigurable is done automatically in provider
  • Abort.report() and Abort.doNotReport()

Version 1.1.1 - 2017-05-23 09:21:41

  • Now possible to add the middleware using Vapor 2's new addConfigurable setup.

Version 1.1.0 - 2017-05-18 08:54:06

  • Vapor 2 released 🎉

Version 1.1.0 Beta 2 - 2017-05-17 17:05:05

  • Stacked not compiling - reverted to an older version

Version 1.1.0 Beta 1 - 2017-05-17 13:22:20

  • Made it compile with newest version of Vapor 2
  • Rewrote how configuration and dependencies are being handled internally

Version 1.0.0 Beta 4 - 2017-05-02 14:46:24

  • Fixed Vapor 2 related errors

Version 1.0.0 Beta 3 - 2017-04-12 05:56:55

  • Reports are now only being sent if the current environment is specified in the notifyReleaseStages config.

Version 0.4.1 - 2017-04-12 05:56:19

  • Reports are now only being sent if the current environment is specified in the notifyReleaseStages config.

Version 1.0.0 Beta 2 - 2017-04-11 17:39:10

  • Now possible to set severity on reports.
  • You can now filter out keys you don't want reported to Bugsnag.

Version 0.4.0 - 2017-04-11 13:31:20

  • Now possible to set severity on reports.
  • You can now filter out keys you don't want reported to Bugsnag.

Version 1.0.0 Beta I - 2017-04-10 09:27:12

New:

  • Updated to Vapor 2.0 Beta

Version 0.3.2 - 2017-04-05 14:33:46

  • Bugsnag now reports url-, query-, form- and json parameters to Bugsnag separately.

Version 0.3.1 - 2017-04-03 08:06:22

  • Make request optional when reporting (makes more sense for manual reporting)
  • Fix config loading bug

Version 0.2.0 - 2017-03-28 10:16:23

Using Stacked for cross-platform stack traces.

Version 0.1.2 - 2017-01-06 18:53:02

Added

  • Support for explicitly specifying if an error should be reported or not using metadata ("report").

Changed

  • Updated to support new AbortError protocol (#7). Errors not conforming to AbortError will now also be thrown.

Version 0.1.1 - 2017-01-04 16:49:29

  • Fix Linux crash due to call to callStackSymbols