Get started with Lambda

edit

Getting Elastic APM set up for your lambda functions is easy, and there are various ways you can tweak it to fit your needs. Follow the guide below to get started, and for more advanced topics, check out the API Reference.

Installation

edit

Add the elastic-apm-node module as a dependency to your application:

npm install elastic-apm-node --save

Initialization

edit

It’s important that the agent is started before you require any other modules in your Node.js application - i.e. before http, etc.

Here’s a simple lambda example with the Elastic APM agent installed:

// Add this to the VERY top of the first file loaded in your app
var apm = require('elastic-apm-node').start({
  // Override service name from package.json
  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
  serviceName: '',

  // Use if APM Server requires a token
  secretToken: '',

  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: '',
})

exports.handler = apm.lambda(function handler (payload, context, callback) {
  callback(null, `Hello, ${payload.name}!`)
})

The agent will now monitor the performance of your lambda function.

Full documentation

edit

Performance monitoring

edit

Elastic APM automatically measures the performance of everything within your lambda function executions. It records traces for database queries, external HTTP requests, and other slow operations that happen during execution.

By default, the agent will trace the most common modules. To trace other events, you can use custom traces. For information about custom traces, see the Custom Spans section.

Error logging

edit

By default, the Node.js agent will watch for uncaught exceptions and send them to Elastic APM automatically. But in most cases, errors are not thrown but returned via a callback, caught by a promise, or simply manually created. Those errors will not automatically be sent to Elastic APM. To manually send an error to Elastic APM, simply call apm.captureError() with the error:

var err = new Error('Ups, something broke!')

apm.captureError(err)

For advanced logging of errors, including adding extra metadata to the error, see the API documentation.

Filter sensitive information

edit

By default, the Node.js agent will filter common sensitive information before sending errors and metrics to the Elastic APM server.

It’s possible for you to tweak these defaults or remove any information you don’t want to send to Elastic APM:

  • By default, the Node.js agent will not log the body of HTTP requests. To enable this, use the logBody config option
  • By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. To disable this, use the filterHttpHeaders config option
  • To apply custom filters, use the apm.addFilter() function

Add your own data

edit

The Node.js agent will keep track of the active lambda function execution and will link it to errors and recorded transaction metrics when they are sent to the Elastic APM server. This allows you to see details about which execution resulted in a particular error or which lambda functions are slow.

But in many cases, information about the lambda execution itself isn’t enough. To add even more metadata to errors and transactions, use one of the two functions below:

  • apm.setUserContext() - Call this to enrich collected performance data and errors with information about the user/client
  • apm.setCustomContext() - Call this to enrich collected performance data and errors with any information that you think will help you debug performance issues and errors (this data is only stored, but not indexed in Elasticsearch)
  • apm.setTag() - Call this to enrich collected performance data and errors with simple key/value strings that you think will help you debug performance issues and errors (tags are indexed in Elasticsearch)

Troubleshooting

edit

If you can’t get the Node.js agent to work as expected, please follow the Troubleshooting Guide.