diff --git a/.github/.OwlBot.lock.yaml b/.github/.OwlBot.lock.yaml
index f3ca5561..74883698 100644
--- a/.github/.OwlBot.lock.yaml
+++ b/.github/.OwlBot.lock.yaml
@@ -13,5 +13,5 @@
# limitations under the License.
docker:
image: gcr.io/cloud-devrel-public-resources/owlbot-nodejs:latest
- digest: sha256:ddb19a6df6c1fa081bc99fb29658f306dd64668bc26f75d1353b28296f3a78e6
-# created: 2022-06-07T21:18:30.024751809Z
+ digest: sha256:bb493bf01d28519e82ab61c490c20122c85a7119c03a978ad0c34b4239fbad15
+# created: 2022-08-23T18:40:55.597313991Z
diff --git a/.kokoro/publish.sh b/.kokoro/publish.sh
index 77a5defb..949e3e1d 100755
--- a/.kokoro/publish.sh
+++ b/.kokoro/publish.sh
@@ -19,7 +19,6 @@ set -eo pipefail
export NPM_CONFIG_PREFIX=${HOME}/.npm-global
# Start the releasetool reporter
-python3 -m pip install gcp-releasetool
python3 -m releasetool publish-reporter-script > /tmp/publisher-script; source /tmp/publisher-script
cd $(dirname $0)/..
diff --git a/.kokoro/release/docs.sh b/.kokoro/release/docs.sh
index 4c866c86..1d8f3f49 100755
--- a/.kokoro/release/docs.sh
+++ b/.kokoro/release/docs.sh
@@ -29,7 +29,6 @@ npm run docs
# create docs.metadata, based on package.json and .repo-metadata.json.
npm i json@9.0.6 -g
-python3 -m pip install --user gcp-docuploader
python3 -m docuploader create-metadata \
--name=$(cat .repo-metadata.json | json name) \
--version=$(cat package.json | json version) \
diff --git a/.readme-partials.yaml b/.readme-partials.yaml
new file mode 100644
index 00000000..c5ce7c62
--- /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.firebaseio.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 60ca52ab..c686484f 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/CHANGELOG.md b/CHANGELOG.md
index d294fed6..29c1a233 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
# Node.js Agent for Google Cloud Debug ChangeLog
+## [7.1.1](https://github.com/googleapis/cloud-debug-nodejs/compare/v7.1.0...v7.1.1) (2022-11-18)
+
+
+### Bug Fixes
+
+* **deps:** Update dependency express to v4.18.2 ([#1110](https://github.com/googleapis/cloud-debug-nodejs/issues/1110)) ([b50b8a0](https://github.com/googleapis/cloud-debug-nodejs/commit/b50b8a078459b58be1b1dac4e8f921b2ec5960d2))
+* Remove pip install statements ([#1546](https://github.com/googleapis/cloud-debug-nodejs/issues/1546)) ([#1101](https://github.com/googleapis/cloud-debug-nodejs/issues/1101)) ([fd2cd5a](https://github.com/googleapis/cloud-debug-nodejs/commit/fd2cd5ad39a007744d0c9349bbdf9b5e386cbaa7))
+
## [7.1.0](https://github.com/googleapis/cloud-debug-nodejs/compare/v7.0.0...v7.1.0) (2022-07-26)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ceb1b83a..ad0b3368 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 2da133e5..367b721d 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)
[](https://cloud.google.com/terms/launch-stages)
[](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.firebaseio.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/package.json b/package.json
index dac54527..8d8b356c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@google-cloud/debug-agent",
- "version": "7.1.0",
+ "version": "7.1.1",
"author": "Google Inc.",
"description": "Stackdriver Debug Agent for Node.js",
"main": "./build/src/index",
@@ -31,7 +31,7 @@
"system-test": "nyc mocha build/system-test --timeout 600000",
"test": "nyc cross-env CLOUD_DEBUG_ASSERTIONS=1 mocha build/test --recursive false",
"compile": "tsc -p .",
- "postcompile": "cpy test/*.js test/**/*.js test/fixtures build --parents",
+ "postcompile": "cpy \"test/\" build",
"fix": "gts fix",
"pretest": "npm run compile",
"prepack": "npm run compile",
@@ -66,12 +66,12 @@
"@types/mocha": "^9.0.0",
"@types/mv": "^2.1.0",
"@types/ncp": "^2.0.3",
- "@types/node": "^16.0.0",
+ "@types/node": "^18.0.0",
"@types/proxyquire": "^1.3.28",
"@types/semver": "^7.0.0",
"@types/tmp": "^0.2.0",
"@types/uuid": "^8.0.0",
- "cpy-cli": "^3.1.0",
+ "cpy-cli": "^4.0.0",
"cross-env": "^7.0.0",
"execa": "^5.0.0",
"gts": "^3.1.0",
@@ -85,6 +85,6 @@
"teeny-request": "^8.0.0",
"tmp-promise": "^3.0.0",
"typescript": "^4.6.4",
- "uuid": "^8.0.0"
+ "uuid": "^9.0.0"
}
-}
\ No newline at end of file
+}
diff --git a/samples/README.md b/samples/README.md
index 21444bad..374b85f6 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
diff --git a/samples/package.json b/samples/package.json
index 5e3c4575..e5ea458a 100644
--- a/samples/package.json
+++ b/samples/package.json
@@ -17,8 +17,8 @@
"test": "mocha"
},
"dependencies": {
- "@google-cloud/debug-agent": "^7.1.0",
- "express": "4.18.1"
+ "@google-cloud/debug-agent": "^7.1.1",
+ "express": "4.18.2"
},
"devDependencies": {
"execa": "^5.0.0",
diff --git a/system-test/fixtures/sample/package.json b/system-test/fixtures/sample/package.json
index 7296c2c8..2798ab60 100644
--- a/system-test/fixtures/sample/package.json
+++ b/system-test/fixtures/sample/package.json
@@ -15,7 +15,7 @@
},
"devDependencies": {
"gts": "^2.0.0",
- "typescript": "^3.8.3",
- "@types/node": "^16.0.0"
+ "typescript": "4.8.4",
+ "@types/node": "^18.0.0"
}
}