Adds support for Cloud Profiler to Node.js applications
A comprehensive list of changes in each version may be found in the CHANGELOG.
- Cloud Profiler Node.js Client API Referenceclient-docs
- Cloud Profiler Documentationproduct-docs
- github.com/googleapis/cloud-profiler-nodejs
Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in Client Libraries Explainedexplained.
Table of contents:
Before you begin Installing the client library
Quickstart
Before you begin
- Select or create a Cloud Platform projectprojects.
- Enable the Cloud Profiler APIenableapi.
- Set up authentication with a service accountauth so you can access the
API from your local workstation.
Installing the client library
npm install @google-cloud/profiler
Prerequisites
- Your application will need to be using Node.js version between 14 and 20.
@google-cloud/profiler
depends on the
pprof
module, a module with a native
component that is used to collect profiles with v8's CPU and Heap profilers.
You may need to install additional dependencies to build the pprof
module.* For Linux: `pprof` has prebuilt binaries available for Linux and Alpine
Linux for Node 14 and 16. No additional dependencies are required.
* For other environments: when using `@google-cloud/profiler` on environments
that `pprof` does not have prebuilt binaries for, the module
[`node-gyp`](https://www.npmjs.com/package/node-gyp) will be used to
build binaries. See `node-gyp`'s
[documentation](https://github.com/nodejs/node-gyp#installation)
for information on dependencies required to build binaries with `node-gyp`.
- You will need a project in the Google Developers Consolecloud-console.
- You will need to enable the Cloud Profiler API for your project.
Basic Set-up
- Install
@google-cloud/profiler
withnpm
or add
package.json
.```sh
# Install through npm while saving to the local 'package.json'
npm install --save @google-cloud/profiler
```
- Include and start the profiler at the beginning of your application:
```js
require('@google-cloud/profiler').start().catch((err) => {
console.log(`Failed to start profiler: ${err}`);
});
```
Some environments require a configuration to be passed to the `start()`
function. For more details on this, see instructions for running
[outside of Google Cloud Platform](#running-elsewhere), on
[App Engine flexible environment](#running-on-app-engine-flexible-environment),
on [Google Compute Engine](#running-on-google-compute-engine),
and on [Google Container Engine](#running-on-google-container-engine).
- If you are running your application locally, or on a machine where you are
```sh
gcloud beta auth application-default login
```
Alternatively, you can set `GOOGLE_APPLICATION_CREDENTIALS`. For more
details on this, see [Running elsewhere](#running-elsewhere)
Configuration
See the default configuration for a list of possible configuration options. These options can be passed to the agent through the object argument to the start command shown below:await require('@google-cloud/profiler').start({disableTime: true});
Alternatively, you can provide the configuration through a config file. This can be useful if you want to load our module using
--require
on the command
line (which requires and starts the agent) instead of editing your main script.
The GCLOUD_PROFILER_CONFIG
environment variable should point to your
configuration file.export GCLOUD_PROFILER_CONFIG=./path/to/your/profiler/configuration.js
Changing log level
The profiler writes log statements to the console log for diagnostic purposes. By default, the log level is set to warn. You can adjust this by settinglogLevel
in the config. Setting logLevel
to 0 will disable logging,
1 sets log level to error, 2 sets it to warn (default), 3 sets it to info,
and 4 sets it to debug.So, for example, to start the profiler with the log level at debug, you would do this:
await require('@google-cloud/profiler').start({logLevel: 4});
Disabling heap or time profile collection
By default, the profiler collects both heap profiles, which show memory allocations, and time profiles, which capture how much wall-clock time is spent in different locations of the code. Using the configuration, it is possible to disable the collection of either type of profile.To disable time profile collection, set
disableTime
to true:await require('@google-cloud/profiler').start({disableTime: true});
To disable heap profile collection, set
disableHeap
to true:await require('@google-cloud/profiler').start({disableHeap: true});
Running on Google Cloud Platform
There are three different services that can host Node.js applications within Google Cloud Platform: Google App Engine flexible environment, Google Compute Engine, and Google Container Engine. After installing@google-cloud/profiler
in your project and ensuring that the environment you are using uses a
supported version of Node.js, follow the service-specific instructions to
enable the profiler.Running on App Engine flexible environment
To enable the profiling agent for a Node.js program running in the App Engine flexible environment, import the agent at the top of your application’s main script or entry point by including the following code snippet:require('@google-cloud/profiler').start();
You can specify which version of Node.js you're using by adding a snippet like the following to your
package.json
:"engines": {
"node": ">=14.0.0"
}
The above snippet will ensure that you're using 14.0.0 or greater.Deploy your application to App Engine Flexible environment as usual.
Running on Google Compute Engine
To enable the profiling agent for a Node.js program running in the Google Compute Engine environment, import the agent at the top of your application’s main script or entry point by including the following code snippet:require('@google-cloud/profiler').start({
serviceContext: {
service: 'your-service',
version: '1.0.0'
}
});
Running on Google Container Engine
To enable the profiling agent for a Node.js program running in the Google Container Engine environment, import the agent at the top of your application’s main script or entry point by including the following code snippet:require('@google-cloud/profiler').start({
serviceContext: {
service: 'your-service',
version: '1.0.0'
}
});
Running on Istio
On Istio, the GCP Metadata server may not be available for a few seconds after your application has started. When this occurs, the profiling agent may fail to start because it cannot initialize required fields. One can retry when starting the profiler with the following snippet.const profiler = require('@google-cloud/profiler');
async function startProfiler() {
for (let i = 0; i < 3; i++) {
try {
await profiler.start({
serviceContext: {
service: 'your-service',
version: '1.0.0',
},
});
} catch(e) {
console.log(`Failed to start profiler: ${e}`);
}
// Wait for 1 second before trying again.
await new Promise(r => setTimeout(r, 1000));
}
}
startProfiler();
Running elsewhere
You can still use@google-cloud/profiler
if your application is running
outside of Google Cloud Platform, for example, running locally, on-premise, or
on another cloud provider.- You will need to specify your project id and the service you want the
await require('@google-cloud/profiler').start({
projectId: 'project-id',
serviceContext: {
service: 'your-service',
version: '1.0.0'
}
});
- You will need to provide credential for your application.
- If you are running your application on a development machine or test
gcloud
command line toolsgcloud-sdk,
and are logged using gcloud beta auth application-default login
, you
already have sufficient credentials, and a service account key is not
required.- You can provide credentials via
1. [Create a new JSON service account key][service-account].
2. Copy the key somewhere your application can access it. Be sure not
to expose the key publicly.
3. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to
the full path to the key. The profiler will automatically look for
this environment variable.
- You may set the
keyFilename
orcredentials
configuration field to the
GOOGLE_APPLICATION_CREDENTIALS
or
logging in using gcloud
.This is how you would set `keyFilename`:
```js
await require('@google-cloud/profiler').start({
projectId: 'project-id',
serviceContext: {
service: 'your-service',
version: '1.0.0'
},
keyFilename: '/path/to/keyfile'
});
```
This is how you would set `credentials`:
```js
await require('@google-cloud/profiler').start({
projectId: 'project-id',
serviceContext: {
service: 'your-service',
version: '1.0.0'
},
credentials: {
client_email: 'email',
private_key: 'private_key'
}
});
```
Samples
Samples are in thesamples/
directory. Each sample's README.md
has instructions for running its sample.| Sample | Source Code | Try it | | --------------------------- | --------------------------------- | ------ | | App | source code | !Open in Cloud Shellshellimg | | Snippets | source code | !Open in Cloud Shellshellimg |
The Cloud Profiler Node.js Client API Referenceclient-docs documentation also contains samples.
Supported Node.js Versions
Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js. If you are using an end-of-life version of Node.js, we recommend that you update as soon as possible to an actively supported LTS version.Google's client libraries support legacy versions of Node.js runtimes on a best-efforts basis with the following warnings:
- Legacy versions are not tested in continuous integration.
- Some security patches and features cannot be backported.
- Dependencies cannot be kept up-to-date.
Client libraries targeting some end-of-life versions of Node.js are available, and can be installed through npm dist-tags. The dist-tags follow the naming convention
legacy-(version)
.
For example, npm install @google-cloud/profiler@legacy-8
installs client libraries
for versions compatible with Node.js 8.Versioning
This library follows Semantic Versioning.This library is considered to be stable. The code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against stable libraries are addressed with the highest priority.
More Information: Google Cloud Platform Launch Stageslaunchstages
Contributing
Contributions welcome! See the Contributing Guide.Please note that this
README.md
, the samples/README.md
,
and a variety of configuration files in this repository (including .nycrc
and tsconfig.json
)
are generated from a central template. To edit one of these files, make an edit
to its templates in
directory.License
Apache Version 2.0See LICENSE