Azure App Service Tracing for Node.js

To use Instana to monitor a Node.js application that runs as an Azure App Service, install and activate the Node.js Azure App Service Collector.

Supported platforms

Instana supports Azure App Service monitoring only on the Linux platform.

Prerequisites

If you need full monitoring including metrics and infrastructure correlation of your Microsoft Azure App Services, install the Azure Cloud Service agent.

Note: Even if the agent is not installed, the Node.js Azure App Service Collector gathers trace data and sends it to the Instana serverless acceptor endpoint, which creates a service instance.

Enabling the collector by using Azure CLI

To enable the Node.js Azure App Service Collector with Azure CLI, you need to configure the Node.js Azure App Service In-process Collector in your Node.js application.

Installing the collector

Add the Instana Collector package @instana/azure-container-services to your project dependencies:

npm install --save @instana/azure-container-services

Note: If you use a different package manager, adjust the npm commands accordingly.

Activating tracing

Note: Before you activate tracing, make sure that your Azure App Service is deployed in the Azure environment.

Use the following commands to enable the collector with Azure CLI. If your application uses CommonJS, follow the steps in the following CommonJS section to enable tracing. If your application uses ECMAScript modules, follow the steps in the following ECMAScript modules section to enable tracing. For more information about the Instana environment variables, see the Environment variables section.

CommonJS

If your application uses CommonJS, use the following command:

az webapp config appsettings set \
    --name <app-name> \
    --resource-group <resource-group-name> \
    --settings NODE_OPTIONS='--require /path/to/instana/node_modules/@instana/azure-container-services' \
    INSTANA_ENDPOINT_URL=<instana-endpoint-url>  INSTANA_AGENT_KEY=<instana-agent-key>

The following example shows a typical path to node_modules: ./node_modules/@instana/azure-container-services.

ECMAScript modules

If the application uses ECMAScript modules, use the following command (Node.js 18.19 and later):

az webapp config appsettings set \
    --name <your-app-name> \
    --resource-group <your-resource-group-name> \
    --settings NODE_OPTIONS='--import /path/to/instana/node_modules/@instana/azure-container-services/esm-register.mjs' \
    INSTANA_ENDPOINT_URL=<instana-endpoint-url>  INSTANA_AGENT_KEY=<instana-agent-key>

The following example shows a typical path to node_modules: ./node_modules/@instana/azure-container-services/esm-register.mjs.

Note:

If your Node.js version is earlier than v18.19.0, you must use --experimental-loader /path/to/instana/node_modules/@instana/azure-container-services/esm-loader.mjs instead of --import /path/to/instana/node_modules/@instana/azure-container-services/esm-register.mjs.
The use of --experimental-loader with esm-loader.mjs is no longer supported in current versions and will be removed in the next upgrade. For more details, see the Breaking changes section.

Enabling the collector without Azure CLI

To enable the collector on your Node.js App Service, either follow the instructions in the Manual installation section or if you use Docker, see the instructions in the Docker installation section.

Manual installation

To configure the Node.js Azure App Service Collector, you need to install the Node.js Azure App Service In-process Collector and enable tracing.

Installing the collector

Add the Instana collector package @instana/azure-container-services to your project's dependencies:

npm install --save @instana/azure-container-services

Note: If you use a different package manager, adjust the npm commands accordingly.

Activating tracing

If your application uses CommonJS, follow the steps in the following CommonJS section to activate tracing. If your application uses ECMAScript modules, follow the steps in the following ECMAScript modules section to activate tracing.

CommonJS

For applications that use CommonJS, complete one of the following steps when you start the Node.js executable. Setting either NODE_OPTIONS or the --require flag loads and initializes the Node.js Collector before your application code.

Set the NODE_OPTIONS variable before you start the Node.js activation process:

NODE_OPTIONS="--require /path/to/instana/node_modules/@instana/azure-container-services"

Alternately, add the --require parameter to the command that starts Node.js. If you normally start the application by using the app/index.js node command, add an extra --require command-line argument. See the following example:
```
node --require /path/to/instana/node_modules/@instana/azure-container-services app/index.js
 
```

ECMAScript modules

If the application uses ECMAScript modules, complete either of the following steps when you start the Node.js executable file. Setting NODE_OPTIONS or using the --import argument initializes the Node.js collector before the application code. For more information about ECMAScript modules, see the Node.js official documentation.

Before you start the Node.js activation process, set the NODE_OPTIONS variable (Node.js 18.19 and later):

NODE_OPTIONS="--import=/path/to/instana/node_modules/@instana/azure-container-services/esm-register.mjs"

Alternatively, include the --import parameter when you start Node.js application. If you start your application with the node app/index.mjs command, append the --import command to the command-line argument. See the following example:
```
node --import /path/to/instana/node_modules/@instana/azure-container-services/esm-register.mjs app/index.mjs
```

Docker installation

If you are building the application with Docker, you don't need to manually install the @instana/azure-container-services package. The package is included in the Docker image that is available at the icr.io/instana/azure-container-services-nodejs image registry.

Instana currently supports only the x86_64 architecture.

This image is not intended for use in FedRAMP-compliant environments.

Activating tracing

If your application uses CommonJS, follow the steps in the following CommonJS section to activate tracing. If your application uses ECMAScript modules, follow the steps in the following ECMAScript modules section to activate tracing.

CommonJS

If you build the application with Docker, add the following lines to your Dockerfile after the last FROM clause:

COPY --from=icr.io/instana/azure-container-services-nodejs:latest /instana /instana

ENV NODE_OPTIONS="--require /instana/node_modules/@instana/azure-container-services"

Then, build the container, and push it to the image repository of your choice.

ECMAScript modules

Add the following lines to your Dockerfile after the last FROM clause (Node.js 18.19 and later):

COPY --from=icr.io/instana/azure-container-services-nodejs:latest /instana /instana

ENV NODE_OPTIONS="--import=/instana/node_modules/@instana/azure-container-services/esm-register.mjs"

Then, build the container, and push it to the image repository of your choice.

Configuring environment variables in the Azure portal

Before you set the environment variables, make sure that you configured the Node.js Azure App Service Collector in your Azure App Service successfully and deployed your app in the Azure environment. To configure the necessary Instana environment variables on the Azure portal, complete the following steps:

Open the Azure App Service that Instana needs to trace.
On the configuration page, click Application Settings. Then, add the environment variables as described in the Environment variables section.
Save the changes, and restart the application.

Environment variables

To configure the Node.js Azure App Service Collector, set the following environment variables:

INSTANA_ENDPOINT_URL: Your serverless monitoring endpoint. Make sure to use the correct value for your region that starts with https://serverless-.
INSTANA_AGENT_KEY: Your agent key.

You can set these variables through the Azure CLI or within the Azure portal.