{"id":13846504,"url":"https://github.com/googleapis/cloud-profiler-nodejs","last_synced_at":"2025-05-15T17:01:21.687Z","repository":{"id":3719852,"uuid":"50680973","full_name":"googleapis/cloud-profiler-nodejs","owner":"googleapis","description":"Node.js library for Google Cloud Profiler. Continuous CPU and heap profiling to improve performance and reduce costs.","archived":false,"fork":false,"pushed_at":"2025-03-26T19:54:16.000Z","size":3275,"stargazers_count":71,"open_issues_count":30,"forks_count":29,"subscribers_count":55,"default_branch":"main","last_synced_at":"2025-03-31T21:45:14.338Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cloud.google.com/profiler/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleapis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-29T18:06:50.000Z","updated_at":"2025-03-06T14:24:22.000Z","dependencies_parsed_at":"2023-11-08T11:25:41.251Z","dependency_job_id":"526408c9-3c03-411d-8e60-bfbb26f5523a","html_url":"https://github.com/googleapis/cloud-profiler-nodejs","commit_stats":{"total_commits":624,"total_committers":39,"mean_commits":16.0,"dds":0.641025641025641,"last_synced_commit":"58633cc715f0f1ed912afc664782a60a325dad96"},"previous_names":["googlecloudplatform/cloud-profiler-nodejs"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fcloud-profiler-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fcloud-profiler-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fcloud-profiler-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleapis%2Fcloud-profiler-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleapis","download_url":"https://codeload.github.com/googleapis/cloud-profiler-nodejs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247737770,"owners_count":20987718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T18:00:35.914Z","updated_at":"2025-04-07T22:06:24.254Z","avatar_url":"https://github.com/googleapis.png","language":"TypeScript","readme":"[//]: # \"This README.md file is auto-generated, all changes to this file will be lost.\"\n[//]: # \"To regenerate it, use `python -m synthtool`.\"\n\u003cimg src=\"https://avatars2.githubusercontent.com/u/2810941?v=3\u0026s=96\" alt=\"Google Cloud Platform logo\" title=\"Google Cloud Platform\" align=\"right\" height=\"96\" width=\"96\"/\u003e\n\n# [Cloud Profiler: Node.js Client](https://github.com/googleapis/cloud-profiler-nodejs)\n\n[![release level](https://img.shields.io/badge/release%20level-stable-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages)\n[![npm version](https://img.shields.io/npm/v/@google-cloud/profiler.svg)](https://www.npmjs.org/package/@google-cloud/profiler)\n\n\n\n\nAdds support for Cloud Profiler to Node.js applications\n\n\nA comprehensive list of changes in each version may be found in\n[the CHANGELOG](https://github.com/googleapis/cloud-profiler-nodejs/blob/main/CHANGELOG.md).\n\n* [Cloud Profiler Node.js Client API Reference][client-docs]\n* [Cloud Profiler Documentation][product-docs]\n* [github.com/googleapis/cloud-profiler-nodejs](https://github.com/googleapis/cloud-profiler-nodejs)\n\nRead more about the client libraries for Cloud APIs, including the older\nGoogle APIs Client Libraries, in [Client Libraries Explained][explained].\n\n[explained]: https://cloud.google.com/apis/docs/client-libraries-explained\n\n**Table of contents:**\n\n\n* [Quickstart](#quickstart)\n  * [Before you begin](#before-you-begin)\n  * [Installing the client library](#installing-the-client-library)\n\n* [Samples](#samples)\n* [Versioning](#versioning)\n* [Contributing](#contributing)\n* [License](#license)\n\n## Quickstart\n\n### Before you begin\n\n1.  [Select or create a Cloud Platform project][projects].\n1.  [Enable the Cloud Profiler API][enable_api].\n1.  [Set up authentication][auth] so you can access the\n    API from your local workstation.\n\n### Installing the client library\n\n```bash\nnpm install @google-cloud/profiler\n```\n\n\n### Prerequisites\n\n1. Your application will need to be using Node.js version between 14 and 20.\n\n1. `@google-cloud/profiler` depends on the\n[`pprof`](https://www.npmjs.com/package/pprof) module, a module with a native\ncomponent that is used to collect profiles with v8's CPU and Heap profilers.\nYou may need to install additional dependencies to build the `pprof` module.\n    * For Linux: `pprof` has prebuilt binaries available for Linux and Alpine\n    Linux for Node 14 and 16. No additional dependencies are required.\n    * For other environments: when using `@google-cloud/profiler` on environments\n    that `pprof` does not have prebuilt binaries for, the module\n    [`node-gyp`](https://www.npmjs.com/package/node-gyp) will be used to\n    build binaries. See `node-gyp`'s\n    [documentation](https://github.com/nodejs/node-gyp#installation)\n    for information on dependencies required to build binaries with `node-gyp`.\n\n1. You will need a project in the [Google Developers Console][cloud-console].\nYour application can run anywhere, but the profiler data is associated with a\nparticular project.\n\n1. You will need to enable the Cloud Profiler API for your project.\n\n### Basic Set-up\n\n1. Install `@google-cloud/profiler` with [`npm`](https://www.npmjs.com) or add\nto your [`package.json`](https://docs.npmjs.com/files/package.json#dependencies).\n\n    ```sh\n    # Install through npm while saving to the local 'package.json'\n    npm install --save @google-cloud/profiler\n    ```\n\n2. Include and start the profiler at the beginning of your application:\n\n    ```js\n    require('@google-cloud/profiler').start().catch((err) =\u003e {\n    console.log(`Failed to start profiler: ${err}`);\n    });\n    ```\n\n    Some environments require a configuration to be passed to the `start()`\n    function. For more details on this, see instructions for running\n    [outside of Google Cloud Platform](#running-elsewhere), on\n    [App Engine flexible environment](#running-on-app-engine-flexible-environment),\n    on [Google Compute Engine](#running-on-google-compute-engine),\n    and on [Google Container Engine](#running-on-google-container-engine).\n\n3. If you are running your application locally, or on a machine where you are\nusing the [Google Cloud SDK][gcloud-sdk], make sure to log in with the\napplication default credentials:\n\n    ```sh\n    gcloud beta auth application-default login\n    ```\n\n    Alternatively, you can set `GOOGLE_APPLICATION_CREDENTIALS`. For more\n    details on this, see [Running elsewhere](#running-elsewhere)\n\n### Configuration\n\nSee [the default configuration](https://github.com/googleapis/cloud-profiler-nodejs/blob/master/src/config.ts) for a list of possible\nconfiguration options. These options can be passed to the agent through the\nobject argument to the start command shown below:\n\n```js\nawait require('@google-cloud/profiler').start({disableTime: true});\n```\n\nAlternatively, you can provide the configuration through a config file. This\ncan be useful if you want to load our module using `--require` on the command\nline (which requires and starts the agent) instead of editing your main script.\nThe `GCLOUD_PROFILER_CONFIG` environment variable should point to your\nconfiguration file.\n\n```bash\nexport GCLOUD_PROFILER_CONFIG=./path/to/your/profiler/configuration.js\n```\n\n#### Changing log level\n\nThe profiler writes log statements to the console log for diagnostic purposes.\nBy default, the log level is set to warn. You can adjust this by setting\n`logLevel` in the config. Setting `logLevel` to 0 will disable logging,\n1 sets log level to error, 2 sets it to warn (default), 3 sets it to info,\nand 4 sets it to debug.\n\nSo, for example, to start the profiler with the log level at debug, you would\ndo this:\n\n```js\nawait require('@google-cloud/profiler').start({logLevel: 4});\n```\n\n#### Disabling heap or time profile collection\n\nBy default, the profiler collects both heap profiles, which show memory\nallocations, and time profiles, which capture how much wall-clock time is spent\nin different locations of the code. Using the configuration, it is possible to\ndisable the collection of either type of profile.\n\nTo disable time profile collection, set `disableTime` to true:\n\n```js\nawait require('@google-cloud/profiler').start({disableTime: true});\n```\n\nTo disable heap profile collection, set `disableHeap` to true:\n\n```js\nawait require('@google-cloud/profiler').start({disableHeap: true});\n```\n\n### Running on Google Cloud Platform\n\nThere are three different services that can host Node.js applications within\nGoogle Cloud Platform: Google App Engine flexible environment, Google Compute\nEngine, and Google Container Engine. After installing `@google-cloud/profiler`\nin your project and ensuring that the environment you are using uses a\nsupported version of Node.js, follow the service-specific instructions to\nenable the profiler.\n\n#### Running on App Engine flexible environment\n\nTo enable the profiling agent for a Node.js program running in the App Engine\nflexible environment, import the agent at the top of your application’s main\nscript or entry point by including the following code snippet:\n\n```js\nrequire('@google-cloud/profiler').start();\n```\n\nYou can specify which version of Node.js you're using by adding a snippet like\nthe following to your `package.json`:\n\n```json\n\"engines\": {\n    \"node\": \"\u003e=14.0.0\"\n}\n```\nThe above snippet will ensure that you're using 14.0.0 or greater.\n\nDeploy your application to App Engine Flexible environment as usual.\n\n#### Running on Google Compute Engine\n\nTo enable the profiling agent for a Node.js program running in the Google\nCompute Engine environment, import the agent at the top of your application’s\nmain script or entry point by including the following code snippet:\n\n```js\nrequire('@google-cloud/profiler').start({\nserviceContext: {\n    service: 'your-service',\n    version: '1.0.0'\n}\n});\n```\n\n#### Running on Google Container Engine\n\nTo enable the profiling agent for a Node.js program running in the Google\nContainer Engine environment, import the agent at the top of your application’s\nmain script or entry point by including the following code snippet:\n\n```js\nrequire('@google-cloud/profiler').start({\nserviceContext: {\n    service: 'your-service',\n    version: '1.0.0'\n}\n});\n```\n\n#### Running on Istio\n\nOn Istio, the GCP Metadata server may not be available for a few seconds after\nyour application has started. When this occurs, the profiling agent may fail\nto start because it cannot initialize required fields. One can retry when\nstarting the profiler with the following snippet.\n\n```js\nconst profiler = require('@google-cloud/profiler');\nasync function startProfiler() {\nfor (let i = 0; i \u003c 3; i++) {\n    try {\n    await profiler.start({\n        serviceContext: {\n        service: 'your-service',\n        version: '1.0.0',\n        },\n    });\n    } catch(e) {\n    console.log(`Failed to start profiler: ${e}`);\n    }\n\n    // Wait for 1 second before trying again.\n    await new Promise(r =\u003e setTimeout(r, 1000));\n}\n}\nstartProfiler();\n\n```\n\n\n### Running elsewhere\n\nYou can still use `@google-cloud/profiler` if your application is running\noutside of Google Cloud Platform, for example, running locally, on-premise, or\non another cloud provider.\n\n1. You will need to specify your project id and the service you want the\ncollected profiles to be associated with, and (optionally) the version of\nthe service when starting the profiler:\n\n```js\n    await require('@google-cloud/profiler').start({\n    projectId: 'project-id',\n    serviceContext: {\n        service: 'your-service',\n        version: '1.0.0'\n    }\n    });\n```\n2. You will need to provide credential for your application.\n\n* If you are running your application on a development machine or test\nenvironment where you are using the [`gcloud` command line tools][gcloud-sdk],\nand are logged using `gcloud beta auth application-default login`, you\nalready have sufficient credentials, and a service account key is not\nrequired.\n\n* You can provide credentials via\n[Application Default Credentials][app-default-credentials]. This is the\nrecommended method.\n        1. [Create a new JSON service account key][service-account].\n        2. Copy the key somewhere your application can access it. Be sure not\n        to expose the key publicly.\n        3.  Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to\n        the full path to the key. The profiler will automatically look for\n        this environment variable.\n\n*  You may set the `keyFilename` or `credentials` configuration field to the\nfull path or contents to the key file, respectively. Setting either of these\nfields will override either setting `GOOGLE_APPLICATION_CREDENTIALS` or\nlogging in using `gcloud`.\n\n    This is how you would set `keyFilename`:\n    ```js\n    await require('@google-cloud/profiler').start({\n        projectId: 'project-id',\n        serviceContext: {\n        service: 'your-service',\n        version: '1.0.0'\n        },\n        keyFilename: '/path/to/keyfile'\n    });\n    ```\n\n    This is how you would set  `credentials`:\n    ```js\n    await require('@google-cloud/profiler').start({\n        projectId: 'project-id',\n        serviceContext: {\n        service: 'your-service',\n        version: '1.0.0'\n        },\n        credentials: {\n        client_email: 'email',\n        private_key: 'private_key'\n        }\n    });\n    ```\n\n\n## Samples\n\nSamples are in the [`samples/`](https://github.com/googleapis/cloud-profiler-nodejs/tree/main/samples) directory. Each sample's `README.md` has instructions for running its sample.\n\n| Sample                      | Source Code                       | Try it |\n| --------------------------- | --------------------------------- | ------ |\n| App | [source code](https://github.com/googleapis/cloud-profiler-nodejs/blob/main/samples/app.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/cloud-profiler-nodejs\u0026page=editor\u0026open_in_editor=samples/app.js,samples/README.md) |\n| Snippets | [source code](https://github.com/googleapis/cloud-profiler-nodejs/blob/main/samples/snippets.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/cloud-profiler-nodejs\u0026page=editor\u0026open_in_editor=samples/snippets.js,samples/README.md) |\n\n\n\nThe [Cloud Profiler Node.js Client API Reference][client-docs] documentation\nalso contains samples.\n\n## Supported Node.js Versions\n\nOur client libraries follow the [Node.js release schedule](https://github.com/nodejs/release#release-schedule).\nLibraries are compatible with all current _active_ and _maintenance_ versions of\nNode.js.\nIf you are using an end-of-life version of Node.js, we recommend that you update\nas soon as possible to an actively supported LTS version.\n\nGoogle's client libraries support legacy versions of Node.js runtimes on a\nbest-efforts basis with the following warnings:\n\n* Legacy versions are not tested in continuous integration.\n* Some security patches and features cannot be backported.\n* Dependencies cannot be kept up-to-date.\n\nClient libraries targeting some end-of-life versions of Node.js are available, and\ncan be installed through npm [dist-tags](https://docs.npmjs.com/cli/dist-tag).\nThe dist-tags follow the naming convention `legacy-(version)`.\nFor example, `npm install @google-cloud/profiler@legacy-8` installs client libraries\nfor versions compatible with Node.js 8.\n\n## Versioning\n\nThis library follows [Semantic Versioning](http://semver.org/).\n\n\n\nThis library is considered to be **stable**. The code surface will not change in backwards-incompatible ways\nunless absolutely necessary (e.g. because of critical security issues) or with\nan extensive deprecation period. Issues and requests against **stable** libraries\nare addressed with the highest priority.\n\n\n\n\n\n\nMore Information: [Google Cloud Platform Launch Stages][launch_stages]\n\n[launch_stages]: https://cloud.google.com/terms/launch-stages\n\n## Contributing\n\nContributions welcome! See the [Contributing Guide](https://github.com/googleapis/cloud-profiler-nodejs/blob/main/CONTRIBUTING.md).\n\nPlease note that this `README.md`, the `samples/README.md`,\nand a variety of configuration files in this repository (including `.nycrc` and `tsconfig.json`)\nare generated from a central template. To edit one of these files, make an edit\nto its templates in\n[directory](https://github.com/googleapis/synthtool).\n\n## License\n\nApache Version 2.0\n\nSee [LICENSE](https://github.com/googleapis/cloud-profiler-nodejs/blob/main/LICENSE)\n\n[client-docs]: https://cloud.google.com/nodejs/docs/reference/profiler/latest\n[product-docs]: https://cloud.google.com/profiler/docs\n[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png\n[projects]: https://console.cloud.google.com/project\n[billing]: https://support.google.com/cloud/answer/6293499#enable-billing\n[enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=cloudprofiler.googleapis.com\n[auth]: https://cloud.google.com/docs/authentication/external/set-up-adc-local\n","funding_links":[],"categories":["Google Cloud Profiler"],"sub_categories":["Client libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleapis%2Fcloud-profiler-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleapis%2Fcloud-profiler-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleapis%2Fcloud-profiler-nodejs/lists"}