Node.js

Traceable's Node.js tracing agent is an in-app tracing agent. It collects information from your Node.js application and sends it to Traceable's platform agent. The platform agent sends the information to Traceable's SaaS platform for further analysis. The topic covers deployment, verification, troubleshooting, upgrade, and uninstall information.

Before you begin

Make a note of the following points before you proceed with the deployment:

• Make sure that Traceable's platform agent is already installed. For more information, see Platform agent.

• Your Node.js application must be using Node 8.17 or later.

Traceable's Node.js tracing agent package comes with pre-compiled extensions that support the following:

Supported operating system

The following operating systems are supported:

• Debian 10 and later.

• Ubuntu 18.0.4 and later.

• CentOS 7 and later.

• Alpine 3.9 and later. You would need Traceable Platform agent 1.21.2 or later for blocking support on Alpine.

Supported frameworks

The following frameworks are supported:

• Hapi - version 17 and later.

• Express - version 4 and later.

• Sails - version 1 and later.

• NestJS - version 4 and later.

• Koa - version 2 and later.

Supported database libraries

The following database libraries are supported:

• mysql - version 2 and later.

• mysql2 - version 2 and later.

• Postgres - 7.* and 8.*

• MongoDB - version 3.3 and later and earlier than 4. MongoDB 4 and later is not supported.

Other libraries

A few other supported libraries:

• HTTP and HTTPS (these are a part of node.js standard library)

• GraphQL - version 14 and later

Download

The package is downloaded as part of the installation process through npm.

Installation

To install Traceable's Node.js tracing agent, enter the following command. The package is downloaded and installed as part of the installation process.

npm install @traceable/nodejsagent --save

The --save option instructs NPM to include the package inside the dependencies section of your automatically  package.json.

Make sure that the package.json has the following entries:

  "dependencies": {
    "@traceable/nodejsagent": "1.7.0",
    ... # rest of your dependencies go here
  }

Configuration

You can configure Traceable's Node.js tracing agent using one of the following methods:

• Using a configuration file

• Using environment variables

Configure using a configuration file

Using a configuration file to configure the Node.js tracing agent comprises two steps:

1. Configuring the file

2. Setting the environment variable for the configuration file

Step 1 - Configure the file

Create a config.yaml file as shown below:

service_name: enter_a_service_name_here
reporting:
  endpoint: http://agent.traceableai:4317 # update to point to a TPA
opa:
  endpoint: http://agent.traceableai:8181/ # update to point to a TPA
blocking_config:
  enabled: true
  remote_config:
    endpoint: agent.traceableai:5441 # update to point to a TPA

Following is a sample config.yaml file:

service_name: nodeagent
reporting:
  endpoint: http://localhost:4317
  secure: false
  trace_reporter_type: OTLP
  cert_file:
data_capture:
  http_headers:
    request: true
    response: true
  http_body:
    request: true
    response: true
  rpc_metadata:
    request: true
    response: true
  rpc_body:
    request: true
    response: true
  body_max_size_bytes: 131072
  body_max_processing_size_bytes: 1048576
propagation_formats: ["TRACECONTEXT"]
enabled: true
resource_attributes: { }
opa:
  enabled: true
  endpoint: http://opa.traceableai:8181/
  poll_period_seconds: 60
blocking_config:
  enabled: true
  debug_log: true
  evaluate_body: true
  skip_internal_request: false
  cert_file:
  modsecurity:
    enabled: true
  regionBlocking:
    enabled: true
  remote_config:
    enabled: true
    endpoint: localhost:5441/
    poll_period_seconds: 30

Step 2 - Set the environment variable

Set the environment variable TA_CONFIG_FILE. Use the path of the configuration file you created in step 1 as the value for the environment variable. For example, TA_CONFIG_FILE=./config.yaml.

Configure using the environment variable

The following table details the full list of supported environment variables:

Name	Default	Description
TA_OPA_ENABLED	true	When true, OPA evaluation is enabled to block requests.
TA_OPA_ENDPOINT	http://opa.traceableai:8181/	Represents the endpoint for polling OPA configuration file, for example, http://opa.traceableai:8181/.
TA_OPA_POLL_PERIOD_SECONDS	60	The poll period in seconds to query the OPA service.
TA_BLOCKING_CONFIG_ENABLED	false	The top-level switch that enables or disables blocking functionality.
TA_BLOCKING_CONFIG_DEBUG_LOG	false	Enables verbose logging of the native extensions.
TA_BLOCKING_CONFIG_MODSECURITY_ENABLED	true	Represents the endpoint for reporting the traces. For the ZIPKIN reporter type, use http://api.traceable.ai:9411/api/v2/spans. For OTLP reporter type, use http://api.traceable.ai:4317
TA_BLOCKING_CONFIG_EVALUATE_BODY	true	Determines whether the request body should be analyzed.
TA_BLOCKING_CONFIG_REGION_BLOCKING_ENABLED	true	Enables IP-based blocking.
TA_BLOCKING_CONFIG_REMOTE_CONFIG_ENABLED	true	Denotes whether the configuration needs to be fetched from remote or not.
TA_BLOCKING_CONFIG_REMOTE_CONFIG_ENDPOINT	http://localhost:5441	Denotes the agent endpoint to connect to for configuration. For example, localhost:5441.
TA_BLOCKING_CONFIG_REMOTE_CONFIG_POLL_PERIOD_SECONDS	30	The poll period in seconds to query for configuration updates.
TA_BLOCKING_CONFIG_SKIP_INTERNAL_REQUEST	true	When set to true, the blocking evaluation is skipped for internal requests, that is, the requests coming from private IP addresses.
TA_SERVICE_NAME	nodeagent	Identifies the service, for example, “my service.”
TA_REPORTING_ENDPOINT	http://localhost:4317	Configure the reporting endpoint.
TA_REPORTING_SECURE	false	When set to true, connects to endpoints over TLS.
TA_REPORTING_CERT_FILE	-	The path to the certificate file.
TA_REMOTE_CONFIG_CERT_FILE	-	The path to the certificate file.
TA_DATA_CAPTURE_HTTP_HEADERS_REQUEST	true	When set to false, the client request capture is disabled.
TA_DATA_CAPTURE_HTTP_HEADERS_RESPONSE	true	When set to false, the response is not captured.
TA_DATA_CAPTURE_HTTP_BODY_REQUEST	true	When set to false, request body capture is disabled.
TA_DATA_CAPTURE_HTTP_BODY_RESPONSE	true	When set to false, response body capture is disabled.
TA_DATA_CAPTURE_RPC_METADATA_REQUEST	true	When set to false, request metadata capture is disabled.
TA_DATA_CAPTURE_RPC_METADATA_RESPONSE	true	When set to false response metadata capture is disabled.
TA_DATA_CAPTURE_RPC_BODY_REQUEST	true	When set to false RPC request body capture is disabled.
TA_DATA_CAPTURE_RPC_BODY_RESPONSE	true	When set to false RPC response body capture is disabled.
TA_DATA_CAPTURE_BODY_MAX_SIZE_BYTES	131072	Is the maximum size of captured body in bytes. Default should be 131_072 (128 KiB).
TA_DATA_CAPTURE_BODY_MAX_PROCESSING_SIZE_BYTES	1048576	Defines the maximum body size processed by filters in bytes.  For the uncompressed bodies, Traceable captures all bytes up to body_max_processing_size_bytes in memory and passes that through the filter. For compressed and GRPC bodies, if the size is larger than this, Traceable ignores it entirely; otherwise, the body is decompressed/decoded and then passed to the filter.
TA_PROPAGATION_FORMATS	['TRACECONTEXT']	List the supported propagation formats, for example, TA_PROPAGATION_FORMATS="B3,TRACECONTEXT".
TA_ENABLED	true	When false, disables the agent.
TA_LOG_LEVEL	info	Controls granularity of produced logs, one of debug, info, warning, error

---

Add the agent to your application code

To enable in-app tracing, you must add the Traceable's tracing agent to your application code. You can instrument the Node.js tracing agent using one of the following two methods:

• Auto instrumentation

• Manual instrumentation

Important

You should use only one method to instrument the application. Do not use both methods at the same time.

Auto instrumentation

To auto-instrument your Node.js application with the tracing agent, modify your application startup command to use the -r option. For example:

node -r @traceable/nodejsagent server.js

Important

If using ES6 import syntax in your application, you must use auto instrumentation instead of manual instrumentation. For example, import express from 'express' instead of const express = require('express'). The former requires auto instrumentation.

Manual instrumentation

To manually instrument your Node.js application, add the following lines of code to your application's main entry file:

const traceable = require('@traceable/nodejsagent');
const traceableAgent = new traceable.TraceableAgent()
traceableAgent.instrument() # adds observability instrumentation
traceableAgent.addTraceableFilter() # adds traceable blocking features

---

Run your application

Run your application with the tracing agent. Complete the following:

• If you have used auto instrumentation

  ActionScript

  TA_CONFIG_FILE=./config.yaml TA_LOG_LEVEL=DEBUG node -r @traceable/nodejsagent server.js

• If you have manually instrumented your application

  ActionScript

  TA_CONFIG_FILE=./config.yaml TA_LOG_LEVEL=DEBUG node server.js

The above commands use TA_LOG_LEVEL=DEBUG. This is optional; however, using this option would indicate whether everything is working as expected.

---

Verification

After you have exercised your application with traffic, navigate to Traceable platform and verify if your Node.js tracing agent is displayed.

---

Upgrade

To upgrade Traceable's Node.js tracing agent, enter the following command:

npm update @traceable/nodejsagent

---

Uninstall

If you wish to uninstall the tracing agent, enter the following command:

npm uninstall @traceable/nodejsagent

---

Troubleshooting

Node.js dropping spans

If you observe that your Node.js application is not exporting the spans at a reasonable rate, or if the spans pass the queue size limits frequently, then customize the batch span processor using the environment variable defined in OpenTelemetry Environment Variable Specification. Specifically, configure the following two environment variables:

• OTEL_BSP_MAX_EXPORT_BATCH_SIZE

• OTEL_BSP_SCHEDULE_DELAY