Monitoring Node.js Azure Functions

edit

The Node.js APM Agent can trace function invocations in an Azure Functions app.

Prerequisites

edit

You need an APM Server to send APM data to. Follow the APM Quick start if you have not set one up yet. You will need your APM server URL and an APM server secret token (or API key) for configuring the APM agent below.

You will also need an Azure Function app to monitor. If you do not have an existing one, you can follow this Azure guide to create one.

If you use func init --javascript ... as suggested in this Azure guide, then it is recommended that you uninstall the azure-functions-core-tools dependency by running npm uninstall azure-functions-core-tools and install it separately. Having azure-functions-core-tools as a "devDependency" in your package.json will result in unreasonably large deployments that will be very slow to publish and will run your Azure Function app VM out of disk space.

You can also take a look at and use this Azure Functions example app with Elastic APM already integrated.

Step 1: Add the APM agent dependency

edit

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

npm install elastic-apm-node --save  # or 'yarn add elastic-apm-node'

Step 2: Start the APM agent

edit

For the APM agent to instrument Azure Functions, it needs to be started when the Azure host starts its Node.js worker processes. The best way to do so is by using an app-level entry point (support for this was added for Node.js Azure Functions here).

  1. Create a module to start the APM agent. For example, a file at the root of your repository named "initapm.js":

    // initapm.js
    require('elastic-apm-node').start({
      
    })

    Optional configuration options can be added here.

  2. Add a "main" entry to your package.json pointing to the app init file.

    ...
      "main": "initapm.js",
    ...

    If your application already has a "main" init file, you can instead add the require('elastic-apm-node').start() to top of that file.

Step 3: Configure the APM agent

edit

The APM agent can be configured with options to the .start() method or with environment variables. Using environment variables allows one to use application settings in the Azure Portal which allows hiding values and updating settings without needing to re-deploy code.

Open Configuration > Application settings for your Function App in the Azure Portal and set:

ELASTIC_APM_SERVER_URL: <your APM server URL from the prerequisites step>
ELASTIC_APM_SECRET_TOKEN: <your APM secret token from the prerequisites step>

For example:

Configuring the APM Agent in the Azure Portal

For local testing via func start you can set these environment variables in your terminal, or in the "local.settings.json" file. See the agent configuration guide for full details on supported configuration variables.

Step 4: (Re-)deploy your Azure Function app

edit
func azure functionapp publish <APP_NAME>

Now, when you invoke your Azure Functions, you should see your application show up as a Service in the APM app in Kibana and see APM transactions for function invocations. Tracing data is forwarded to APM server after a period of time, so allow a minute or so for data to appear.

Limitations

edit

This instrumentation does not send an APM transaction or error to APM server when a handler has an uncaughtException or unhandledRejection. The Azure Functions Node.js reference has a section with best practices for avoiding these cases.

Azure Functions instrumentation currently does not collect system metrics in the background because of a concern with unintentionally increasing Azure Functions costs (for Consumption plans).

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 captureBody config option
  • By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. To disable this, use the sanitizeFieldNames config option
  • To apply custom filters, use one of the filtering functions

Compatibility

edit

See Supported technologies for details.

Troubleshooting

edit

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