Autoinstrumentation for Node.js
Setup
package.json
{
"dependencies": {
"@sap/xotel-agent-ext-js": "https://73555000100200018064.npmsrv.cdn.repositories.cloud.sap/@sap/xotel-agent-ext-js/-/xotel-agent-ext-js-1.5.20.tgz",
"cf-nodejs-logging-support": "7.4.0-beta.4",
"@sap/opentelemetry-exporter-for-sap-cloud-logging": "0.2.0"
},
}
For deployment, the below environment parameter needs to be configured. OTEL_RESOURCE_ATTRIBUTES not required anymore as of xotel-agent-ext-js version 1.5.16.
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:
mta.yaml
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');
// Initialization of Exception Monitoring:
const sdklogs = require ('@opentelemetry/sdk-logs');
const calmExtAutoConf = require('@sap/xotel-agent-ext-js/dist/config/AutoInstrumentationConfig');
const cflog = require("cf-nodejs-logging-support");
const otellog = require('@sap/opentelemetry-exporter-for-sap-cloud-logging');
// Create an instance of the OpenTelemetryLogsOutputPlugin.
// By default, it will use the global logger provider.
// Use a custom loggerProvider to capture Cloud Foundry attributes.
const cfLoggerProvider = new sdklogs.LoggerProvider({resource: new otellog.CFApplicationDetector().detect()});
const otelOutputPlugin = new cflog.OpenTelemetryLogsOutputPlugin(cfLoggerProvider)
// Optionally set whether additional log fields should be included as log attributes.
// Default: include custom fields only.
otelOutputPlugin.setIncludeFieldsAsAttributes(cflog.FieldInclusionMode.CustomFieldsOnly)
// register the plugin
cflog.addOutputPlugin(otelOutputPlugin)
// optional, if application is bound to application-logs service
cflog.setCustomFieldsFormat(cflog.CustomFieldsFormat.All);
// add CALM Extension Exception Monitoring log processor
cfLoggerProvider.addLogRecordProcessor(calmExtAutoConf.createEXMLogRecordProcessor());
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')(() => {
// Initialization of Exception Monitoring:
const sdklogs = require ('@opentelemetry/sdk-logs');
const calmExtAutoConf = require('@sap/xotel-agent-ext-js/dist/config/AutoInstrumentationConfig');
const cflog = require("cf-nodejs-logging-support");
const otellog = require('@sap/opentelemetry-exporter-for-sap-cloud-logging');
// Create an instance of the OpenTelemetryLogsOutputPlugin.
// By default, it will use the global logger provider.
// Use a custom loggerProvider to capture Cloud Foundry attributes
const cfLoggerProvider = new sdklogs.LoggerProvider({resource: new otellog.CFApplicationDetector().detect()});
const otelOutputPlugin = new cflog.OpenTelemetryLogsOutputPlugin(cfLoggerProvider);
// Optionally set whether additional log fields should be included as log attributes.
// Default: include custom fields only.
otelOutputPlugin.setIncludeFieldsAsAttributes(cflog.FieldInclusionMode.CustomFieldsOnly);
// Register the plugin
cflog.addOutputPlugin(otelOutputPlugin);
// optional, if application is bound to application-logs service
cflog.setCustomFieldsFormat(cflog.CustomFieldsFormat.All);
// Add CALM Extension Exception Monitoring log processor
cfLoggerProvider.addLogRecordProcessor(calmExtAutoConf.createEXMLogRecordProcessor());
//---------------------------------
// initialize your application here
})
Setup at Deployment Level
Require the tracer via node arguments in the mta.yaml file:
mta.yaml
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/.bin/cds-serve"
}
}