1 | [//]: # "This README.md file is auto-generated, all changes to this file will be lost."
|
2 | [//]: # "To regenerate it, use `python -m synthtool`."
|
3 | <img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
|
4 |
|
5 | # [Stackdriver Profiler: Node.js Client](https://github.com/googleapis/cloud-profiler-nodejs)
|
6 |
|
7 | [![release level](https://img.shields.io/badge/release%20level-general%20availability%20%28GA%29-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages)
|
8 | [![npm version](https://img.shields.io/npm/v/@google-cloud/profiler.svg)](https://www.npmjs.org/package/@google-cloud/profiler)
|
9 | [![codecov](https://img.shields.io/codecov/c/github/googleapis/cloud-profiler-nodejs/master.svg?style=flat)](https://codecov.io/gh/googleapis/cloud-profiler-nodejs)
|
10 |
|
11 |
|
12 |
|
13 |
|
14 | Adds support for Stackdriver Profiler to Node.js applications
|
15 |
|
16 |
|
17 | * [Stackdriver Profiler Node.js Client API Reference][client-docs]
|
18 | * [Stackdriver Profiler Documentation][product-docs]
|
19 | * [github.com/googleapis/cloud-profiler-nodejs](https://github.com/googleapis/cloud-profiler-nodejs)
|
20 |
|
21 | Read more about the client libraries for Cloud APIs, including the older
|
22 | Google APIs Client Libraries, in [Client Libraries Explained][explained].
|
23 |
|
24 | [explained]: https://cloud.google.com/apis/docs/client-libraries-explained
|
25 |
|
26 | **Table of contents:**
|
27 |
|
28 |
|
29 | * [Quickstart](#quickstart)
|
30 | * [Before you begin](#before-you-begin)
|
31 | * [Installing the client library](#installing-the-client-library)
|
32 |
|
33 | * [Samples](#samples)
|
34 | * [Versioning](#versioning)
|
35 | * [Contributing](#contributing)
|
36 | * [License](#license)
|
37 |
|
38 | ## Quickstart
|
39 |
|
40 | ### Before you begin
|
41 |
|
42 | 1. [Select or create a Cloud Platform project][projects].
|
43 | 1. [Enable the Stackdriver Profiler API][enable_api].
|
44 | 1. [Set up authentication with a service account][auth] so you can access the
|
45 | API from your local workstation.
|
46 |
|
47 | ### Installing the client library
|
48 |
|
49 | ```bash
|
50 | npm install @google-cloud/profiler
|
51 | ```
|
52 |
|
53 |
|
54 | ### Prerequisites
|
55 |
|
56 | 1. Your application will need to be using Node.js 10.4.1 or greater or Node.js
|
57 | 12. The profiler will not be enabled when using earlier versions of 10 because
|
58 | versions of Node.js 10 prior to 10.4.1 are impacted by
|
59 | [this](https://bugs.chromium.org/p/chromium/issues/detail?id=847863) issue,
|
60 | which can cause garbage collection to take several minutes when heap profiling
|
61 | is enabled.
|
62 |
|
63 | 1. `@google-cloud/profiler` depends on the
|
64 | [`pprof`](https://www.npmjs.com/package/pprof) module, a module with a native
|
65 | component that is used to collect profiles with v8's CPU and Heap profilers.
|
66 | You may need to install additional dependencies to build the `pprof` module.
|
67 | * For Linux: `pprof` has prebuilt binaries available for Linux and Alpine
|
68 | Linux for Node 10 and 12. No additional dependencies are required.
|
69 | * For other environments: when using `@google-cloud/profiler` on environments
|
70 | that `pprof` does not have prebuilt binaries for, the module
|
71 | [`node-gyp`](https://www.npmjs.com/package/node-gyp) will be used to
|
72 | build binaries. See `node-gyp`'s
|
73 | [documentation](https://github.com/nodejs/node-gyp#installation)
|
74 | for information on dependencies required to build binaries with `node-gyp`.
|
75 |
|
76 | 1. You will need a project in the [Google Developers Console][cloud-console].
|
77 | Your application can run anywhere, but the profiler data is associated with a
|
78 | particular project.
|
79 |
|
80 | 1. You will need to enable the Stackdriver Profiler API for your project.
|
81 |
|
82 | ### Basic Set-up
|
83 |
|
84 | 1. Install `@google-cloud/profiler` with [`npm`](https://www.npmjs.com) or add
|
85 | to your [`package.json`](https://docs.npmjs.com/files/package.json#dependencies).
|
86 |
|
87 | ```sh
|
88 | # Install through npm while saving to the local 'package.json'
|
89 | npm install --save @google-cloud/profiler
|
90 | ```
|
91 |
|
92 | 2. Include and start the profiler at the beginning of your application:
|
93 |
|
94 | ```js
|
95 | require('@google-cloud/profiler').start().catch((err) => {
|
96 | console.log(`Failed to start profiler: ${err}`);
|
97 | });
|
98 | ```
|
99 |
|
100 | Some environments require a configuration to be passed to the `start()`
|
101 | function. For more details on this, see instructions for running
|
102 | [outside of Google Cloud Platform](#running-elsewhere), on
|
103 | [App Engine flexible environment](#running-on-app-engine-flexible-environment),
|
104 | on [Google Compute Engine](#running-on-google-compute-engine),
|
105 | and on [Google Container Engine](#running-on-google-container-engine).
|
106 |
|
107 | 3. If you are running your application locally, or on a machine where you are
|
108 | using the [Google Cloud SDK][gcloud-sdk], make sure to log in with the
|
109 | application default credentials:
|
110 |
|
111 | ```sh
|
112 | gcloud beta auth application-default login
|
113 | ```
|
114 |
|
115 | Alternatively, you can set `GOOGLE_APPLICATION_CREDENTIALS`. For more
|
116 | details on this, see [Running elsewhere](#running-elsewhere)
|
117 |
|
118 | ### Configuration
|
119 |
|
120 | See [the default configuration](https://github.com/googleapis/cloud-profiler-nodejs/blob/master/src/config.ts) for a list of possible
|
121 | configuration options. These options can be passed to the agent through the
|
122 | object argument to the start command shown below:
|
123 |
|
124 | ```js
|
125 | await require('@google-cloud/profiler').start({disableTime: true});
|
126 | ```
|
127 |
|
128 | Alternatively, you can provide the configuration through a config file. This
|
129 | can be useful if you want to load our module using `--require` on the command
|
130 | line (which requires and starts the agent) instead of editing your main script.
|
131 | The `GCLOUD_PROFILER_CONFIG` environment variable should point to your
|
132 | configuration file.
|
133 |
|
134 | ```bash
|
135 | export GCLOUD_PROFILER_CONFIG=./path/to/your/profiler/configuration.js
|
136 | ```
|
137 |
|
138 | #### Changing log level
|
139 |
|
140 | The profiler writes log statements to the console log for diagnostic purposes.
|
141 | By default, the log level is set to warn. You can adjust this by setting
|
142 | `logLevel` in the config. Setting `logLevel` to 0 will disable logging,
|
143 | 1 sets log level to error, 2 sets it to warn (default), 3 sets it to info,
|
144 | and 4 sets it to debug.
|
145 |
|
146 | So, for example, to start the profiler with the log level at debug, you would
|
147 | do this:
|
148 |
|
149 | ```js
|
150 | await require('@google-cloud/profiler').start({logLevel: 4});
|
151 | ```
|
152 |
|
153 | #### Disabling heap or time profile collection
|
154 |
|
155 | By default, the profiler collects both heap profiles, which show memory
|
156 | allocations, and time profiles, which capture how much wall-clock time is spent
|
157 | in different locations of the code. Using the configuration, it is possible to
|
158 | disable the collection of either type of profile.
|
159 |
|
160 | To disable time profile collection, set `disableTime` to true:
|
161 |
|
162 | ```js
|
163 | await require('@google-cloud/profiler').start({disableTime: true});
|
164 | ```
|
165 |
|
166 | To disable heap profile collection, set `disableHeap` to true:
|
167 |
|
168 | ```js
|
169 | await require('@google-cloud/profiler').start({disableHeap: true});
|
170 | ```
|
171 |
|
172 | ### Running on Google Cloud Platform
|
173 |
|
174 | There are three different services that can host Node.js applications within
|
175 | Google Cloud Platform: Google App Engine flexible environment, Google Compute
|
176 | Engine, and Google Container Engine. After installing `@google-cloud/profiler`
|
177 | in your project and ensuring that the environment you are using uses a
|
178 | supported version of Node.js, follow the service-specific instructions to
|
179 | enable the profiler.
|
180 |
|
181 | #### Running on App Engine flexible environment
|
182 |
|
183 | To enable the profiling agent for a Node.js program running in the App Engine
|
184 | flexible environment, import the agent at the top of your application’s main
|
185 | script or entry point by including the following code snippet:
|
186 |
|
187 | ```js
|
188 | require('@google-cloud/profiler').start();
|
189 | ```
|
190 |
|
191 | You can specify which version of Node.js you're using by adding a snippet like
|
192 | the following to your `package.json`:
|
193 |
|
194 | ```json
|
195 | "engines": {
|
196 | "node": ">=10.4.1"
|
197 | }
|
198 | ```
|
199 | The above snippet will ensure that you're using 10.4.1 or greater.
|
200 |
|
201 | Deploy your application to App Engine Flexible environment as usual.
|
202 |
|
203 | #### Running on Google Compute Engine
|
204 |
|
205 | To enable the profiling agent for a Node.js program running in the Google
|
206 | Compute Engine environment, import the agent at the top of your application’s
|
207 | main script or entry point by including the following code snippet:
|
208 |
|
209 | ```js
|
210 | require('@google-cloud/profiler').start({
|
211 | serviceContext: {
|
212 | service: 'your-service',
|
213 | version: '1.0.0'
|
214 | }
|
215 | });
|
216 | ```
|
217 |
|
218 | #### Running on Google Container Engine
|
219 |
|
220 | To enable the profiling agent for a Node.js program running in the Google
|
221 | Container Engine environment, import the agent at the top of your application’s
|
222 | main script or entry point by including the following code snippet:
|
223 |
|
224 | ```js
|
225 | require('@google-cloud/profiler').start({
|
226 | serviceContext: {
|
227 | service: 'your-service',
|
228 | version: '1.0.0'
|
229 | }
|
230 | });
|
231 | ```
|
232 |
|
233 | #### Running on Istio
|
234 |
|
235 | On Istio, the GCP Metadata server may not be available for a few seconds after
|
236 | your application has started. When this occurs, the profiling agent may fail
|
237 | to start because it cannot initialize required fields. One can retry when
|
238 | starting the profiler with the following snippet.
|
239 |
|
240 | ```js
|
241 | const profiler = require('@google-cloud/profiler');
|
242 | async function startProfiler() {
|
243 | for (let i = 0; i < 3; i++) {
|
244 | try {
|
245 | await profiler.start({
|
246 | serviceContext: {
|
247 | service: 'your-service',
|
248 | version: '1.0.0',
|
249 | },
|
250 | });
|
251 | } catch(e) {
|
252 | console.log(`Failed to start profiler: ${e}`);
|
253 | }
|
254 |
|
255 | // Wait for 1 second before trying again.
|
256 | await new Promise(r => setTimeout(r, 1000));
|
257 | }
|
258 | }
|
259 | startProfiler();
|
260 |
|
261 | ```
|
262 |
|
263 |
|
264 | ### Running elsewhere
|
265 |
|
266 | You can still use `@google-cloud/profiler` if your application is running
|
267 | outside of Google Cloud Platform, for example, running locally, on-premise, or
|
268 | on another cloud provider.
|
269 |
|
270 | 1. You will need to specify your project id and the service you want the
|
271 | collected profiles to be associated with, and (optionally) the version of
|
272 | the service when starting the profiler:
|
273 |
|
274 | ```js
|
275 | await require('@google-cloud/profiler').start({
|
276 | projectId: 'project-id',
|
277 | serviceContext: {
|
278 | service: 'your-service',
|
279 | version: '1.0.0'
|
280 | }
|
281 | });
|
282 | ```
|
283 | 2. You will need to provide credential for your application.
|
284 |
|
285 | * If you are running your application on a development machine or test
|
286 | environment where you are using the [`gcloud` command line tools][gcloud-sdk],
|
287 | and are logged using `gcloud beta auth application-default login`, you
|
288 | already have sufficient credentials, and a service account key is not
|
289 | required.
|
290 |
|
291 | * You can provide credentials via
|
292 | [Application Default Credentials][app-default-credentials]. This is the
|
293 | recommended method.
|
294 | 1. [Create a new JSON service account key][service-account].
|
295 | 2. Copy the key somewhere your application can access it. Be sure not
|
296 | to expose the key publicly.
|
297 | 3. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to
|
298 | the full path to the key. The profiler will automatically look for
|
299 | this environment variable.
|
300 |
|
301 | * You may set the `keyFilename` or `credentials` configuration field to the
|
302 | full path or contents to the key file, respectively. Setting either of these
|
303 | fields will override either setting `GOOGLE_APPLICATION_CREDENTIALS` or
|
304 | logging in using `gcloud`.
|
305 |
|
306 | This is how you would set `keyFilename`:
|
307 | ```js
|
308 | await require('@google-cloud/profiler').start({
|
309 | projectId: 'project-id',
|
310 | serviceContext: {
|
311 | service: 'your-service',
|
312 | version: '1.0.0'
|
313 | },
|
314 | keyFilename: '/path/to/keyfile'
|
315 | });
|
316 | ```
|
317 |
|
318 | This is how you would set `credentials`:
|
319 | ```js
|
320 | await require('@google-cloud/profiler').start({
|
321 | projectId: 'project-id',
|
322 | serviceContext: {
|
323 | service: 'your-service',
|
324 | version: '1.0.0'
|
325 | },
|
326 | credentials: {
|
327 | client_email: 'email',
|
328 | private_key: 'private_key'
|
329 | }
|
330 | });
|
331 | ```
|
332 |
|
333 |
|
334 | ## Samples
|
335 |
|
336 | Samples are in the [`samples/`](https://github.com/googleapis/cloud-profiler-nodejs/tree/master/samples) directory. The samples' `README.md`
|
337 | has instructions for running the samples.
|
338 |
|
339 | | Sample | Source Code | Try it |
|
340 | | --------------------------- | --------------------------------- | ------ |
|
341 | | App | [source code](https://github.com/googleapis/cloud-profiler-nodejs/blob/master/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&page=editor&open_in_editor=samples/app.js,samples/README.md) |
|
342 | | Snippets | [source code](https://github.com/googleapis/cloud-profiler-nodejs/blob/master/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&page=editor&open_in_editor=samples/snippets.js,samples/README.md) |
|
343 |
|
344 |
|
345 |
|
346 | The [Stackdriver Profiler Node.js Client API Reference][client-docs] documentation
|
347 | also contains samples.
|
348 |
|
349 | ## Supported Node.js Versions
|
350 |
|
351 | Our client libraries follow the [Node.js release schedule](https://nodejs.org/en/about/releases/).
|
352 | Libraries are compatible with all current _active_ and _maintenance_ versions of
|
353 | Node.js.
|
354 |
|
355 | Client libraries targetting some end-of-life versions of Node.js are available, and
|
356 | can be installed via npm [dist-tags](https://docs.npmjs.com/cli/dist-tag).
|
357 | The dist-tags follow the naming convention `legacy-(version)`.
|
358 |
|
359 | _Legacy Node.js versions are supported as a best effort:_
|
360 |
|
361 | * Legacy versions will not be tested in continuous integration.
|
362 | * Some security patches may not be able to be backported.
|
363 | * Dependencies will not be kept up-to-date, and features will not be backported.
|
364 |
|
365 | #### Legacy tags available
|
366 |
|
367 | * `legacy-8`: install client libraries from this dist-tag for versions
|
368 | compatible with Node.js 8.
|
369 |
|
370 | ## Versioning
|
371 |
|
372 | This library follows [Semantic Versioning](http://semver.org/).
|
373 |
|
374 |
|
375 | This library is considered to be **General Availability (GA)**. This means it
|
376 | is stable; the code surface will not change in backwards-incompatible ways
|
377 | unless absolutely necessary (e.g. because of critical security issues) or with
|
378 | an extensive deprecation period. Issues and requests against **GA** libraries
|
379 | are addressed with the highest priority.
|
380 |
|
381 |
|
382 |
|
383 |
|
384 |
|
385 | More Information: [Google Cloud Platform Launch Stages][launch_stages]
|
386 |
|
387 | [launch_stages]: https://cloud.google.com/terms/launch-stages
|
388 |
|
389 | ## Contributing
|
390 |
|
391 | Contributions welcome! See the [Contributing Guide](https://github.com/googleapis/cloud-profiler-nodejs/blob/master/CONTRIBUTING.md).
|
392 |
|
393 | Please note that this `README.md`, the `samples/README.md`,
|
394 | and a variety of configuration files in this repository (including `.nycrc` and `tsconfig.json`)
|
395 | are generated from a central template. To edit one of these files, make an edit
|
396 | to its template in this
|
397 | [directory](https://github.com/googleapis/synthtool/tree/master/synthtool/gcp/templates/node_library).
|
398 |
|
399 | ## License
|
400 |
|
401 | Apache Version 2.0
|
402 |
|
403 | See [LICENSE](https://github.com/googleapis/cloud-profiler-nodejs/blob/master/LICENSE)
|
404 |
|
405 | [client-docs]: https://googleapis.dev/nodejs/profiler/latest/
|
406 | [product-docs]: https://cloud.google.com/profiler
|
407 | [shell_img]: https://gstatic.com/cloudssh/images/open-btn.png
|
408 | [projects]: https://console.cloud.google.com/project
|
409 | [billing]: https://support.google.com/cloud/answer/6293499#enable-billing
|
410 | [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=cloudprofiler.googleapis.com
|
411 | [auth]: https://cloud.google.com/docs/authentication/getting-started
|