serverless-sentry
Advanced tools
Serverless Sentry Plugin - Automatically send errors and exceptions to Sentry (https://sentry.io)
This Serverless plugin simplifies the integration of Sentry](https://sentry.io) with the popular Serverless Framework and AWS Lambda.
Currently, we support Lambda Runtimes for Node.js 12, 14, and 16 for AWS Lambda. Other platforms can be added by providing a respective integration library. Pull Requests are welcome!
The serverless-sentry-plugin and serverless-sentry-lib libraries are not affiliated with either Functional Software Inc., Sentry, Serverless or Amazon Web Services but developed independently and in my spare time.
Sentry integration splits into two components:
For a detailed overview of how to use the serverless-sentry-lib refer to its README.md.
Install the @sentry/node module as a production dependency (so it gets packaged together with your source code):
npm install --save @sentry/node
Install the serverless-sentry-lib as a production dependency as well:
npm install --save serverless-sentry-lib
Install this plugin as a development dependency (you don't want to package it with your release artifacts):
npm install --save-dev serverless-sentry
Check out the examples below on how to integrate it with your project
by updating serverless.yml as well as your Lambda handler code.
The Serverless Sentry Plugin allows configuration of the library through the serverless.yml
and will create release and deployment information for you (if wanted). This is the recommended way of using the serverless-sentry-lib library.
The plugin determines your environment during deployment and adds the
SENTRY_DSN environment variables to your Lambda function. All you need to
do is to load the plugin and set the dsn configuration option as follows:
service: my-serverless-project
provider:
# ...
plugins:
- serverless-sentry
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz # URL provided by Sentry
The actual reporting to Sentry happens in platform-specific libraries. Currently, only Node.js and Python are supported.
Each library provides a withSentry helper that acts as decorators around your original AWS Lambda handler code and is configured via this plugin or manually through environment variables.
For more details refer to the individual libraries' repositories:
Old, now unsupported libraries:
For maximum flexibility, this library is implemented as a wrapper around your original AWS Lambda handler code (your handler.js or similar function). The withSentry higher-order function adds error and exception handling and takes care of configuring the Sentry client automatically.
withSentry is pre-configured to reasonable defaults and doesn't need any configuration. It will automatically load and configure @sentry/node which needs to be installed as a peer dependency.
Original Lambda Handler Code:
exports.handler = async function (event, context) {
console.log("EVENT: \n" + JSON.stringify(event, null, 2));
return context.logStreamName;
};
New Lambda Handler Code Using withSentry For Sentry Reporting
const withSentry = require("serverless-sentry-lib"); // This helper library
exports.handler = withSentry(async function (event, context) {
console.log("EVENT: \n" + JSON.stringify(event, null, 2));
return context.logStreamName;
});
ES6 Module: Original Lambda Handler Code:
export async function handler(event, context) {
console.log("EVENT: \n" + JSON.stringify(event, null, 2));
return context.logStreamName;
}
ES6 Module: New Lambda Handler Code Using withSentry For Sentry Reporting
import withSentry from "serverless-sentry-lib"; // This helper library
export const handler = withSentry(async (event, context) => {
console.log("EVENT: \n" + JSON.stringify(event, null, 2));
return context.logStreamName;
});
Once your Lambda handler code is wrapped in withSentry, it will be extended with automatic error reporting. Whenever your Lambda handler sets an error response, the error is forwarded to Sentry with additional context information. For more details about the different configuration options available refer to the serverless-sentry-lib documentation.
Configure the Sentry plugin using the following options in your
serverless.yml:
dsn - Your Sentry project's DSN URL (required)enabled - Specifies whether this SDK should activate and send events to Sentry (defaults to true)environment - Explicitly set the Sentry environment (defaults to the
Serverless stage)In order for some features such as releases and deployments to work, you need to grant API access to this plugin by setting the following options:
organization - Organization nameproject - Project nameauthToken - API authentication token with project:write access👉 Important: You need to make sure you’re using Auth Tokens not API Keys, which are deprecated.
Releases are used by Sentry to provide you with additional context when determining the cause of an issue. The plugin can automatically create releases for you and tag all messages accordingly. To find out more about releases in Sentry, refer to the official documentation.
In order to enable release tagging, you need to set the release option in your serverless.yml:
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz
organization: my-sentry-organziation
project: my-sentry-project
authToken: my-sentry-api-key
release:
version: <RELEASE VERSION>
refs:
- repository: <REPOSITORY NAME>
commit: <COMMIT HASH>
previousCommit: <COMMIT HASH>
version - Set the release version used in Sentry. Use any of the below values:
git - Uses the current git commit hash or tag as release identifier.random - Generates a random release during deployment.true - First tries to determine the release via git and falls back to random if Git is not available.false - Disable release versioning.refs - If you have set up Sentry to collect commit data, you can use commit refs to associate your commits with your Sentry releases. Refer to the Sentry Documentation for details about how to use commit refs. If you set your version to git (or true), the refs options are populated automatically and don't need to be set.
👉 Tip {"refs":["Invalid repository names: xxxxx/yyyyyyy"]}: If your repository provider is not supported by Sentry (currently only GitHub or Gitlab with Sentry Integrations) you have the following options:
refs: false, this will not automatically population the refs but also dismisses your commit id as versionrefs: true and version: true to populate the version with the commit short idIf you don't specify any refs, you can also use the short notation for release and simply set it to the desired release version as follows:
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz
release: <RELEASE VERSION>
If you don't need or want the plugin to create releases and deployments, you can omit the authToken, organization and project options. Messages and exceptions sent by your Lambda functions will still be tagged with the release version and show up grouped in Sentry nonetheless.
👉 Pro Tip: The possibility to use a fixed string in combination with Serverless variables allows you to inject your release version through the command line, e.g. when running on your continuous integration machine.
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz
organization: my-sentry-organziation
project: my-sentry-project
authToken: my-sentry-api-key
release:
version: ${opt:sentryVersion}
refs:
- repository: ${opt:sentryRepository}
commit: ${opt:sentryCommit}
And then deploy your project using the command-line options from above:
sls deploy --sentryVersion 1.0.0 --sentryRepository foo/bar --sentryCommit 2da95dfb
👉 Tip when using Sentry with multiple projects: Releases in Sentry are specific to the organization and can span multiple projects. Take this in consideration when choosing a version name. If your version applies to the current project only, you should prefix it with your project name.
If no option for release is provided, releases and deployments are disabled.
Sourcemap files can be uploaded to Sentry to display source files in the stack traces rather than the compiled versions. This only uploads existing files being output, you'll need to configure your bundling tool separately. You'll also need to have releases configured, see above.
Default options:
custom:
sentry:
sourceMaps: true
Add custom prefix (required if your app is not at the filesystem root)
custom:
sentry:
sourceMaps:
urlPrefix: /var/task
In addition, you can configure the Sentry error reporting on a service as well as a per-function level. For more details about the individual configuration options see the serverless-sentry-lib documentation.
autoBreadcrumbs - Automatically create breadcrumbs (see Sentry Raven docs, defaults to true)filterLocal - Don't report errors from local environments (defaults to true)captureErrors - Capture Lambda errors (defaults to true)captureUnhandledRejections - Capture unhandled Promise rejections (defaults to true)captureUncaughtException - Capture unhandled exceptions (defaults to true)captureMemoryWarnings - Monitor memory usage (defaults to true)captureTimeoutWarnings - Monitor execution timeouts (defaults to true)# serverless.yml
service: my-serverless-project
provider:
# ...
plugins:
- serverless-sentry
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz # URL provided by Sentry
captureTimeoutWarnings: false # disable timeout warnings globally for all functions
functions:
FuncFoo:
handler: Foo.handler
description: Hello World
sentry:
captureErrors: false # Disable error capturing for this specific function only
captureTimeoutWarnings: true # Turn timeout warnings back on
FuncBar:
handler: Bar.handler
sentry: false # completely turn off Sentry reporting
In some cases, it might be desired to use a different Sentry configuration depending on the currently deployed stage. To make this work we can use a built-in Serverless variable resolutions trick:
# serverless.yml
plugins:
- serverless-sentry
custom:
config:
default:
sentryDsn: ""
prod:
sentryDsn: "https://xxxx:yyyy@sentry.io/zzzz" # URL provided by Sentry
sentry:
dsn: ${self:custom.config.${self:provider.stage}.sentryDsn, self:custom.config.default.sentryDsn}
captureTimeoutWarnings: false # disable timeout warnings globally for all functions
Double-check the DSN settings in your serverless.yml and compare it with what Sentry shows you in your project settings under "Client Keys (DSN)". You need a URL in the following format - see the Sentry Quick Start:
{PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}/{PATH}{PROJECT_ID}
Also, make sure to add the plugin to your plugins list in the serverless.yml:
plugins:
- serverless-sentry
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz # URL provided by Sentry
Make sure to set the authToken, organization as well as project options in your serverless.yml, and set release to a non-empty value as shown in the example below:
plugins:
- serverless-sentry
custom:
sentry:
dsn: https://xxxx:yyyy@sentry.io/zzzz # URL provided by Sentry
organization: my-sentry-organziation
project: my-sentry-project
authToken: my-sentry-api-key
release: git
Check out the filterLocal configuration setting. If you test Sentry locally and want to make sure your messages are sent, set this flag to false. Once done testing, don't forget to switch it back to true as otherwise, you'll spam your Sentry projects with meaningless errors of local code changes.
false or unset.enabled flag. Thanks to aaronbannin for the contribution.custom.sentry.captureUncaughtException configuration option. This already exists in serverless-sentry-lib but was never exposed in the plugin.SENTRY_DSN is not set but simply disable Sentry integration.sls deploy -f MyFunction). Thanks to dominik-meissner!serverless-sentry-plugin requires the use of serverless-sentry-lib v2.x.xraven to the Unified Node.js SDK @sentry/node.withSentry higher-order function. Passing the Sentry instance is now optional.sls invoke local. Thanks to sifrenette
for his contribution.serverless-sentry-lib v1.1.x.serverless-sentry-lib as well!sentry: false in
the serverless.yml.That you for supporting me and my projects.
FAQs
Serverless Sentry Plugin - Automatically send errors and exceptions to Sentry (https://sentry.io)
We found that serverless-sentry demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.