Node.js installation instructions

Get your Node.js services auto-instrumented with Helios by following the installation instructions provided below.

Installing Helios in your Node.js microservice

Navigate to your project's root directory, and install the latest Helios OpenTelemetry SDK:

npm install --save helios-opentelemetry-sdk

Configuring Helios through environment variables

Define the following environment variables when running your service:

export NODE_OPTIONS="--require helios-opentelemetry-sdk" # TODO: Variable should be set before process starts.
export HS_TOKEN=<API_TOKEN> # TODO: Replace value with API token from Helios.
export HS_SERVICE_NAME=<SERVICE_NAME> # TODO: Replace value with service name.
export HS_ENVIRONMENT="<ENVIRONMENT_NAME>" # TODO: Replace value with service environment.

🚧

It's common for Node.js developers to use .env files to define environment variables for their applications and local environment. Please note, that since the instrumentation must be loaded before the process starts, placing the above environment variables in the .env file will not work and should be declared before starting the application.

Configuring Helios in the code

Alternatively, it is possible to configure Helios in the code itself.
In your project's main index.js file, paste the following code snippet before all other imports:

const { initialize } = require('helios-opentelemetry-sdk');

initialize({
    apiToken: <API_TOKEN>,       // TODO: Insert API token from Helios.
    serviceName: <SERVICE_NAME>, // TODO: Insert service name.
    enable: true,                // Defaults to false if omitted.
    environment: <ENVIRONMENT>,  // Defaults to process.env.NODE_ENV if omitted.
    commitHash: <COMMIT_HASH>,   // Defaults to process.env.COMMIT_HASH if omitted.
});

import { initialize } from 'helios-opentelemetry-sdk';

initialize({
    apiToken: <API_TOKEN>,       // TODO: Insert API token from Helios.
    serviceName: <SERVICE_NAME>, // TODO: Insert service name.
    enable: true,                // Defaults to false if omitted.
    environment: <ENVIRONMENT>,  // Defaults to process.env.NODE_ENV if omitted.
    commitHash: <COMMIT_HASH>,   // Defaults to process.env.COMMIT_HASH if omitted.
});

Deploying Helios in a Kubernetes cluster

It's possible to install and update the Helios OpenTelemetry SDK in a centralized manner when running multiple containers, via deployment with Kubernetes operator. Please refer to the Deploying the Helios SDK in a Kubernetes (K8s) cluster doc.

See more configuration options here.

👍

All set

After setup is complete and once the service is up and running, it will show up in the Helios application.

Troubleshooting tips

Installing the Helios OpenTelemetry SDK is usually a simple process; nonetheless, we've aggregated here some useful tips based on common issues we've encountered in the field so that you can complete the installation quickly.

Ensure imports are in order (and that Helios is first)

Some JS compilers (like Babel, for example) alter the order of required / imported external modules, which affects loading order and can break instrumentation.

To circumvent the issue, when configuring Helios in code, put the the initialization snippet into a separate file, and import it as the first module in index.js.

Verify Helios appears in your package.json's dependencies

If you encounter this error: Error: Cannot find module 'helios-opentelemetry-sdk', make sure our SDK (helios-opentelemetry-sdk) truly appears in the dependencies of your application's package.json, preferably in the latest version.

Turn debug mode on

The Helios SDK support a debug mode through the environment variable HS_DEBUG.
Once debug mode is enabled, search for the Helios initialization prints. This will help verify (or refute) the successful installation of Helios in your microservice.