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. MongDB 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 automatically include the package inside the dependencies section of your package.json.

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

  "dependencies": {
    "@traceable/nodejsagent": "1.2.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 configuration file

Using a configuration file to configure the Node.js tracing agent comprises of 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 of complete config.yaml file:

service_name: nodeagent
reporting:
  endpoint: http://localhost:4317
  secure: false
  trace_reporter_type: OTLP
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
  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 that you created in step 1 as the value for the environment variable. For example, TA_CONFIG_FILE=./config.yaml.

Configure using environment variable

node -r @traceable/nodejsagent server.js

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

npm update @traceable/nodejsagent

npm uninstall @traceable/nodejsagent