Node.js Auto-Instrumentation

Want to use OpenTelemetry instead? Read these docs to get started!

If your app is written in Node.js, you can get started quickly with Cloud Observability. Download the Auto-Installer, then configure it to communicate with your Cloud Observability Microsatellites. When you deploy your app, all supported libraries will send trace data to Cloud Observability.

To ensure you can access all Cloud Observability functionality, including infrastructure metrics reporting, update your tracer to the latest release. To update, simply follow the instructions for installing the tracer. No code changes are needed.

These Auto-Installers are forked from Datadog’s contribution of their tracers to the OpenTelemetry project. You can find the original Datadog docs here.

This library MUST be imported and initialized before any instrumented module. When using a transpiler, you MUST import and initialize the tracer library in an external file and then import that file as a whole when building your application. This prevents hoisting and ensures that the tracer library gets imported and initialized before importing any other instrumented module.

Supported Node Versions

Node >=8 is supported by this Auto-Installer. Only even versions like 8.x and 10.x are officially supported. Odd versions like 9.x and 11.x should work but are not officially supported.

Install the Auto-Installer

1. Install the Node.js Auto-Installer, using npm.

   1
    npm install --save ls-trace
   

2. Import and initialize the Auto-Installer and set trace propagation to use B3 headers.

   Cloud Observability recommends using B3 headers for trace propagation as the default, especially on hybrid deployments, as it is the most widely supported header at this time.

   1
   2
   3
   4
   5
   6
   7
    const tracer = require('ls-trace').init(
      {
    	experimental: {
    	  b3: true
    	 }
      }
    )
   

   1
   2
   3
   4
   5
   6
   7
    // server.js
    import "./tracer"; // must come before importing any instrumented module.
   
    // tracer.js
    import tracer from "ls-trace";
    tracer.init(); // initialized in a different file to avoid hoisting.
    export default tracer;
   

Configure the Auto-Installer to Send Data to Cloud Observability

To send data from your system to Cloud Observability, you need to configure the Auto-Installer to:

• Point to your Microsatellites
• Send global tags required by Cloud Observability to ingest and display the data to you.

To configure the Auto-Installer:

Configure the Auto-Installer to point to the Cloud Observability Microsatellites by setting these environment variables. Use the right values, depending on if you are using on-premise, Cloud Observability public, or Developer Mode Satellites.

Start tabs

On-Premise Microsatellites

1
2
DD_TRACE_AGENT_URL=https://<Satellite host>:<Satellite port>
DD_TRACE_GLOBAL_TAGS="lightstep.service_name:<service_name>,lightstep.access_token:<access_token>"

Public Microsatellites

1
2
DD_TRACE_AGENT_URL=https://ingest.lightstep.com:443
DD_TRACE_GLOBAL_TAGS="lightstep.service_name:<service_name>,lightstep.access_token:<access_token>"

Developer Mode

1
2
DD_TRACE_AGENT_URL=http://localhost:8360
DD_TRACE_GLOBAL_TAGS="lightstep.service_name:<service_name>,lightstep.access_token:developer"

End code tabs

The host and port values for on-premise Microsatellites is your pool address, found in your configuration file.

When setting the environment variable DD_TRACE_GLOBAL_TAGS, the following variables must be included:

• service_name:
  The name of the service from which spans originate. This tag allows Cloud Observability to accurately report on your services, with features such as the Service diagram and the Service Directory
• access_token:
  The access token for the project the tracers report to. Cloud Observability Microsatellites need this token to accept and store span data from the tracer. Reports from clients with invalid or deactivated access tokens will be rejected on ingress.

Troubleshooting

Following are issues you may have after instrumentation, and how to resolve them.

Operation Names Aren’t Human Readable

Symptom
Operation names in Cloud Observability are not clear or are very long and unhelpful.

This feature requires a Satellite upgrade to the June 2020 release.

This can happen because the auto-installer is getting the name from a parameter in Datadog that might not be appropriate for your language. You can set that parameter to different values to see if that results in better operation names.

You can use either the resource or the name parameter, or both.

Which to use (or if using the both, the order to use) depends on the language of the installer. Refer to the Datadog docs for more info.

To configure how the operation name is set, add the following parameter to your Microsatellite configuration:

1
2
3
4
5
receivers:
  datadog:
	operation_name_extractors:
  	  - resource
  	  - name

If you set both, the order of the values matters. Cloud Observability tries to extract a name from the first variable value. If one isn’t found, it looks for the second value and uses that.

What’s Auto-Instrumented

The following auto-instrumentation libraries are supported:

• Frameworks
• Native modules
• Data stores
• Workers
• Promise libraries
• Loggers

Frameworks

Native Modules

Data Stores

Workers

Promise Libraries

Loggers

See also

Measure your instrumentation quality

Updated Mar 3, 2020