Skip to content
This repository was archived by the owner on Apr 3, 2024. It is now read-only.

Commit 92176b0

Browse files
mctavishmctavish
authored
docs: add custom readme content (#1100)
1 parent bbaa42e commit 92176b0

6 files changed

Lines changed: 221 additions & 11 deletions

File tree

‎.readme-partials.yaml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
introduction: |-
2+
> This module provides Cloud Debugger support for Node.js applications.
3+
Cloud Debugger is a feature of Google Cloud Platform that lets you debug your
4+
applications in production without stopping or pausing your application.
5+
6+
body: |-
7+
## Debugger Agent Settings
8+
9+
To customize the behaviour of the automatic debugger agent, specify options
10+
when starting the agent. The following code sample shows how to pass in a
11+
subset of the available options.
12+
13+
```js
14+
require('@google-cloud/debug-agent').start({
15+
// .. auth settings ..
16+
17+
// debug agent settings:
18+
allowExpressions: true,
19+
serviceContext: {
20+
service: 'my-service',
21+
version: 'version-1'
22+
},
23+
capture: { maxFrames: 20, maxProperties: 100 }
24+
});
25+
```
26+
27+
See [the agent configuration][config-ts] for a list of possible configuration
28+
options.
29+
30+
## Using the Debugger
31+
32+
Once your application is running, use the [Debug UI][debug-tab] in your Cloud
33+
[developer console][dev-console] to debug your application. The Debug UI can
34+
be found in the 'Operations -> Debug' section in the navigation panel, or by
35+
simply searching for 'Debug' in the cloud console.
36+
37+
To take a snapshot with the debugger:
38+
1. Click in the gutter (line number area) or enter a filename and line number
39+
in the snapshot panel
40+
2. The debugger inserts a momentary breakpoint at the specified location in
41+
your code in the running instance of your application.
42+
3. As soon as that line of code is reached in any of the running instances of
43+
your application, the stack traces, local variables, and watch expressions
44+
are captured, and your application continues.
45+
46+
**Note:** The directory layout of the code that is being debugged does not
47+
have to exactly match the source code specified in the Debug UI. This is
48+
because the debug agent resolves a snapshot filename by searching for a file
49+
with the longest matching path suffix. If a unique match is found, that file
50+
will be used to set the snapshot.
51+
52+
## Firebase Realtime Database backend
53+
54+
The Cloud Debugger API is deprecated and will be turned down in May 2023.
55+
56+
You can use Firebase Realtime Database for data persistence as an
57+
alternative.
58+
59+
### Enabling the agent
60+
61+
To enable the agent, add the following at the top of your app's main script
62+
or entry point:
63+
64+
```js
65+
require('@google-cloud/debug-agent').start({
66+
useFirebase: true,
67+
firebaseDbUrl: 'https://my-database-url.firebaseio.com',
68+
firebaseKeyPath: 'path/to/service_account.json',
69+
});
70+
```
71+
72+
The following params are optional:
73+
* firebaseDbUrl - https://PROJECT_ID-cdbg.firebase.io.com will be used if not
74+
provided. where PROJECT_ID is your project ID.
75+
* firebaseKeyPath - Default google application credentials are used if not
76+
provided.
77+
78+
### Using the Debugger
79+
80+
Using the Debugger with the Firebase Realtime Database backend requires using
81+
the Snapshot Debugger CLI.
82+
83+
See the [full Snapshot Debugger CLI documentation][snapshot-debugger-readme].
84+
85+
## Limitations and Requirements
86+
87+
> Note: There is a known issue where enabling the agent may trigger memory
88+
leaks. See [#811](https://github.com/googleapis/cloud-debug-nodejs/issues/811)
89+
90+
* Privacy issues can be created by setting snapshot conditions that watch
91+
expressions evaluated in the context of your application. You may be able
92+
to view sensitive user data when viewing the values of variables.
93+
* The debug agent tries to ensure that all conditions and watchpoints you
94+
add are read-only and have no side effects. It catches, and disallows,
95+
all expressions that may have static side effects to prevent accidental
96+
state change. However, it presently does not catch expressions that have
97+
dynamic side-effects. For example, `o.f` looks like a property access,
98+
but dynamically, it may end up calling a getter function. We presently do
99+
NOT detect such dynamic-side effects.
100+
* The root directory of your application needs to contain a `package.json`
101+
file.
102+
103+
[config-ts]: https://github.com/googleapis/cloud-debug-nodejs/blob/master/src/agent/config.ts
104+
[debug-tab]: https://console.cloud.google.com/debug
105+
[dev-console]: https://console.cloud.google.com/
106+
[snapshot-debugger-readme]: https://github.com/GoogleCloudPlatform/snapshot-debugger#readme

‎.repo-metadata.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "debugger",
3-
"name_pretty": "Stackdriver Debugger",
3+
"name_pretty": "Cloud Debugger",
44
"product_documentation": "https://cloud.google.com/debugger",
55
"client_documentation": "https://cloud.google.com/nodejs/docs/reference/debug-agent/latest",
66
"issue_tracker": "https://issuetracker.google.com/savedsearches/559771",

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ accept your pull requests.
4040
### Before you begin
4141

4242
1. [Select or create a Cloud Platform project][projects].
43-
1. [Enable the Stackdriver Debugger API][enable_api].
43+
1. [Enable the Cloud Debugger API][enable_api].
4444
1. [Set up authentication with a service account][auth] so you can access the
4545
API from your local workstation.
4646

‎README.md‎

Lines changed: 107 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,24 @@
22
[//]: # "To regenerate it, use `python -m synthtool`."
33
<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"/>
44

5-
# [Stackdriver Debugger: Node.js Client](https://github.com/googleapis/cloud-debug-nodejs)
5+
# [Cloud Debugger: Node.js Client](https://github.com/googleapis/cloud-debug-nodejs)
66

77
[![release level](https://img.shields.io/badge/release%20level-stable-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages)
88
[![npm version](https://img.shields.io/npm/v/@google-cloud/debug-agent.svg)](https://www.npmjs.org/package/@google-cloud/debug-agent)
99

1010

1111

1212

13-
Stackdriver Debug Agent for Node.js
13+
> This module provides Cloud Debugger support for Node.js applications.
14+
Cloud Debugger is a feature of Google Cloud Platform that lets you debug your
15+
applications in production without stopping or pausing your application.
1416

1517

1618
A comprehensive list of changes in each version may be found in
1719
[the CHANGELOG](https://github.com/googleapis/cloud-debug-nodejs/blob/main/CHANGELOG.md).
1820

19-
* [Stackdriver Debugger Node.js Client API Reference][client-docs]
20-
* [Stackdriver Debugger Documentation][product-docs]
21+
* [Cloud Debugger Node.js Client API Reference][client-docs]
22+
* [Cloud Debugger Documentation][product-docs]
2123
* [github.com/googleapis/cloud-debug-nodejs](https://github.com/googleapis/cloud-debug-nodejs)
2224

2325
Read more about the client libraries for Cloud APIs, including the older
@@ -42,7 +44,7 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
4244
### Before you begin
4345

4446
1. [Select or create a Cloud Platform project][projects].
45-
1. [Enable the Stackdriver Debugger API][enable_api].
47+
1. [Enable the Cloud Debugger API][enable_api].
4648
1. [Set up authentication with a service account][auth] so you can access the
4749
API from your local workstation.
4850

@@ -52,7 +54,106 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
5254
npm install @google-cloud/debug-agent
5355
```
5456

57+
## Debugger Agent Settings
5558

59+
To customize the behaviour of the automatic debugger agent, specify options
60+
when starting the agent. The following code sample shows how to pass in a
61+
subset of the available options.
62+
63+
```js
64+
require('@google-cloud/debug-agent').start({
65+
// .. auth settings ..
66+
67+
// debug agent settings:
68+
allowExpressions: true,
69+
serviceContext: {
70+
service: 'my-service',
71+
version: 'version-1'
72+
},
73+
capture: { maxFrames: 20, maxProperties: 100 }
74+
});
75+
```
76+
77+
See [the agent configuration][config-ts] for a list of possible configuration
78+
options.
79+
80+
## Using the Debugger
81+
82+
Once your application is running, use the [Debug UI][debug-tab] in your Cloud
83+
[developer console][dev-console] to debug your application. The Debug UI can
84+
be found in the 'Operations -> Debug' section in the navigation panel, or by
85+
simply searching for 'Debug' in the cloud console.
86+
87+
To take a snapshot with the debugger:
88+
1. Click in the gutter (line number area) or enter a filename and line number
89+
in the snapshot panel
90+
2. The debugger inserts a momentary breakpoint at the specified location in
91+
your code in the running instance of your application.
92+
3. As soon as that line of code is reached in any of the running instances of
93+
your application, the stack traces, local variables, and watch expressions
94+
are captured, and your application continues.
95+
96+
**Note:** The directory layout of the code that is being debugged does not
97+
have to exactly match the source code specified in the Debug UI. This is
98+
because the debug agent resolves a snapshot filename by searching for a file
99+
with the longest matching path suffix. If a unique match is found, that file
100+
will be used to set the snapshot.
101+
102+
## Firebase Realtime Database backend
103+
104+
The Cloud Debugger API is deprecated and will be turned down in May 2023.
105+
106+
You can use Firebase Realtime Database for data persistence as an
107+
alternative.
108+
109+
### Enabling the agent
110+
111+
To enable the agent, add the following at the top of your app's main script
112+
or entry point:
113+
114+
```js
115+
require('@google-cloud/debug-agent').start({
116+
useFirebase: true,
117+
firebaseDbUrl: 'https://my-database-url.firebaseio.com',
118+
firebaseKeyPath: 'path/to/service_account.json',
119+
});
120+
```
121+
122+
The following params are optional:
123+
* firebaseDbUrl - https://PROJECT_ID-cdbg.firebase.io.com will be used if not
124+
provided. where PROJECT_ID is your project ID.
125+
* firebaseKeyPath - Default google application credentials are used if not
126+
provided.
127+
128+
### Using the Debugger
129+
130+
Using the Debugger with the Firebase Realtime Database backend requires using
131+
the Snapshot Debugger CLI.
132+
133+
See the [full Snapshot Debugger CLI documentation][snapshot-debugger-readme].
134+
135+
## Limitations and Requirements
136+
137+
> Note: There is a known issue where enabling the agent may trigger memory
138+
leaks. See [#811](https://github.com/googleapis/cloud-debug-nodejs/issues/811)
139+
140+
* Privacy issues can be created by setting snapshot conditions that watch
141+
expressions evaluated in the context of your application. You may be able
142+
to view sensitive user data when viewing the values of variables.
143+
* The debug agent tries to ensure that all conditions and watchpoints you
144+
add are read-only and have no side effects. It catches, and disallows,
145+
all expressions that may have static side effects to prevent accidental
146+
state change. However, it presently does not catch expressions that have
147+
dynamic side-effects. For example, `o.f` looks like a property access,
148+
but dynamically, it may end up calling a getter function. We presently do
149+
NOT detect such dynamic-side effects.
150+
* The root directory of your application needs to contain a `package.json`
151+
file.
152+
153+
[config-ts]: https://github.com/googleapis/cloud-debug-nodejs/blob/master/src/agent/config.ts
154+
[debug-tab]: https://console.cloud.google.com/debug
155+
[dev-console]: https://console.cloud.google.com/
156+
[snapshot-debugger-readme]: https://github.com/GoogleCloudPlatform/snapshot-debugger#readme
56157

57158

58159
## Samples
@@ -66,7 +167,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/cloud-debug-nodejs
66167

67168

68169

69-
The [Stackdriver Debugger Node.js Client API Reference][client-docs] documentation
170+
The [Cloud Debugger Node.js Client API Reference][client-docs] documentation
70171
also contains samples.
71172

72173
## Supported Node.js Versions

‎linkinator.config.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
"skip": [
44
"https://codecov.io/gh/googleapis/",
55
"www.googleapis.com",
6-
"img.shields.io"
6+
"img.shields.io",
7+
"https://project_id-cdbg.firebase.io.com"
78
],
89
"silent": true,
910
"concurrency": 10

‎samples/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,13 @@
22
[//]: # "To regenerate it, use `python -m synthtool`."
33
<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"/>
44

5-
# [Stackdriver Debugger: Node.js Samples](https://github.com/googleapis/cloud-debug-nodejs)
5+
# [Cloud Debugger: Node.js Samples](https://github.com/googleapis/cloud-debug-nodejs)
66

77
[![Open in Cloud Shell][shell_img]][shell_link]
88

9-
9+
> This module provides Cloud Debugger support for Node.js applications.
10+
Cloud Debugger is a feature of Google Cloud Platform that lets you debug your
11+
applications in production without stopping or pausing your application.
1012

1113
## Table of Contents
1214

0 commit comments

Comments
 (0)