README.md

Bugsnag 🐛

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: "4.0.0")

Update configure.swift

public func configure(_ app: Application) throws {
    // Configure Bugsnag.
    app.bugsnag.configuration = .init(
        apiKey: "<YOUR BUGSNAG API KEY>",
        releaseStage: app.environment.name,
        shouldReport: app.environment.name != "local"
    )

    // Add Bugsnag middleware.
    app.middleware.use(BugsnagMiddleware())
}

Reporting

BugsnagMiddleware will automatically report errors thrown by your route handlers. You can report errors manually from Application or Request.

// Reporting from Application.
app.bugsnag.report(Abort(.internalServerError))

// Reporting from Request.
app.get("test") { req in
    req.bugsnag.report(Abort(.upgradeRequired))
    return HTTPStatus.ok
}

By conforming to the BugsnagError protocol you can have full control over how your errors are reported. 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
metadata	[String: CustomDebugStringConvertible]	Additional metadata to include in the report	[:]

Users

Conforming your Authenticatable model to BugsnagUser allows you to easily pair the data to a report.

extension TestUser: BugsnagUser {
    var bugsnagID: CustomStringConvertible? { 
        self.id
    }
}

Configure all user models you would like Bugsnag to report.

// Add to configure.swift.
app.bugsnag.users.add(TestUser.self)

Bugsnag will automatically check Vapor's authentication API for the configured user types and report the user's identifier if they are logged in.

Breadcrumbs

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

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

The breadcrumb types are provided by Bugsnag:

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

Key Filters

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:

app.bugsnag.configuration = .init(
    apiKey: "foo",
    releaseStage: "debug",
    keyFilters: ["email", "password"]
)

In this case Bugsnag Reports will hide header fields, query params or post body json fields with the keys/names email and password.

⚠️ Note: If key filters are defined and Bugsnag does not know how to parse the request body, the entire body will be hidden.

🏆 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.