You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 3, 2024. It is now read-only.
See also, [Setting up Stackdriver Debugger for Node.js][setting-up-nodejs].
17
+
16
18
## Prerequisites
17
19
* Stackdriver Debugger is comptible with Node.js version 4 or greater. Node.js v5+ is recommended.
18
20
@@ -40,87 +42,92 @@ the [Google Cloud Console][dev-console]. You can start adding snapshots and log-
40
42
41
43
## Running on Google Cloud Platform
42
44
43
-
The Stackdriver Debugger Agent should work without manually provided authentication credentials for instances running on Google Cloud Platform, as long as the [Stackdriver Debugger API][debugger-api] access scope is enabled on that instance.
45
+
The Stackdriver Debugger agent should work without the need to manually provide authentication credentials for instances running on Google Cloud Platform, as long as the [Stackdriver Debugger API][debugger-api] access scope is enabled on that instance.
46
+
47
+
### App Engine
44
48
45
-
For**Google App Engine** instances, this is the enabled by default.
49
+
On**Google App Engine**, the Stackdriver Debugger API access scope is enabled by default, and the Stackdriver Debugger agent can be used without needing to provide credentials or a project ID.
46
50
47
-
On **Google Container Engine (GKE)**, you need to explicitly add the `cloud_debugger` OAuth scope when creating the cluster:
51
+
### Container Engine
52
+
53
+
On **Google Container Engine**, you need to explicitly add the `cloud_debugger` OAuth scope when creating the cluster:
For **Google Compute Engine instances**, you need to explicitly enable the Debugger API access scope for each instance. When creating a new instance through the GCP web console, you can do this in one of two ways under **Identity and API access**:
54
-
* Use the Compute Engine default service account and select "Allow full access to all Cloud APIs" under Access scopes.
55
-
* Select a service account with the [**Cloud Debugger Agent**][debugger-roles] role, which contains the necessary permissions (or any other role with at least the same permissions). You may need to create one if you don't have one already.
59
+
### Compute Engine
60
+
61
+
For **Google Compute Engine instances**, you need to explicitly enable the `cloud_debugger` Stackdriver Debugger API access scope for each instance. When creating a new instance through the Google Cloud Platform Console, you can do this under **Identity and API access**: Use the Compute Engine default service account and select "Allow full access to all Cloud APIs" under Access scopes.
62
+
63
+
To use something other than the Compute Engine default service account see the docs for [Creating and Enabling Service Accounts for Instances][service-account-docs] and the [Running elsewhere](#running-locally-and-elsewhere) section below. The important thing is that the service account you use has the [**Cloud Debugger Agent**][debugger-roles] role.
64
+
65
+
## Running locally and elsewhere
66
+
67
+
If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Debugger, provided that you supply a project ID and credentials to the Stackdriver Debugger agent.
56
68
57
-
You may add the Stackdriver Debugger API access scope to existing Compute instances if they are running as a non-default service account by adding the Cloud Debugger Agent role to the service account. For more information, see the docs for [Creating and Enabling Service Accounts for Instances][service-account-docs].
69
+
### Project ID
58
70
59
-
## Running elsewhere
71
+
Provide a project ID to the Stackdriver Debugger agent by setting the projectId value in the options object passed to the agent's `start` method, or set the `GCLOUD_PROJECT` environment variable:
60
72
61
-
If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Debugger.
73
+
On Linux or Mac OS X:
74
+
75
+
```bash
76
+
export GCLOUD_PROJECT=your-project-id
77
+
```
78
+
79
+
On Windows:
80
+
81
+
```
82
+
set GCLOUD_PROJECT=your-project-id
83
+
```
62
84
63
-
1. You will need to specify your project name. Your project name is visible in the [Google Cloud Console][cloud-console-projects], it may be something like `particular-future-12345`. If your application is [running on Google Cloud Platform](running-on-google-cloud-platform), you don't need to specify the project name. You can specify this either in the module options, or through an environment variable:
85
+
And on Windows Powershell:
64
86
65
-
```JS
66
-
// In your app:
67
-
var debug =require('@google-cloud/debug-agent').start({
68
-
allowExpressions:true,
69
-
projectId:'particular-future-12345',
70
-
keyFilename:'/path/to/keyfile.json'
71
-
});
72
-
```
87
+
```
88
+
$env:GCLOUD_PROJECT="your-project-id"
89
+
```
73
90
74
-
```BASH
75
-
# Or in Bash:
76
-
export GCLOUD_PROJECT='particular-future-12345'
77
-
```
91
+
### Credentials
78
92
79
-
1. You need to provide service account credentials to your application.
80
-
* The recommended way is via [Application Default Credentials][app-default-credentials].
81
-
1. [Create a newJSON service account key][service-account].
82
-
1. Copy the key somewhere your application can access it. Be sure not to expose the key publicly.
83
-
1.Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the full path to the key. The debug agent will automatically look forthis environment variable.
84
-
* If you are running your application on a machine where your are using the [`gcloud` command line tools][gcloud-sdk], and are logged using `gcloud auth login`, you already have sufficient credentials, and a service account key is not required.
85
-
* Alternatively, you may set the keyFilename or credentials configuration field to the full path or contents to the key file, respectively. Setting either of these fields will override either setting GOOGLE_APPLICATION_CREDENTIALS or logging in using gcloud. For example:
93
+
Google Cloud Platform client libraries use a strategy called [Application Default Credentials (ADC)][app-default-credentials] to find your application's credentials. You can provide credentials to the Stackdriver Debugger agent by setting the `keyFilename` value in the `options` object passed to the agent's `start` method, or you can set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. For more information, see [Providing credentials to your application][providing-credentials].
86
94
87
-
```js
88
-
// Require and start the agent with configuration options
89
-
require('@google-cloud/debug-agent').start({
90
-
// Allow the evaluation of watch expressions and snapshot conditions:
91
-
allowExpressions: true,
95
+
### Example
92
96
93
-
// The path to your key file:
94
-
keyFilename: '/path/to/keyfile.json',
97
+
```js
98
+
require('@google-cloud/debug-agent').start({
99
+
projectId:'your-project-id',
100
+
keyFilename:'/path/to/key.json'
101
+
});
102
+
```
95
103
96
-
// Or the contents of the key file:
97
-
credentials: require('./path/to/keyfile.json')
98
-
});
99
-
```
104
+
### Source version
100
105
101
-
See the [configuration object][configuration-object] for more details.
106
+
Generate a `source-context.json` file which contains information about the version of the source code used to build the application. This file should be located in the root directory of your application. When you open the Stackdriver Debugger in the Cloud Platform Console, it uses the information in this file to display the correct version of the source.
102
107
103
-
1. Generate a `source-context.json` file which contains information about the version of the source code used to build the application. This file should be located in the root directory of your application. When you open the Stackdriver Debugger in the Cloud Platform Console, it uses the information inthis file to display the correct version of the source.
108
+
```
109
+
gcloud beta debug source gen-repo-info-file
110
+
```
104
111
105
-
gcloud beta debug source gen-repo-info-file
112
+
For more information see [Selecting Source Code Manually][selecting-source].
106
113
107
114
## Debugger Agent Settings
108
115
109
116
You can customize the behaviour of the automatic debugger agent. See [the agent configuration][config-js] for a list of possible configuration options. These options can be passed in the `options` object passed to the `start` function.
110
117
111
-
```JS
112
-
require('@google-cloud/debug-agent').start({
113
-
// .. auth settings ..
118
+
```js
119
+
require('@google-cloud/debug-agent').start({
120
+
// .. auth settings ..
114
121
115
-
// debug agent settings:
116
-
allowExpressions:true,
117
-
serviceContext: {
118
-
service:'my-service',
119
-
version:'version-1'
120
-
},
121
-
capture: { maxFrames:20, maxProperties:100 }
122
-
});
123
-
```
122
+
// debug agent settings:
123
+
allowExpressions:true,
124
+
serviceContext: {
125
+
service:'my-service',
126
+
version:'version-1'
127
+
},
128
+
capture: { maxFrames:20, maxProperties:100 }
129
+
});
130
+
```
124
131
125
132
## Using the Debugger
126
133
@@ -177,12 +184,14 @@ In the Debug UI, you only need to provide the original source code -- you don't
0 commit comments