You can enable Cloud Trace for Node.js applications by using the Cloud Trace library for Node.js.
Installing the client library
Before installing the Cloud Trace library for Node.js, make sure you've prepared your environment for Node.js development.
To install the Cloud Trace library for Node.js, use npm:
npm install --save @google-cloud/trace-agent
Import the Cloud Trace library for Node.js at the top of your application's main script or entry point before any other code:
For more information or to report issues with the Cloud Trace library for Node.js, see the
agent's cloud-trace-nodejs
GitHub repository.
Configuring the client library
You can customize the behavior of the Cloud Trace library for Node.js. See the
library's configuration on GitHub for a list
of configuration options that you can pass to the library's start
method
by using an options
object.
The following example demonstrates specifying the Google Cloud project ID and setting the path to your credential file. These two statements are optional when you're running on Google Cloud:
If you're running on Google Cloud infrastructure, then
you don't need to set projectId
to your Google Cloud
project ID. If you don't set this field, the client library for Node.js
automatically gathers this data from a Google Cloud metadata server.
If you aren't running on Google Cloud infrastructure, then you must supply your Google Cloud project ID to your application.
Regardless of your infrastructure, for Node.js,
when you don't explicitly set the Google Cloud project ID,
the cloud-trace-nodejs
library automatically determines if
the environment variable GCLOUD_PROJECT
is set, and if so, the
library uses the value of GCLOUD_PROJECT
as your Google Cloud
project ID. For more information on the discovery file, go to
cloud-trace-nodejs/src/index
.
To set the environment variable, do the following:
Linux or macOS
export GCLOUD_PROJECT=your-project-id
Windows
set GCLOUD_PROJECT=your-project-id
PowerShell:
$env:GCLOUD_PROJECT="your-project-id"
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 thetrace.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"
Sample application
View traces
In the navigation panel of the Google Cloud console, select Trace, and then select Trace explorer:
Troubleshooting
For information on troubleshooting issues with Cloud Trace, go to the Troubleshooting page.