Node.js and OpenTelemetry

This page is designed for application developers who want to collect Cloud Trace data for Node.js applications by using OpenTelemetry. OpenTelemetry is a vendor-neutral instrumentation framework that you can use to collect trace and metric data. For information about instrumenting your code, see Instrumentation and observability.

  • Install the OpenTelemetry packages.
  • Configure your application to export spans to Cloud Trace.
  • Configure your platform.

For release information, see the following:

For OpenTelemetry reference content, see the following:

For the latest details about OpenTelemetry for Node.js, along with additional documentation and examples, see OpenTelemetry.

Before you begin

  1. In the navigation panel of the Google Cloud console, select APIs & Services, click Enable APIs and Services, and then enable the Cloud Trace API:

    Go to Cloud Trace API settings

  2. If API enabled is displayed, then the API is already enabled. If not, click the Enable button.

Installing, initializing, and using the client

OpenTelemetry offers the following ways to instrument your application:

  • Auto-instrumentation for Node.js applications

    When you use this approach, you configure your application to include the @opentelemetry/sdk-trace-node SDK. However, you don't have to make code changes to any of the libraries you're using.

  • Manual tracing

    When you use this approach, you modify the libraries you're using to collect trace information.

The following sections show the use case for each instrumentation.

Auto-instrumentation

The @opentelemetry/sdk-trace-node module provides auto-instrumentation for Node.js applications.

Auto-instrumentation automatically identifies the following within your application:

  • Frameworks, such as Express
  • Common protocols, such as HTTP, HTTPS, and gRPC
  • Databases, such as MySQL, MongoDB, Redis, and PostgreSQL
  • Other libraries within your application

Auto-instrumentation provides ready-to-use tracing, so you don't have to make code changes to any of the libraries you're using. The instrumentation code automatically performs the following actions:

  • Extracts a trace-context identifier from inbound requests to allow distributed tracing, if applicable.
  • Guarantees that the current trace-context is propagated while the transaction traverses an application.
  • Adds the trace-context identifier to outbound requests, allowing the distributed trace to continue to the next hop, if applicable.
  • Creates and ends spans.

The module uses plugins to automatically instrument your application to produce spans and provide end-to-end tracing with just a few lines of code.

Manual instrumentation

The manual tracing module, @opentelemetry/sdk-trace-base, provides complete control over instrumentation and span creation. It doesn't load async_hooks. It doesn't use continuation-local storage or any instrumentation plugin by default. Manual tracing has less performance overhead implications compared to the auto-instrumentation module.

Example

The following instructions show how to use the auto-instrumentation module for Compute Engine and Google Kubernetes Engine.

Compute Engine

Install the following packages:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Add the following code to your app to initialize and register the exporter:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

GKE

Add the following to the Dockerfile:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Add the following code to your app to initialize and register the exporter:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Sample application using the Express framework

OpenTelemetry Express Instrumentation lets you automatically collect trace data and export it to your backend of choice, giving you observability to distributed systems.

To use OpenTelemetry for applications that use the Express framework, complete the following steps:

  1. Install the following packages:

    npm install --save @opentelemetry/instrumentation-http
    npm install --save @opentelemetry/instrumentation-express
    
  2. Add the following code to your app, which loads all the supported plugins:

    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
    const provider = new NodeTracerProvider();
    

For a basic example, see the OpenTelemetry Express example.

Creating a custom span

You can add additional information to the system-created trace by creating a custom span.

To create a custom span, add the following to the source code:


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
provider.register();
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();
  • getTracer returns an instance of tracer, where basic is the name of the tracer or the instrumentation library. This tells OpenTelemetry who is creating spans.

  • foo is the name of the custom span.

  • invoking work is the name of the sample event. This shows how to use addEvent API.

For a basic example of creating a custom span, see the OpenTelemetry example.

Configure your platform

You can use Cloud Trace on Google Cloud and other platforms.

Running on Google Cloud

When your application is running on Google Cloud, you don't need to provide authentication credentials in the form of a service account to the client library. However, you do need to ensure that your Google Cloud platform has the Cloud Trace API access scope enabled.

For a list of supported Google Cloud environments, see Environment support.

For the following configurations, the default access-scope settings enable the Cloud Trace API:

  • App Engine flexible environment
  • App Engine standard environment

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

If you use custom access scopes, then you must ensure that Cloud Trace API access scope is enabled:

  • For information about how to configure the access scopes for your environment by using the Google Cloud console, see Configuring your Google Cloud project.

  • For gcloud users, specify access scopes using the --scopes flag and include the trace.append Cloud Trace API access scope. For example, to create a GKE cluster with only the Cloud Trace API enabled, do the following:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Running locally and elsewhere

If your application is running outside of Google Cloud, then you must provide authentication credentials in the form of a service account to the client library. The service account must contain the Cloud Trace agent role. For instructions, see Creating a service account.

Google Cloud client libraries use Application Default Credentials (ADC) to find your application's credentials.

You can provide these credentials in one of three ways:

  • Run gcloud auth application-default login

  • Place the service account in a default path for your operating system. The following lists the default paths for Windows and Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path to your service account:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

View traces

In the navigation panel of the Google Cloud console, select Trace, and then select Trace explorer:

Go to Trace explorer

Troubleshooting

For information on troubleshooting issues with Cloud Trace, go to the Troubleshooting page.