Auto-instrumentation for Node.js

Setup

otel 2.0

Open telemetry JS libraries 2.x are supported starting with xotel-agent-ext-js 2.0.0.

{

"dependencies": {

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

        },

}

For deployment, the below environment parameters needs to be configured. OTEL_RESOURCE_ATTRIBUTES not required anymore as of xotel-agent-ext-js version 1.5.23.

SAP_CALM_SERVICE_NAME = <name of your application>
SAP_CALM_SERVICE_TYPE = SAP_CP_CF

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

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)
CALM_OTEL_AGENT_EXT_TRACER_CONFIG='{"urlNormalizerPatterns":["odata","(?<=v)\\d+"]}'	The value of the variable is a JSON string. The value for urlNormalizerPatterns is an array of regular expressions. Every match will be replaced by *.

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

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/.bin/cds-serve"
  }
}

{ "dependencies": { "@sap/xotel-agent-ext-js": "https://73555000100200018064.npmsrv.cdn.repositories.cloud.sap/@sap/xotel-agent-ext-js/-/xotel-agent-ext-js-2.0.4.tgz", "@cap-js/telemetry": "2.0.1", "@sap/cds": "^9" }, "cds": { "requires": { "telemetry": { "logging": { "processor": { "module": "@sap/xotel-agent-ext-js", "class": "ExmLogProcessor" }, "exporter": { "module": "@opentelemetry/exporter-logs-otlp-grpc", "class": "OTLPLogExporter" } } } } } }

const cds = require ('@sap/cds') const LOG = cds.log('cds.log') // logging an error LOG.error('NodeJs error message') try { // Code throwing an Error } catch (e) { // logging an error with details LOG.error('NodeJs error message', e) }

Checklist

Setup

otel 2.0

Additional steps for Exception Monitoring

Custom-built applications using cloud logging library

Custom-built applications using CDS library (experimental, supported in versions of xotel-agent-ext-js >= 2.0.4)

Troubleshooting

Disabling auto-instrumentation