google-cloud-debugger 0.30.0 → 0.31.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +111 -75
- data/ext/google/cloud/debugger/debugger_c/evaluator.c +14 -9
- data/lib/google-cloud-debugger.rb +55 -0
- data/lib/google/cloud/debugger.rb +140 -22
- data/lib/google/cloud/debugger/agent.rb +4 -4
- data/lib/google/cloud/debugger/breakpoint.rb +2 -2
- data/lib/google/cloud/debugger/breakpoint/evaluator.rb +885 -828
- data/lib/google/cloud/debugger/breakpoint/source_location.rb +1 -2
- data/lib/google/cloud/debugger/breakpoint/validator.rb +6 -6
- data/lib/google/cloud/debugger/breakpoint/variable.rb +7 -8
- data/lib/google/cloud/debugger/breakpoint_manager.rb +1 -1
- data/lib/google/cloud/debugger/credentials.rb +7 -7
- data/lib/google/cloud/debugger/debuggee.rb +4 -8
- data/lib/google/cloud/debugger/debuggee/app_uniquifier_generator.rb +0 -2
- data/lib/google/cloud/debugger/logpoint.rb +1 -1
- data/lib/google/cloud/debugger/middleware.rb +16 -18
- data/lib/google/cloud/debugger/project.rb +2 -28
- data/lib/google/cloud/debugger/rails.rb +21 -9
- data/lib/google/cloud/debugger/service.rb +4 -2
- data/lib/google/cloud/debugger/snappoint.rb +1 -1
- data/lib/google/cloud/debugger/tracer.rb +2 -1
- data/lib/google/cloud/debugger/transmitter.rb +1 -1
- data/lib/google/cloud/debugger/version.rb +1 -1
- metadata +11 -11
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 71f28cd2cdbb26aeb952111ceed9989d726fe066c7b42b15dc6abc01b77c6d80
|
4
|
+
data.tar.gz: 212961fe1b440ca8934468eedc899ce0304523443944fd4e882e7d07bca60157
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 557129ab5d5b4010df8d7ff0baebe95fe3b20ea5615c2b50e542db0da479c14be7f8ec49e2e72bbfe0eb25d65ca630204f0097657fe26bf7d5e24b08cdc14ab4
|
7
|
+
data.tar.gz: e87fece9e975bd6b6a194029b880d6a682890af4df8c866b0424bed021744e689752a9454ef824ed26b2cebbb1d07157c8422c3718fbd123dc83997bcc729cf6
|
data/README.md
CHANGED
@@ -1,6 +1,12 @@
|
|
1
1
|
# google-cloud-debugger
|
2
2
|
|
3
|
-
[Stackdriver Debugger](https://cloud.google.com/debugger/) lets you inspect the
|
3
|
+
[Stackdriver Debugger](https://cloud.google.com/debugger/) lets you inspect the
|
4
|
+
state of a running application at any code location in real time, without
|
5
|
+
stopping or slowing down the application, and without modifying the code to add
|
6
|
+
logging statements. You can use Stackdriver Debugger with any deployment of
|
7
|
+
your application, including test, development, and production. The Ruby
|
8
|
+
debugger adds minimal request latency, typically less than 50ms, and only when
|
9
|
+
application state is captured. In most cases, this is not noticeable by users.
|
4
10
|
|
5
11
|
- [google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger)
|
6
12
|
- [google-cloud-debugger on RubyGems](https://rubygems.org/gems/google-cloud-debugger)
|
@@ -8,44 +14,28 @@
|
|
8
14
|
|
9
15
|
## Quick Start
|
10
16
|
|
11
|
-
|
17
|
+
### Installing the gem
|
12
18
|
|
13
|
-
|
14
|
-
$ gem install google-cloud-debugger
|
15
|
-
```
|
16
|
-
|
17
|
-
Or install through Bundler:
|
18
|
-
|
19
|
-
1. Add the `google-cloud-debugger` gem to your Gemfile:
|
19
|
+
Add the `google-cloud-debugger` gem to your Gemfile:
|
20
20
|
|
21
21
|
```ruby
|
22
22
|
gem "google-cloud-debugger"
|
23
23
|
```
|
24
24
|
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
$ bundle install
|
29
|
-
```
|
25
|
+
Alternatively, consider installing the [`stackdriver`](../stackdriver) gem. It
|
26
|
+
includes the `google-cloud-debugger` gem as a dependency, and automatically
|
27
|
+
initializes it for some application frameworks.
|
30
28
|
|
31
|
-
|
32
|
-
the `google-cloud-debugger` gem.
|
29
|
+
### Initializing the Debugger
|
33
30
|
|
34
|
-
|
31
|
+
The Stackdriver Debugger library provides a Debugger agent that helps create
|
32
|
+
breakpoints in your running applications. It then collects application snapshot
|
33
|
+
data and transmits it to the Stackdriver Debugger service for you to view on
|
34
|
+
the Google Cloud Console. The library also comes with a Railtie and a Rack
|
35
|
+
Middleware to help control the Debugger agent in popular Rack based frameworks,
|
36
|
+
such as Ruby on Rails and Sinatra.
|
35
37
|
|
36
|
-
|
37
|
-
API](https://console.cloud.google.com/apis/library/clouddebugger.googleapis.com)
|
38
|
-
to be enabled on your Google Cloud project. Make sure it's enabled if not
|
39
|
-
already.
|
40
|
-
|
41
|
-
## Enabling the Debugger agent
|
42
|
-
|
43
|
-
The Stackdriver Debugger library provides a Debugger agent that helps instrument
|
44
|
-
breakpoints in your running applications. The library also comes with a Railtie
|
45
|
-
and a Rack Middleware to help control the Debugger agent in popular Rack based
|
46
|
-
frameworks, such as Ruby on Rails and Sinatra.
|
47
|
-
|
48
|
-
### With Ruby on Rails
|
38
|
+
#### Setup with Ruby on Rails
|
49
39
|
|
50
40
|
You can load the Railtie that comes with the library into your Ruby
|
51
41
|
on Rails application by explicitly requiring it during the application startup:
|
@@ -58,7 +48,7 @@ require "google/cloud/debugger/rails"
|
|
58
48
|
If you're using the `stackdriver` gem, it automatically loads the Railtie into
|
59
49
|
your application when it starts.
|
60
50
|
|
61
|
-
|
51
|
+
#### Setup with other Rack-based frameworks
|
62
52
|
|
63
53
|
Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware
|
64
54
|
provided by the library:
|
@@ -68,38 +58,42 @@ require "google/cloud/debugger"
|
|
68
58
|
use Google::Cloud::Debugger::Middleware
|
69
59
|
```
|
70
60
|
|
71
|
-
|
61
|
+
#### Setup without a Rack-based framework
|
72
62
|
|
73
|
-
Non-rack-based applications can start the agent explicitly
|
74
|
-
|
63
|
+
Non-rack-based applications can start the agent explicitly during the
|
64
|
+
initialization code:
|
75
65
|
|
76
66
|
```ruby
|
77
67
|
require "google/cloud/debugger"
|
78
68
|
Google::Cloud::Debugger.new.start
|
79
69
|
```
|
80
70
|
|
81
|
-
###
|
71
|
+
### Connecting to the Debugger
|
82
72
|
|
83
|
-
You can
|
84
|
-
|
85
|
-
|
73
|
+
You can set breakpoints and view snapshots using the Google Cloud Console.
|
74
|
+
If your app is hosted on Google Cloud (such as on Google App Engine, Google
|
75
|
+
Kubernetes Engine, or Google Compute Engine), you can use the same project.
|
76
|
+
Otherwise, if your application is hosted elsewhere, create a new project on
|
77
|
+
[Google Cloud](https://console.cloud.google.com/).
|
86
78
|
|
87
|
-
|
79
|
+
Make sure the
|
80
|
+
[Stackdriver Debugger API](https://console.cloud.google.com/apis/library/clouddebugger.googleapis.com)
|
81
|
+
is enabled on your Google Cloud project.
|
88
82
|
|
89
|
-
|
90
|
-
|
91
|
-
|
83
|
+
To connect to the Stackdriver Debugger service, the agent needs to be
|
84
|
+
authenticated. If your application is hosted on Google Cloud Platform, much of
|
85
|
+
this is handled for you automatically.
|
92
86
|
|
93
|
-
|
87
|
+
#### Connecting from Google App Engine (GAE)
|
94
88
|
|
95
|
-
|
96
|
-
default, and
|
97
|
-
|
89
|
+
If your app is running on Google App Engine, the Stackdriver Debugger agent
|
90
|
+
authenticates automatically by default, and no additional configuration is
|
91
|
+
required.
|
98
92
|
|
99
|
-
|
93
|
+
#### Connecting from Google Kubernetes Engine (GKE)
|
100
94
|
|
101
|
-
|
102
|
-
scope when creating the cluster:
|
95
|
+
If your app is running on Google Kubernetes Engine, you must explicitly add the
|
96
|
+
`cloud_debugger` OAuth scope when creating the cluster:
|
103
97
|
|
104
98
|
```sh
|
105
99
|
$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud_debugger
|
@@ -108,11 +102,14 @@ $ gcloud container clusters create example-cluster-name --scopes https://www.goo
|
|
108
102
|
You can also do this through the Google Cloud Platform Console. Select
|
109
103
|
**Enabled** in the Cloud Platform section of **Create a container cluster**.
|
110
104
|
|
111
|
-
|
105
|
+
After the OAuth scope is enabled, the Stackdriver Debugger agent authenticates
|
106
|
+
automatically by default, and no additional configuration is required.
|
112
107
|
|
113
|
-
|
114
|
-
|
115
|
-
|
108
|
+
#### Connecting from Google Compute Engine (GCE)
|
109
|
+
|
110
|
+
If your app is running on Google Compute Engine, its VM instances should have
|
111
|
+
one of the following access scopes. These are only relevant when you use
|
112
|
+
Compute Engine's default service account:
|
116
113
|
|
117
114
|
* `https://www.googleapis.com/auth/cloud-platform`
|
118
115
|
* `https://www.googleapis.com/auth/cloud_debugger`
|
@@ -122,25 +119,21 @@ through the Google Cloud Platform Console. Select **Allow full access to all
|
|
122
119
|
Cloud APIs** in the **Identity and API access** section of **Create an
|
123
120
|
instance**.
|
124
121
|
|
125
|
-
The `cloud_debugger` access scope
|
122
|
+
The `cloud_debugger` access scope can be supplied manually using the SDK's
|
126
123
|
`gcloud compute instances create` command or the `gcloud compute instances
|
127
124
|
set-service-account` command.
|
128
125
|
|
129
|
-
|
126
|
+
After the OAuth scope is enabled, the Stackdriver Debugger agent authenticates
|
127
|
+
automatically by default using the VM's service account, and no additional
|
128
|
+
configuration is required.
|
129
|
+
|
130
|
+
#### Connecting from other hosting environments
|
130
131
|
|
131
132
|
To run the Stackdriver Debugger agent outside of Google Cloud Platform, you must
|
132
133
|
supply your GCP project ID and appropriate service account credentials directly
|
133
134
|
to the Stackdriver Debugger agent. This applies to running the agent on your own
|
134
135
|
workstation, on your datacenter's computers, or on the VM instances of another
|
135
|
-
cloud provider.
|
136
|
-
instructions on how to do so.
|
137
|
-
|
138
|
-
## Authentication
|
139
|
-
|
140
|
-
This library uses Service Account credentials to connect to Google Cloud
|
141
|
-
services. When running on Compute Engine the credentials will be discovered
|
142
|
-
automatically. When running on other environments the Service Account
|
143
|
-
credentials can be specified by providing in several ways.
|
136
|
+
cloud provider.
|
144
137
|
|
145
138
|
The best way to provide authentication information if you're using Ruby on Rails
|
146
139
|
is through the Rails configuration interface:
|
@@ -150,25 +143,25 @@ is through the Rails configuration interface:
|
|
150
143
|
Rails.application.configure do |config|
|
151
144
|
# Shared parameters
|
152
145
|
config.google_cloud.project_id = "your-project-id"
|
153
|
-
config.google_cloud.
|
146
|
+
config.google_cloud.credentials = "/path/to/key.json"
|
154
147
|
# Or Stackdriver Debugger agent specific parameters
|
155
148
|
config.google_cloud.debugger.project_id = "your-project-id"
|
156
|
-
config.google_cloud.debugger.
|
149
|
+
config.google_cloud.debugger.credentials = "/path/to/key.json"
|
157
150
|
end
|
158
151
|
```
|
159
152
|
|
160
|
-
Other Rack-based applications that are loading the Rack Middleware directly can
|
161
|
-
the configration interface:
|
153
|
+
Other Rack-based applications that are loading the Rack Middleware directly can
|
154
|
+
use the configration interface:
|
162
155
|
|
163
156
|
```ruby
|
164
157
|
require "google/cloud/debugger"
|
165
158
|
Google::Cloud.configure do |config|
|
166
159
|
# Shared parameters
|
167
160
|
config.project_id = "your-project-id"
|
168
|
-
config.
|
161
|
+
config.credentials = "/path/to/key.json"
|
169
162
|
# Or Stackdriver Debugger agent specific parameters
|
170
163
|
config.debugger.project_id = "your-project-id"
|
171
|
-
config.debugger.
|
164
|
+
config.debugger.credentials = "/path/to/key.json"
|
172
165
|
end
|
173
166
|
```
|
174
167
|
|
@@ -184,15 +177,58 @@ This library also supports the other authentication methods provided by the
|
|
184
177
|
`google-cloud-ruby` suite. Instructions and configuration options are covered
|
185
178
|
in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
|
186
179
|
|
187
|
-
|
180
|
+
### Using the Debugger
|
181
|
+
|
182
|
+
When you set a breakpoint in the Stackdriver Debugger console, the agent takes
|
183
|
+
a snapshot of application data when the breakpoint is hit. The application then
|
184
|
+
continues running with minimal slowdown, and you can view the snapshot offline
|
185
|
+
in the console.
|
186
|
+
|
187
|
+
By default, the snapshot includes the local variables from the current and four
|
188
|
+
most recent stack frames. You may include additional data in the snapshot by
|
189
|
+
providing a list of _expressions_ when you create the breakpoint. Expressions
|
190
|
+
may be instance variables, global variables, or the result of calling Ruby
|
191
|
+
methods, or indeed, any Ruby expression.
|
192
|
+
|
193
|
+
For more information on using the debugger features, see the
|
194
|
+
[Stackdriver Debugger Documentation](https://cloud.google.com/debugger/docs/).
|
195
|
+
|
196
|
+
#### Working with Mutation Protection
|
197
|
+
|
198
|
+
To reduce the risk of corrupting your application data or changing your
|
199
|
+
application's behavior, the debugger agent checks all expressions you provide
|
200
|
+
for possible side effects before it runs them. If an expression calls any code
|
201
|
+
that could modify the program state, by changing an instance variable for
|
202
|
+
example, it is not evaluated.
|
203
|
+
|
204
|
+
This check is rather conservative, so if you are receiving mutation errors on
|
205
|
+
an expression you know to be safe, you may disable the check by wrapping your
|
206
|
+
expression in a call to `Google::Cloud::Debugger.allow_mutating_methods!`. For
|
207
|
+
example:
|
208
|
+
|
209
|
+
```ruby
|
210
|
+
Google::Cloud::Debugger.allow_mutating_methods! { my_expression() }
|
211
|
+
```
|
212
|
+
|
213
|
+
You may disable side effect checks globally by setting the
|
214
|
+
`allow_mutating_methods` configuration. See the next section on configuring the
|
215
|
+
agent.
|
216
|
+
|
217
|
+
#### Configuring the agent
|
188
218
|
|
189
|
-
|
219
|
+
You can customize the behavior of the Stackdriver Debugger agent. This includes
|
220
|
+
setting the Google Cloud project and authentication, and customizing the
|
221
|
+
behavior of the debugger itself, such as side effect protection and data
|
222
|
+
size limits. See [agent configuration](../stackdriver/docs/configuration.md)
|
223
|
+
for a list of possible configuration options.
|
190
224
|
|
191
|
-
##
|
225
|
+
## Compatibility
|
192
226
|
|
193
|
-
This library
|
227
|
+
This library is supported on Ruby 2.2 or later.
|
194
228
|
|
195
|
-
|
229
|
+
This library follows [Semantic Versioning](http://semver.org/). It is currently
|
230
|
+
in major version zero (0.y.z), which means that anything may change at any time
|
231
|
+
and the public API should not be considered stable.
|
196
232
|
|
197
233
|
## Contributing
|
198
234
|
|
@@ -21,8 +21,8 @@
|
|
21
21
|
static void
|
22
22
|
eval_trace_callback(void *data, rb_trace_arg_t *trace_arg)
|
23
23
|
{
|
24
|
-
rb_event_flag_t event
|
25
|
-
VALUE evaluator
|
24
|
+
rb_event_flag_t event;
|
25
|
+
VALUE evaluator;
|
26
26
|
VALUE klass;
|
27
27
|
VALUE obj;
|
28
28
|
VALUE method_id;
|
@@ -32,15 +32,16 @@ eval_trace_callback(void *data, rb_trace_arg_t *trace_arg)
|
|
32
32
|
CONST_ID(trace_func_cb_id, "trace_func_callback");
|
33
33
|
CONST_ID(trace_c_func_cb_id, "trace_c_func_callback");
|
34
34
|
|
35
|
+
event = rb_tracearg_event_flag(trace_arg);
|
36
|
+
evaluator = (VALUE)data;
|
35
37
|
obj = rb_tracearg_self(trace_arg);
|
36
38
|
method_id = rb_tracearg_method_id(trace_arg);
|
39
|
+
klass = rb_tracearg_defined_class(trace_arg);
|
37
40
|
|
38
41
|
if (event & RUBY_EVENT_CALL) {
|
39
|
-
rb_funcall(evaluator, trace_func_cb_id,
|
42
|
+
rb_funcall(evaluator, trace_func_cb_id, 3, obj, klass, method_id);
|
40
43
|
}
|
41
44
|
if (event & RUBY_EVENT_C_CALL) {
|
42
|
-
klass = rb_tracearg_defined_class(trace_arg);
|
43
|
-
|
44
45
|
rb_funcall(evaluator, trace_c_func_cb_id, 3, obj, klass, method_id);
|
45
46
|
}
|
46
47
|
|
@@ -79,10 +80,13 @@ rb_enable_method_trace_for_thread(VALUE self)
|
|
79
80
|
VALUE current_thread;
|
80
81
|
VALUE thread_variables_hash;
|
81
82
|
VALUE trace_set;
|
83
|
+
VALUE evaluator;
|
84
|
+
ID current_evaluator_id;
|
82
85
|
ID locals_id;
|
83
86
|
ID eval_trace_thread_id;
|
84
87
|
VALUE eval_trace_thread_flag;
|
85
88
|
|
89
|
+
CONST_ID(current_evaluator_id, "current");
|
86
90
|
CONST_ID(locals_id, "locals");
|
87
91
|
CONST_ID(eval_trace_thread_id, "gcloud_eval_trace_set");
|
88
92
|
eval_trace_thread_flag = ID2SYM(eval_trace_thread_id);
|
@@ -90,9 +94,10 @@ rb_enable_method_trace_for_thread(VALUE self)
|
|
90
94
|
current_thread = rb_thread_current();
|
91
95
|
thread_variables_hash = rb_ivar_get(current_thread, locals_id);
|
92
96
|
trace_set = rb_hash_aref(thread_variables_hash, eval_trace_thread_flag);
|
97
|
+
evaluator = rb_funcall(self, current_evaluator_id, 0);
|
93
98
|
|
94
99
|
if (!RTEST(trace_set)) {
|
95
|
-
rb_thread_add_event_hook2(current_thread, (rb_event_hook_func_t)eval_trace_callback, RUBY_EVENT_CALL | RUBY_EVENT_C_CALL,
|
100
|
+
rb_thread_add_event_hook2(current_thread, (rb_event_hook_func_t)eval_trace_callback, RUBY_EVENT_CALL | RUBY_EVENT_C_CALL, evaluator, RUBY_EVENT_HOOK_FLAG_RAW_ARG | RUBY_EVENT_HOOK_FLAG_SAFE);
|
96
101
|
rb_hash_aset(thread_variables_hash, eval_trace_thread_flag, Qtrue);
|
97
102
|
}
|
98
103
|
|
@@ -103,8 +108,8 @@ void
|
|
103
108
|
Init_evaluator(VALUE mDebugger)
|
104
109
|
{
|
105
110
|
VALUE cBreakpoint = rb_define_class_under(mDebugger, "Breakpoint", rb_cObject);
|
106
|
-
VALUE
|
111
|
+
VALUE cEvaluator = rb_define_class_under(cBreakpoint, "Evaluator", rb_cObject);
|
107
112
|
|
108
|
-
rb_define_module_function(
|
109
|
-
rb_define_module_function(
|
113
|
+
rb_define_module_function(cEvaluator, "enable_method_trace_for_thread", rb_enable_method_trace_for_thread, 0);
|
114
|
+
rb_define_module_function(cEvaluator, "disable_method_trace_for_thread", rb_disable_method_trace_for_thread, 0);
|
110
115
|
}
|
@@ -20,6 +20,8 @@
|
|
20
20
|
|
21
21
|
gem "google-cloud-core"
|
22
22
|
require "google/cloud"
|
23
|
+
require "google/cloud/config"
|
24
|
+
require "googleauth"
|
23
25
|
|
24
26
|
module Google
|
25
27
|
module Cloud
|
@@ -42,6 +44,8 @@ module Google
|
|
42
44
|
# The default scope is:
|
43
45
|
#
|
44
46
|
# * `https://www.googleapis.com/auth/cloud_debugger`
|
47
|
+
# * `https://www.googleapis.com/auth/logging.admin`
|
48
|
+
#
|
45
49
|
# @param [Integer] timeout Default timeout to use in requests. Optional.
|
46
50
|
# @param [Hash] client_config A hash of values to override the default
|
47
51
|
# behavior of the API client. Optional.
|
@@ -97,6 +101,8 @@ module Google
|
|
97
101
|
# The default scope is:
|
98
102
|
#
|
99
103
|
# * `https://www.googleapis.com/auth/cloud_debugger`
|
104
|
+
# * `https://www.googleapis.com/auth/logging.admin`
|
105
|
+
#
|
100
106
|
# @param [Integer] timeout Default timeout to use in requests. Optional.
|
101
107
|
# @param [Hash] client_config A hash of values to override the default
|
102
108
|
# behavior of the API client. Optional.
|
@@ -123,3 +129,52 @@ module Google
|
|
123
129
|
end
|
124
130
|
end
|
125
131
|
end
|
132
|
+
|
133
|
+
# Add debugger to top-level configuration
|
134
|
+
Google::Cloud.configure do |config|
|
135
|
+
unless config.field? :use_debugger
|
136
|
+
config.add_field! :use_debugger, nil, enum: [true, false]
|
137
|
+
end
|
138
|
+
unless config.field? :service_name
|
139
|
+
config.add_field! :service_name, nil, match: String
|
140
|
+
end
|
141
|
+
unless config.field? :service_version
|
142
|
+
config.add_field! :service_version, nil, match: String
|
143
|
+
end
|
144
|
+
end
|
145
|
+
|
146
|
+
# Set the default debugger configuration
|
147
|
+
Google::Cloud.configure.add_config! :debugger do |config|
|
148
|
+
default_project = Google::Cloud::Config.deferred do
|
149
|
+
ENV["DEBUGGER_PROJECT"]
|
150
|
+
end
|
151
|
+
default_creds = Google::Cloud::Config.deferred do
|
152
|
+
Google::Cloud::Config.credentials_from_env \
|
153
|
+
"DEBUGGER_CREDENTIALS", "DEBUGGER_CREDENTIALS_JSON",
|
154
|
+
"DEBUGGER_KEYFILE", "DEBUGGER_KEYFILE_JSON"
|
155
|
+
end
|
156
|
+
default_service = Google::Cloud::Config.deferred do
|
157
|
+
ENV["DEBUGGER_SERVICE_NAME"]
|
158
|
+
end
|
159
|
+
default_version = Google::Cloud::Config.deferred do
|
160
|
+
ENV["DEBUGGER_SERVICE_VERSION"]
|
161
|
+
end
|
162
|
+
|
163
|
+
config.add_field! :project_id, default_project, match: String, allow_nil: true
|
164
|
+
config.add_alias! :project, :project_id
|
165
|
+
config.add_field! :credentials, default_creds,
|
166
|
+
match: [String, Hash, Google::Auth::Credentials],
|
167
|
+
allow_nil: true
|
168
|
+
config.add_alias! :keyfile, :credentials
|
169
|
+
config.add_field! :service_name, default_service,
|
170
|
+
match: String, allow_nil: true
|
171
|
+
config.add_field! :service_version, default_version,
|
172
|
+
match: String, allow_nil: true
|
173
|
+
config.add_field! :app_root, nil, match: String
|
174
|
+
config.add_field! :root, nil, match: String
|
175
|
+
config.add_field! :scope, nil, match: [String, Array]
|
176
|
+
config.add_field! :timeout, nil, match: Integer
|
177
|
+
config.add_field! :client_config, nil, match: Hash
|
178
|
+
config.add_field! :allow_mutating_methods, false
|
179
|
+
config.add_field! :evaluation_time_limit, 0.05, match: Numeric
|
180
|
+
end
|
@@ -15,6 +15,8 @@
|
|
15
15
|
|
16
16
|
require "google-cloud-debugger"
|
17
17
|
require "google/cloud/debugger/project"
|
18
|
+
require "google/cloud/config"
|
19
|
+
require "google/cloud/env"
|
18
20
|
require "stackdriver/core"
|
19
21
|
|
20
22
|
module Google
|
@@ -320,15 +322,7 @@ module Google
|
|
320
322
|
# See {Google::Cloud::Debugger::V2::Debugger2Client} for details.
|
321
323
|
#
|
322
324
|
module Debugger
|
323
|
-
#
|
324
|
-
# Google::Cloud if haven't already
|
325
|
-
unless Google::Cloud.configure.option? :debugger
|
326
|
-
Google::Cloud.configure.add_options :debugger
|
327
|
-
|
328
|
-
Google::Cloud.configure.define_singleton_method :debugger do
|
329
|
-
Google::Cloud.configure[:debugger]
|
330
|
-
end
|
331
|
-
end
|
325
|
+
# rubocop:disable all
|
332
326
|
|
333
327
|
##
|
334
328
|
# Creates a new debugger object for instrumenting Stackdriver Debugger for
|
@@ -353,8 +347,15 @@ module Google
|
|
353
347
|
# the set of resources and operations that the connection can access.
|
354
348
|
# See [Using OAuth 2.0 to Access Google
|
355
349
|
# APIs](https://developers.google.com/identity/protocols/OAuth2).
|
356
|
-
#
|
350
|
+
#
|
351
|
+
# The default scope is:
|
352
|
+
#
|
353
|
+
# * `https://www.googleapis.com/auth/cloud_debugger`
|
354
|
+
# * `https://www.googleapis.com/auth/logging.admin`
|
355
|
+
#
|
357
356
|
# @param [Integer] timeout Default timeout to use in requests. Optional.
|
357
|
+
# @param [Hash] client_config A hash of values to override the default
|
358
|
+
# behavior of the API client. Optional.
|
358
359
|
# @param [String] project Project identifier for the Stackdriver Debugger
|
359
360
|
# service.
|
360
361
|
# @param [String, Hash] keyfile Keyfile downloaded from Google Cloud:
|
@@ -371,18 +372,26 @@ module Google
|
|
371
372
|
def self.new project_id: nil, credentials: nil, service_name: nil,
|
372
373
|
service_version: nil, scope: nil, timeout: nil,
|
373
374
|
client_config: nil, project: nil, keyfile: nil
|
374
|
-
project_id ||= (project ||
|
375
|
+
project_id ||= (project || default_project_id)
|
375
376
|
project_id = project_id.to_s # Always cast to a string
|
376
|
-
|
377
|
+
|
378
|
+
service_name ||= default_service_name
|
377
379
|
service_name = service_name.to_s
|
378
|
-
|
380
|
+
|
381
|
+
service_version ||= default_service_version
|
379
382
|
service_version = service_version.to_s
|
380
383
|
|
381
|
-
|
382
|
-
|
383
|
-
|
384
|
+
raise ArgumentError, "project_id is missing" if project_id.empty?
|
385
|
+
raise ArgumentError, "service_name is missing" if service_name.empty?
|
386
|
+
if service_version.nil?
|
387
|
+
raise ArgumentError, "service_version is missing"
|
388
|
+
end
|
389
|
+
|
390
|
+
scope ||= configure.scope
|
391
|
+
timeout ||= configure.timeout
|
392
|
+
client_config ||= configure.client_config
|
384
393
|
|
385
|
-
credentials ||= (keyfile ||
|
394
|
+
credentials ||= (keyfile || default_credentials(scope: scope))
|
386
395
|
unless credentials.is_a? Google::Auth::Credentials
|
387
396
|
credentials = Debugger::Credentials.new credentials, scope: scope
|
388
397
|
end
|
@@ -391,23 +400,132 @@ module Google
|
|
391
400
|
Debugger::Service.new(project_id, credentials,
|
392
401
|
timeout: timeout, client_config: client_config),
|
393
402
|
service_name: service_name,
|
394
|
-
service_version: service_version
|
403
|
+
service_version: service_version
|
404
|
+
)
|
395
405
|
end
|
396
406
|
|
407
|
+
# rubocop:enable all
|
408
|
+
|
397
409
|
##
|
398
410
|
# Configure the Stackdriver Debugger agent.
|
399
411
|
#
|
412
|
+
# The following Stackdriver Debugger configuration parameters are
|
413
|
+
# supported:
|
414
|
+
#
|
415
|
+
# * `project_id` - (String) Project identifier for the Stackdriver
|
416
|
+
# Debugger service you are connecting to. (The parameter `project` is
|
417
|
+
# considered deprecated, but may also be used.)
|
418
|
+
# * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
|
419
|
+
# the keyfile as a String, the contents of the keyfile as a Hash, or a
|
420
|
+
# Google::Auth::Credentials object. (See {Debugger::Credentials}) (The
|
421
|
+
# parameter `keyfile` is considered deprecated, but may also be used.)
|
422
|
+
# * `service_name` - (String) Name for the debuggee application.
|
423
|
+
# * `service_version` - (String) Version identifier for the debuggee
|
424
|
+
# application.
|
425
|
+
# * `root` - (String) The root directory of the debuggee application as an
|
426
|
+
# absolute file path.
|
427
|
+
# * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
|
428
|
+
# the set of resources and operations that the connection can access.
|
429
|
+
# * `timeout` - (Integer) Default timeout to use in requests.
|
430
|
+
# * `client_config` - (Hash) A hash of values to override the default
|
431
|
+
# behavior of the API client.
|
432
|
+
# * `allow_mutating_methods` - (boolean) Whether expressions and
|
433
|
+
# conditional breakpoints can call methods that could modify program
|
434
|
+
# state. Defaults to false.
|
435
|
+
# * `evaluation_time_limit` - (Numeric) Time limit in seconds for
|
436
|
+
# expression evaluation. Defaults to 0.05.
|
437
|
+
#
|
400
438
|
# See the [Configuration
|
401
439
|
# Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
|
402
440
|
# for full configuration parameters.
|
403
441
|
#
|
404
|
-
# @return [
|
405
|
-
#
|
442
|
+
# @return [Google::Cloud::Config] The configuration object the
|
443
|
+
# Google::Cloud::Debugger module uses.
|
406
444
|
#
|
407
445
|
def self.configure
|
408
|
-
yield Google::Cloud.configure
|
446
|
+
yield Google::Cloud.configure.debugger if block_given?
|
447
|
+
|
448
|
+
Google::Cloud.configure.debugger
|
449
|
+
end
|
450
|
+
|
451
|
+
##
|
452
|
+
# @private Default project.
|
453
|
+
def self.default_project_id
|
454
|
+
Google::Cloud.configure.debugger.project_id ||
|
455
|
+
Google::Cloud.configure.project_id ||
|
456
|
+
Google::Cloud.env.project_id
|
457
|
+
end
|
409
458
|
|
410
|
-
|
459
|
+
##
|
460
|
+
# @private Default service name identifier.
|
461
|
+
def self.default_service_name
|
462
|
+
Google::Cloud.configure.debugger.service_name ||
|
463
|
+
Google::Cloud.configure.service_name ||
|
464
|
+
Google::Cloud.env.app_engine_service_id ||
|
465
|
+
"ruby-app"
|
466
|
+
end
|
467
|
+
|
468
|
+
##
|
469
|
+
# @private Default service version identifier.
|
470
|
+
def self.default_service_version
|
471
|
+
Google::Cloud.configure.debugger.service_version ||
|
472
|
+
Google::Cloud.configure.service_version ||
|
473
|
+
Google::Cloud.env.app_engine_service_version ||
|
474
|
+
""
|
475
|
+
end
|
476
|
+
|
477
|
+
##
|
478
|
+
# @private Default credentials.
|
479
|
+
def self.default_credentials scope: nil
|
480
|
+
Google::Cloud.configure.debugger.credentials ||
|
481
|
+
Google::Cloud.configure.credentials ||
|
482
|
+
Debugger::Credentials.default(scope: scope)
|
483
|
+
end
|
484
|
+
|
485
|
+
##
|
486
|
+
# Allow calling of potentially state-changing methods even if mutation
|
487
|
+
# detection is configured to be active.
|
488
|
+
#
|
489
|
+
# Generally it is unwise to run code that may change the program state
|
490
|
+
# (e.g. modifying instance variables or causing other side effects) in a
|
491
|
+
# breakpoint expression, because it could change the behavior of your
|
492
|
+
# program. However, the checks are currently quite conservative, and may
|
493
|
+
# block code that is actually safe to run. If you are certain your
|
494
|
+
# expression is safe to evaluate, you may use this method to disable
|
495
|
+
# side effect checks.
|
496
|
+
#
|
497
|
+
# This method may be called with a block, in which case checks are
|
498
|
+
# disabled within the block. It may also be called without a block to
|
499
|
+
# disable side effect checks for the rest of the current expression; the
|
500
|
+
# default setting will be restored for the next expression.
|
501
|
+
#
|
502
|
+
# This method may be called only from a debugger condition or expression
|
503
|
+
# evaluation, and will throw an exception if you call it from normal
|
504
|
+
# application code. Set the `allow_mutating_methods` configuration if you
|
505
|
+
# want to disable the side effect checker globally for your app.
|
506
|
+
#
|
507
|
+
# @example Disabling side effect detection in a block
|
508
|
+
# # This is an expression evaluated in a debugger snapshot
|
509
|
+
# Google::Cloud::Debugger.allow_mutating_methods! do
|
510
|
+
# obj1.method_with_potential_side_effects
|
511
|
+
# end
|
512
|
+
#
|
513
|
+
# @example Disabling side effect detection for the rest of the expression
|
514
|
+
# # This is an expression evaluated in a debugger snapshot
|
515
|
+
# Google::Cloud::Debugger.allow_mutating_methods!
|
516
|
+
# obj1.method_with_potential_side_effects
|
517
|
+
# obj2.another_method_with_potential_side_effects
|
518
|
+
#
|
519
|
+
# @example Globally disabling side effect detection at app initialization
|
520
|
+
# require "google/cloud/debugger"
|
521
|
+
# Google::Cloud::Debugger.configure.allow_mutating_methods = true
|
522
|
+
#
|
523
|
+
def self.allow_mutating_methods! &block
|
524
|
+
evaluator = Breakpoint::Evaluator.current
|
525
|
+
if evaluator.nil?
|
526
|
+
raise "allow_mutating_methods can be called only during evaluation"
|
527
|
+
end
|
528
|
+
evaluator.allow_mutating_methods!(&block)
|
411
529
|
end
|
412
530
|
end
|
413
531
|
end
|