Autoinstrumentation for node.js

Setup

{

"dependencies": {

"@sap/xotel-agent-ext-js": "https://73555000100200018064.npmsrv.cdn.repositories.cloud.sap/@sap/xotel-agent-ext-js/-/xotel-agent-ext-js-1.5.13.tgz",

},

}

For deployment, the below environment parameter needs to be configured:

SAP_CALM_SERVICE_NAME = <name of your application
SAP_CALM_SERVICE_TYPE = SAP_CP_CF
OTEL_RESOURCE_ATTRIBUTES = sap.tenancy.tenant_id=<your provider subaccount id>

For example in mta.yaml this can look like this:

modules:

- name: <service module name>

properties:

SAP_CALM_SERVICE_NAME: <application name>
SAP_CALM_SERVICE_TYPE: SAP_CP_CF
OTEL_RESOURCE_ATTRIBUTES: sap.tenancy.tenant_id=<your provider subaccount id>

Parameters to be replaced:

<application name> arbitrary name of your application
<your provider subaccount id> Technical ID of the subaccount, where the instrumented application is running. The technical ID can be found in the SAP BTP cockpit and has the form of a guid: 12345678-1234-1234-1234-123456789abc and will be used by SAP Cloud ALM to map the data to the corresponding cloud service.

If you are using an mta application make sure that node modules and the package-lock.json are included in your mtar:

modules:

  - name: <your service module>

    type: nodejs

    path: gen/srv

    build-parameters:

      builder: npm

      ignore:

        # - node_modules

        # - package-lock.json

In some cases your mta build setup might copy the built resources to specific folder, e.g. gen/srv. If the node_modules and package-lock.json are not present in this folder we need to tell the mbt command to add these as well:

build-parameters:

  before-all:

    - builder: custom

      commands:

        - npm install --production

        - ...

        - npm install --prefix ./gen/srv

Instrumentation Settings

The following environment variables can be set to configure the behavior of the instrumentation:

Name	Description
SAP_CALM_DCI_AGG_THRESHOLD	Optional - Threshold in ms spans to be aggregated (default: 100, i.e. all spans with a response time lower than 100ms will be aggregated and grouped by action, request, user, span type and span kind)
SAP_CALM_DCI_AGG_USER	Optional - Specify whether user ids shall be aggregated spans (default: true)

Setup at Source Code Level

On application startup load the above-mentioned instrumentation:

const tracer = require('@sap/xotel-agent-ext-js/dist/common/tracer');

NOTE: Require the tracer before you initialize your application. Otherwise the auto-instrumentation will not work. However, for some applications this will still not be sufficient. In such cases we recommend to initialize the application as a callback of the auto-instrumentation:

const tracer = require('@sap/xotel-agent-ext-js/dist/common/tracerCallback')(() => {

  // initialize your application here

})

Setup at Deployment Level

Require the tracer via node arguments in the mta.yaml file:

modules:

  - name: <your srv module>

    type: nodejs

    properties:

      NODE_ARGS: -r @sap/xotel-agent-ext-js/dist/common/tracer

In the package.json file of your project modify the start script to pick up the required tracer.

For regular node.js applications:

{

"scripts": {

"start": "node ${NODE_ARGS} <your main file name>.js"

}

}

For CAP based applications with @sap/cds < 7:

{

  "scripts": {

    "start": "node ${NODE_ARGS} ./node_modules/@sap/cds/bin/cds run"

  }

}

For CAP based applications with @sap/cds >= 7:

{

  "scripts": {

    "start": "node ${NODE_ARGS} ./node_modules/@sap/cds/bin/cds-serve"

  }

}