Autoinstrumentation for node.js

How you can contact us:

Technical Assistance

Request product support from SAP
Non-Technical Assistance

Request non-product support or provide feedback on SAP Support Portal site

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.4.3.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

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} <main file name>.js"

  }

}

For CAP based applications:

{

  "scripts": {

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

  }

}

Disabling Autoinstrumentation

If you want to disable the autoinstrumentation (e.g. in case of an emergency) you can do this by

set the environment variable

SAP_CALM_INSTRUMENTATION_ENABLED=false

restart the application

The following variables can also be be set and are effective after restarting the application:

Tracing

If you only want to disable the tracing auto instrumentation you can set.

SAP_CALM_TRACING_ENABLED=false

Metrics

If you only want to disable the metrics auto instrumentation you can set.

SAP_CALM_METRICS_ENABLED=false

Logging

Log level can be specified via the the SAP_CALM_DCI_LOG_LEVEL environment variable, e.g.

SAP_CALM_DCI_LOG_LEVEL=debug

Authentication

In order to export towards SAP Cloud ALM one has to setup the destination via OAuth based authentication.

Bind to Destination Service
Add the below lines to mta.yaml

modules:

- name: otel-instrumentation

  requires:

   - name: <destination-service-name>

resources:

 - name: <destination-service-name>

   parameters:

     service-plan: lite

     service: destination

   type: org.cloudfoundry.managed-service

Create a destination configuration using Destination Service for persisting the baseUrl and retrieving it.
The Destination endpoint should be your SAP Cloud ALM endpoint API url. How to retrieve this, can be found here
The Destination name should be in the format CALM_datacollector_<space-name>.
- The <space-name> is the space where the microservice has to be deployed.
- Example: If the application is in space "xyz", the destination configuration name can be CALM_datacollector_xyz
As Proxy Type use Internet
As Authentication Type use OAuth2ClientCredentials
Enter the client ID/secret and token URL. How to retrieve these can be found here.

The destination should look like this: