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 Lightstep. Download the Auto-Installer, then configure it to communicate with your Lightstep Satellites. When you deploy your app, all supported libraries will send trace data to Lightstep. The Lightstep tracer also collects and reports on infrastructure metrics, communicating directly with the Lightstep Engine.

To ensure you can access all Lightstep 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.

    Lightstep 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 Lightstep

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

  • Point to your Satellites
  • Send global tags required by Lightstep to ingest and display the data to you.

To configure the Auto-Installer:

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

Start tabs

On-Premise Satellites

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 Satellites

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 satellites 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 Lightstep 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. Lightstep Satellites 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.

Configure Metrics Reporting

Along with the tracer collecting telemetry data to report on performance issues and other contextual information to help you with root cause analysis, Lightstep can also ingest and report on infrastructure metrics for a service to further assist in your investigations.

To ensure you can access all Lightstep 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.

The following infrastructure metrics are sent to Lightstep:

  • CPU Usage (%)
  • Memory (%)
  • Network (bytes)

  • Event Loop Delay
  • Garbage Collect (GC) Pause Time
  • Total Heap Memory

These metrics are displayed when you compare performance of a service over two different time periods.

Machine metrics are enabled by default. However, if you use a proxy, you need to set this environment variable to point to the Lightstep endpoint.

LS_METRICS_URL=http://localhost:8126/metrics
or
LS_METRICS_URL=<scheme>://<proxy_host>:<proxy_port>/metrics

If you don’t want metrics reported, you can configure the auto-installer to turn it off.

To turn metrics off:

Set the following environment variable:
LS_METRICS_ENABLED=False

What’s Auto-Instrumented

The following auto-instrumentation libraries are supported:

Frameworks

ModuleVersionsSupport TypeNotes
connect>=2Fully Supported 
express>=4Fully SupportedSupports Sails, Loopback, and more
fastify>=1Fully Supported 
graphql>=0.10Fully SupportedSupports Apollo Server and express-graphql
hapi>=2Fully Supported 
koa>=2Fully Supported 
paperplane>=2.3Fully SupportedNot supported in serverless-mode
restify>=3Fully Supported 

Native Modules

ModuleSupport Type
dnsFully Supported
httpFully Supported
httpsFully Supported
netFully Supported

Data Stores

ModuleVersionsSupport TypeNotes
cassandra-driver>=3Fully Supported 
elasticsearch>=10Fully SupportedSupports @elastic/elasticsearch versions >=5
ioredis>=2Fully Supported 
knex>=0.8Fully SupportedThis integration is only for context propagation
memcached>=2.2Fully Supported 
mongodb-core>=2Fully SupportedSupports Mongoose
mysql>=2Fully Supported 
mysql2>=1Fully Supported 
pg>=4Fully SupportedSupports pg-native when used with pg
redis>=0.12Fully Supported 
tedious>=1Fully SupportedSQL Server driver for mssql and sequelize

Workers

ModuleVersionsSupport TypeNotes
amqp10>=3Fully SupportedSupports AMQP 1.0 brokers (i.e. ActiveMQ, Apache Qpid)
amqplib>=0.5Fully SupportedSupports AMQP 0.9 brokers (i.e. RabbitMQ, Apache Qpid)
generic-pool>=2Fully Supported 
kafka-node Coming Soon 
rhea Coming Soon 

Promise Libraries

ModuleVersionsSupport Type
bluebird>=2Fully Supported
promise>=7Fully Supported
promise-js>=0.0.3Fully Supported
q>=1Fully Supported
when>=3Fully Supported

Loggers

ModuleVersionsSupport Type
bunyan>=1Fully Supported
paperplane>=2.3.2Fully Supported
pino>=2Fully Supported
winston>=1Fully Supported