Profiling Node.js Code

This page describes setting up Stackdriver Profiler for profiling Node.js code. For Node.js, Profiler offers wall-time and heap profiling; see Profiling Concepts for more information.

You must either use version of 6.12.3 or higher of Node.js, use version 8.9.4 or higher, or use version 10.4.1 or higher.

You can use the profiling agent on Linux in the following environments:

  • Compute Engine
  • Kubernetes Engine
  • App Engine.

You can also profile Java code on non-Google Cloud Platform systems. See Profiling Outside Google Cloud Platform for more information.

Enabling the Profiler API

Before you use the profiling agent, ensure that the underlying Profiler API is enabled. You can check the status of the API and enable it if necessary by using either the Cloud SDK gcloud command-line tool or the Cloud Console:

Cloud SDK

  1. If you have not already installed the Cloud SDK on your workstation, see Google Cloud SDK.

  2. To see if the Profiler API is enabled, run the following command on your workstation:

    gcloud services list
    

    If cloudprofiler.googleapis.com appears in the output, the API is enabled.

  3. If the API is not enabled, run the following command to enable it:

    gcloud services enable cloudprofiler.googleapis.com
    

For more information, see gcloud services.

Cloud Console

Go to APIs & services

  1. Select the project you will use to access the API.
  2. Click the Enable APIs and Service button.
  3. Search for “Stackdriver”.
  4. In the search results, click through to “Profiler API”.
  5. If “API enabled” is displayed, then the API is already enabled. If not, click the Enable button.

Using Stackdriver Profiler

In all of the supported environments, you use the Profiler by installing the package, requiring the package in your app, and deploying the code.

Use npm install to install the latest version of Stackdriver Profiler:

 npm install --save @google-cloud/profiler

When modifying your code, import the Profiler after the Trace agent (@google-cloud/trace-agent), if you are also using the Trace agent. The environment-specific require statements are discussed next.

After modifying your code, deploy it as usual to your environment.

Compute Engine and Kubernetes Engine

For Compute Engine and Kubernetes Engine, the require code looks like this:

require('@google-cloud/profiler').start({
    serviceContext: {
        service: 'your-service',
        version: '1.0.0'
    }
});

In both the Compute Engine and Kubernetes Engine environments, create a serviceContext object that includes two parameters:

  • service: A name for the service being profiled
  • version: (optional) The version of the service being profiled

See Service name and version arguments for more information on these configuration options.

App Engine

For App Engine, the require code is simpler than that for Compute Engine and Kubernetes Engine:

require('@google-cloud/profiler').start();

In App Engine, the service and version parameters can be derived from the environment, so they do not have to specified. Therefore, you do not need to create a serviceContext object.

Service name and version arguments

When you load the Profiler agent, you specify a service-name argument and an optional service-version argument to configure it.

The service name lets Profiler collect profiling data for all replicas of that service. The profiler service ensures a collection rate of one profile per minute, on average, for each service name across each combination service versions and zones.

For example, if you have a service with two versions running across replicas in three zones, the profiler will create an average of 6 profiles per minute for that service.

If you use different service names for your replicas, then your service will be profiled more often than necessary, with a correspondingly higher overhead.

When selecting a service name:

  • Choose a name that clearly represents the service in your application architecture. The choice of service name is less important if you only run a single service or application. It is more important if your application runs as a set of micro-services, for example.

  • Make sure to not use any process-specific values, like a process ID, in the service-name string.

  • The service-name string must match this regular expression:

    ^[a-z]([-a-z0-9_.]{0,253}[a-z0-9])?$

A good guideline is to use a static string like imageproc-service as the service name.

The service version is optional. If you specify the service version, Profiler can aggregate profiling information from multiple instances and display it correctly. It can be used to mark different versions of your services as they get deployed. The Profiler UI lets you filter the data by service version; this way, you can compare the performance of older and newer versions of the code.

The value of the service-version argument is a free-form string, but values for this argument typically look like version numbers, for example, 1.0.0 or 2.1.2.

Agent logging

The profiling agent can report logging information. To enable logging in the profiling agent, set the logLevel option when starting the agent. The supported logLevel values are:

  • 0: disables all agent logging (default)
  • 1: enables error logging
  • 2: enables warning logging
  • 3: enables info logging
  • 4: enables debug logging

Set the logLevel value in the same object that provides the service context:

require('@google-cloud/profiler').start({
    serviceContext: { ... }
    logLevel:       3
});

Known issues

The following are known issues in the beta release of Stackdriver Profiler for Node.js:

  • The profiling agent for Node.js interferes with the normal exit of the program; it can take up to an hour for the program to terminate after all the tasks in the program have completed. Forcibly exiting the program, for example, by using ctrl-C, causes the program to terminate immediately.
  • Inline functions are not supported well. The Profiler interface may report the wrong line number or source file. Using the --noturbo-inlining option when running the profiling agent can help by providing information about the calls to builtins made by optimized functions.
  • The heap profiler of profiling agent for Node.js is known to crash, rarely, during deoptimization, as described in this bug report.
  • The profiling agent for Node.js gets an authorization error when its credentials expire during the request to create a profile, as described in this bug report. This error is logged at the warn level and will degrade profile quality if it occurs frequently, but it has no other impact.
Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Profiler