Setting Up Stackdriver Trace for Node.js

Stackdriver Trace can be enabled for Node.js applications using the Stackdriver Trace agent for Node.js.

Installing the agent

  1. Before installing the agent, make sure you've prepared your environment for Node.js development.

  2. The easiest way to install the Stackdriver Trace agent for Node.js is with npm:

    npm install --save @google-cloud/trace-agent

  3. Import the agent at the top of your application's main script or entry point before any other code:

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

For more information or to report issues with the Stackdriver Trace agent, see the agent's source code repository.

Configuring the agent

You can customize the behavior of the Stackdriver Trace agent. See the agent configuration on GitHub for a list of possible configuration options. These options can be passed in the options object passed to the agent's start method.

Running on Google Cloud Platform

The Stackdriver Trace agent should work without the need to manually provide authentication credentials for instances running on Google Cloud Platform, as long as the Stackdriver Trace API access scope is enabled on that instance.

App Engine

On Google App Engine, the Stackdriver Trace API access scope is enabled by default, and the Stackdriver Trace agent can be used without needing to provide credentials or a project ID.

Container Engine

On Google Container Engine, you need to explicitly add the trace.append OAuth scope when creating the cluster:

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

Compute Engine

For Google Compute Engine instances, you need to explicitly enable the trace.append Stackdriver Trace API access scope for each instance. When creating a new instance through the Google Cloud Platform Console, you can do this under Identity and API access: Use the Compute Engine default service account and select "Allow full access to all Cloud APIs" under Access scopes.

To use something other than the Compute Engine default service account see the docs for Creating and Enabling Service Accounts for Instances and the Running elsewhere section below. The important thing is that the service account you use has the Cloud Trace Agent role.

Running locally and elsewhere

If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Trace, provided that you supply a project ID and credentials to the Stackdriver Trace agent, as described in the following sections.

Project ID

Provide a project ID to the Stackdriver Trace agent by setting the projectId value in the options object passed to the agent's start method, or set the GCLOUD_PROJECT environment variable:

Linux or Mac OS X

export GCLOUD_PROJECT=your-project-id

Windows

set GCLOUD_PROJECT=your-project-id

Powershell:

$env:GCLOUD_PROJECT="your-project-id"

Credentials

Google Cloud Platform client libraries use a strategy called Application Default Credentials (ADC) to find your application's credentials. You can provide credentials to the Stackdriver Trace agent by setting the keyFilename value in the options object passed to the agent's start method, or you can set the GOOGLE_APPLICATION_CREDENTIALS environment variable. For more information, see Providing credentials to your application.

Example

require('@google-cloud/trace-agent').start({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json'
});

Sample application

if (process.env.NODE_ENV === 'production') {
  require('@google-cloud/trace-agent').start();
}

const express = require('express');
const got = require('got');

const app = express();
const DISCOVERY_URL = 'https://www.googleapis.com/discovery/v1/apis';

// This incoming HTTP request should be captured by Trace
app.get('/', (req, res) => {
  // This outgoing HTTP request should be captured by Trace
  got(DISCOVERY_URL, { json: true })
    .then((response) => {
      const names = response.body.items.map((item) => item.name);

      res
        .status(200)
        .send(names.join('\n'))
        .end();
    })
    .catch((err) => {
      console.error(err);
      res
        .status(500)
        .end();
    });
});

// Start the server
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

Viewing the traces

After deployment, you can view the traces in the Cloud Platform Console Trace Viewer.

Go to the Trace Viewer page

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Trace