This repository has been archived by the owner on Apr 3, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 51
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into release-please--branches--main--components--…
…debug-agent
- Loading branch information
Showing
6 changed files
with
221 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
introduction: |- | ||
> This module provides Cloud Debugger support for Node.js applications. | ||
Cloud Debugger is a feature of Google Cloud Platform that lets you debug your | ||
applications in production without stopping or pausing your application. | ||
body: |- | ||
## Debugger Agent Settings | ||
To customize the behaviour of the automatic debugger agent, specify options | ||
when starting the agent. The following code sample shows how to pass in a | ||
subset of the available options. | ||
```js | ||
require('@google-cloud/debug-agent').start({ | ||
// .. auth settings .. | ||
// debug agent settings: | ||
allowExpressions: true, | ||
serviceContext: { | ||
service: 'my-service', | ||
version: 'version-1' | ||
}, | ||
capture: { maxFrames: 20, maxProperties: 100 } | ||
}); | ||
``` | ||
See [the agent configuration][config-ts] for a list of possible configuration | ||
options. | ||
## Using the Debugger | ||
Once your application is running, use the [Debug UI][debug-tab] in your Cloud | ||
[developer console][dev-console] to debug your application. The Debug UI can | ||
be found in the 'Operations -> Debug' section in the navigation panel, or by | ||
simply searching for 'Debug' in the cloud console. | ||
To take a snapshot with the debugger: | ||
1. Click in the gutter (line number area) or enter a filename and line number | ||
in the snapshot panel | ||
2. The debugger inserts a momentary breakpoint at the specified location in | ||
your code in the running instance of your application. | ||
3. As soon as that line of code is reached in any of the running instances of | ||
your application, the stack traces, local variables, and watch expressions | ||
are captured, and your application continues. | ||
**Note:** The directory layout of the code that is being debugged does not | ||
have to exactly match the source code specified in the Debug UI. This is | ||
because the debug agent resolves a snapshot filename by searching for a file | ||
with the longest matching path suffix. If a unique match is found, that file | ||
will be used to set the snapshot. | ||
## Firebase Realtime Database backend | ||
The Cloud Debugger API is deprecated and will be turned down in May 2023. | ||
You can use Firebase Realtime Database for data persistence as an | ||
alternative. | ||
### Enabling the agent | ||
To enable the agent, add the following at the top of your app's main script | ||
or entry point: | ||
```js | ||
require('@google-cloud/debug-agent').start({ | ||
useFirebase: true, | ||
firebaseDbUrl: 'https://my-database-url.firebaseio.com', | ||
firebaseKeyPath: 'path/to/service_account.json', | ||
}); | ||
``` | ||
The following params are optional: | ||
* firebaseDbUrl - https://PROJECT_ID-cdbg.firebase.io.com will be used if not | ||
provided. where PROJECT_ID is your project ID. | ||
* firebaseKeyPath - Default google application credentials are used if not | ||
provided. | ||
### Using the Debugger | ||
Using the Debugger with the Firebase Realtime Database backend requires using | ||
the Snapshot Debugger CLI. | ||
See the [full Snapshot Debugger CLI documentation][snapshot-debugger-readme]. | ||
## Limitations and Requirements | ||
> Note: There is a known issue where enabling the agent may trigger memory | ||
leaks. See [#811](https://github.com/googleapis/cloud-debug-nodejs/issues/811) | ||
* Privacy issues can be created by setting snapshot conditions that watch | ||
expressions evaluated in the context of your application. You may be able | ||
to view sensitive user data when viewing the values of variables. | ||
* The debug agent tries to ensure that all conditions and watchpoints you | ||
add are read-only and have no side effects. It catches, and disallows, | ||
all expressions that may have static side effects to prevent accidental | ||
state change. However, it presently does not catch expressions that have | ||
dynamic side-effects. For example, `o.f` looks like a property access, | ||
but dynamically, it may end up calling a getter function. We presently do | ||
NOT detect such dynamic-side effects. | ||
* The root directory of your application needs to contain a `package.json` | ||
file. | ||
[config-ts]: https://github.com/googleapis/cloud-debug-nodejs/blob/master/src/agent/config.ts | ||
[debug-tab]: https://console.cloud.google.com/debug | ||
[dev-console]: https://console.cloud.google.com/ | ||
[snapshot-debugger-readme]: https://github.com/GoogleCloudPlatform/snapshot-debugger#readme |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters