Raygun AWS Lambda + Node

Raygun.com package for AWS Lambda + Node, written in TypeScript.

This package improves the experience when using Raygun with AWS Lambda using JavaScript.

Provides two main advantages compared to using Raygun directly:

1. Captures any uncaught error in the AWS Lambda function and reports it to Raygun automatically.
2. Scopes Breadcrumbs to the current function session.

Getting Started

Install the module with: npm install @raygun.io/aws-lambda

Set up the Raygun client as described in the Raygun package.

Import the awsHandler method:

const { awsHandler } = require("@raygun.io/aws-lambda");

Adding Raygun to a AWS Lambda function

To add Raygun to an existing AWS Lambda function, wrap the existing handler implementation with the awsHandler function.

Before:

exports.handler = async function (event, context) {
    // your code
}

After:

// 1. Configure your Raygun client outside the AWS Lambda function
const client = new Raygun.client().init( ... );

// 2. Wrap the existing function with awsHandler
// 3. Pass the client as the first parameter
exports.handler = awsHandler({ client }, async function (event, context) {
    // your code
});

Using AWS Lambda functions with callbacks

Raygun AWS Lambda handler also supports functions with three parameters and callbacks.

// Wrap the existing function with callback
exports.handler = awsHandler({ client }, function (event, context, callback) {
    // your code
});

Sending errors to Raygun from an AWS Lambda function

Any errors thrown in code will be automatically captured by the awsHandler.

exports.handler = awsHandler({ client }, async function (event, context) {
    // Captured by awsHandler and reported to Raygun
    throw "error";
});

Errors are also automatically reported when using the callback version.

exports.handler = awsHandler({ client }, function (event, context, callback) {
    // Captured by awsHandler and reported to Raygun
    callback("error", null);
});

As well, you can keep using the send() method.

exports.handler = awsHandler({ client }, async function (event, context) {
    await client.send("error");
});

Important: The awsHandler will rethrow the error back to AWS once it has been captured.

Adding breadcrumbs to Raygun error reports

Breadcumbs are included automatically to all error reports sent from the awsHandler or when using the send() method.

Call to client.addBreadcrumb() to add breadcrumbs.

exports.handler = awsHandler({ client }, async function (event, context) {
    // Add a breadcrumb
    client.addBreadcrumb("breadcrumb");
    
    // Captured error includes the above breadcrumb
    throw "error";
});

AWS Lambda function context in Custom Data

The awsHandler adds the full function call context to the error report's "Custom Data" and the automatic "Running AWS Function" breadcrumb. The example below shows common metadata fields, not an exhaustive list. Serializable identity, clientContext, and application-added fields are also included when present. Context changes made by your handler are reflected in the report.

This payload can be found in the "Custom" tab in the Raygun Crash Reporting error report page.

context: {
  callbackWaitsForEmptyEventLoop: true,
  functionVersion: "$LATEST",
  functionName: "xyz",
  memoryLimitInMB: "128",
  logGroupName: "/aws/lambda/xyz",
  logStreamName: "2024/05/31/[$LATEST]xyz",
  invokedFunctionArn: "arn:aws:lambda:xyz",
  awsRequestId: "xyz"
}

Protecting sensitive data

The wrapper does not automatically capture the event, but it does capture the full context. Review context fields such as identity, clientContext, and application-added data for credentials or personal information. Context also contains infrastructure identifiers, including the function ARN and log names. Avoid adding sensitive data to custom data, breadcrumbs, or error messages.

The Raygun client's filters option applies only to request headers, query parameters, and parsed request bodies. It does not redact Lambda context, custom data, breadcrumbs, or error messages. Use the client's onBeforeSend hook to remove or redact these sections before transport. For example, to omit all custom data and breadcrumbs:

client.onBeforeSend((payload) => {
    delete payload.details.userCustomData;
    delete payload.details.breadcrumbs;
    return payload;
});

See the Raygun client's sensitive-data guidance for request filtering and logging precautions.

Release History

View the changelog here

License

Copyright (c) 2024 Raygun Limited

Licensed under the MIT license.