diff --git a/.readme-partials.yaml b/.readme-partials.yaml
new file mode 100644
index 000000000..ca9660e28
--- /dev/null
+++ b/.readme-partials.yaml
@@ -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
diff --git a/.repo-metadata.json b/.repo-metadata.json
index 60ca52abf..c686484f2 100644
--- a/.repo-metadata.json
+++ b/.repo-metadata.json
@@ -1,6 +1,6 @@
{
"name": "debugger",
- "name_pretty": "Stackdriver Debugger",
+ "name_pretty": "Cloud Debugger",
"product_documentation": "https://cloud.google.com/debugger",
"client_documentation": "https://cloud.google.com/nodejs/docs/reference/debug-agent/latest",
"issue_tracker": "https://issuetracker.google.com/savedsearches/559771",
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ceb1b83ae..ad0b3368c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,7 +40,7 @@ accept your pull requests.
### Before you begin
1. [Select or create a Cloud Platform project][projects].
-1. [Enable the Stackdriver Debugger API][enable_api].
+1. [Enable the Cloud Debugger API][enable_api].
1. [Set up authentication with a service account][auth] so you can access the
API from your local workstation.
diff --git a/README.md b/README.md
index 2da133e5f..5c6214586 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
[//]: # "To regenerate it, use `python -m synthtool`."
-# [Stackdriver Debugger: Node.js Client](https://github.com/googleapis/cloud-debug-nodejs)
+# [Cloud Debugger: Node.js Client](https://github.com/googleapis/cloud-debug-nodejs)
[![release level](https://img.shields.io/badge/release%20level-stable-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages)
[![npm version](https://img.shields.io/npm/v/@google-cloud/debug-agent.svg)](https://www.npmjs.org/package/@google-cloud/debug-agent)
@@ -10,14 +10,16 @@
-Stackdriver Debug Agent for Node.js
+> 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.
A comprehensive list of changes in each version may be found in
[the CHANGELOG](https://github.com/googleapis/cloud-debug-nodejs/blob/main/CHANGELOG.md).
-* [Stackdriver Debugger Node.js Client API Reference][client-docs]
-* [Stackdriver Debugger Documentation][product-docs]
+* [Cloud Debugger Node.js Client API Reference][client-docs]
+* [Cloud Debugger Documentation][product-docs]
* [github.com/googleapis/cloud-debug-nodejs](https://github.com/googleapis/cloud-debug-nodejs)
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].
### Before you begin
1. [Select or create a Cloud Platform project][projects].
-1. [Enable the Stackdriver Debugger API][enable_api].
+1. [Enable the Cloud Debugger API][enable_api].
1. [Set up authentication with a service account][auth] so you can access the
API from your local workstation.
@@ -52,7 +54,106 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
npm install @google-cloud/debug-agent
```
+## 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
## Samples
@@ -66,7 +167,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/cloud-debug-nodejs
-The [Stackdriver Debugger Node.js Client API Reference][client-docs] documentation
+The [Cloud Debugger Node.js Client API Reference][client-docs] documentation
also contains samples.
## Supported Node.js Versions
diff --git a/linkinator.config.json b/linkinator.config.json
index 29a223b6d..cf4c78689 100644
--- a/linkinator.config.json
+++ b/linkinator.config.json
@@ -3,7 +3,8 @@
"skip": [
"https://codecov.io/gh/googleapis/",
"www.googleapis.com",
- "img.shields.io"
+ "img.shields.io",
+ "https://project_id-cdbg.firebase.io.com"
],
"silent": true,
"concurrency": 10
diff --git a/samples/README.md b/samples/README.md
index 21444badd..374b85f60 100644
--- a/samples/README.md
+++ b/samples/README.md
@@ -2,11 +2,13 @@
[//]: # "To regenerate it, use `python -m synthtool`."
-# [Stackdriver Debugger: Node.js Samples](https://github.com/googleapis/cloud-debug-nodejs)
+# [Cloud Debugger: Node.js Samples](https://github.com/googleapis/cloud-debug-nodejs)
[![Open in Cloud Shell][shell_img]][shell_link]
-
+> 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.
## Table of Contents