--- title: "Node.js agent" slug: "nodejs-agent" tags: ["node.js", "serverless"] updated: 2024-06-03T04:35:04Z published: 2024-06-03T04:35:04Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Node.js agent 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. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_node_js_deployment.jpg) --- ## 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](/v1/docs/tpa). - 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. ```actionscript 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: ```actionscript  "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 Note Environment variables take precedence over values set through the configuration file. ### 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: ```yaml 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: ```yaml 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 If you wish to use environment variables, prepend `TA` to the YAML field you wish to set. For example, to set the service name, you would set `TA_SERVICE_NAME=your_service_name`. 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/](http://opa.traceableai:8181/) | Represents the endpoint for polling OPA configuration file, for example, [http://opa.traceableai:8181/](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 [h](http://api.traceable.ai:9411/api/v2/spans)[ttp://api.traceable.ai:9411/api/v2/spans.](http://api.traceable.ai:9411/api/v2/spans.) - For OTLP reporter type, use [http://api.traceable.ai:4317](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](http://localhost:5441) | Denotes the agent endpoint to connect to for configuration. For example, [localhost:5441](http://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](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: ```actionscript 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: ```actionscript 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 ** ** ```actionscript TA_CONFIG_FILE=./config.yaml TA_LOG_LEVEL=DEBUG node -r @traceable/nodejsagent server.js ``` - If you have **manually**instrumented your application ActionScript ** ** ```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](https://app.traceable.ai/administration/agents?time=1h&type=tracing-agents) and verify if your Node.js tracing agent is displayed. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_nodejs_verification.png) --- ## Upgrade To upgrade Traceable's Node.js tracing agent, enter the following command: ```actionscript npm update @traceable/nodejsagent ``` --- ## Uninstall If you wish to uninstall the tracing agent, enter the following command: ```actionscript 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](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/#batch-span-processor). Specifically, configure the following two environment variables: - `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` - `OTEL_BSP_SCHEDULE_DELAY`