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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8eec075346b0460efd9940071568dd622d2ffb7685bedf218d186925d5cc7993
4
- data.tar.gz: ab048f08b20449c6aa81d4a73bc081933d803f722a96d22eb4a0c5b64a589142
3
+ metadata.gz: 71f28cd2cdbb26aeb952111ceed9989d726fe066c7b42b15dc6abc01b77c6d80
4
+ data.tar.gz: 212961fe1b440ca8934468eedc899ce0304523443944fd4e882e7d07bca60157
5
5
  SHA512:
6
- metadata.gz: 15052121b82c76b080c552b4036ca7ce22ecdfd84ad5071d6a587ed4a0d25f684bd9c6e58e2a5cd50884b70004bfaa22dfd4ba0ccaa60d49bb6d5b0a1dd1c85e
7
- data.tar.gz: b7849a9d1e71d1acea6b253668260eadd39541534c4ce9084a55373fbe037da8c1060196d86ff19f1eca8d72b4d41deaff167147a54ada0043ebfc5ce1e77c6f
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 state of a running application at any code location in real time, without stopping or slowing down the application, and without modifying the code to add logging statements. You can use Stackdriver Debugger with any deployment of your application, including test, development, and production. The Ruby debugger adds minimal request latency, typically less than 50ms, and only when the application state is captured. In most cases, this is not noticeable by users.
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
- Install the gem directly:
17
+ ### Installing the gem
12
18
 
13
- ```sh
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
- 2. Use Bundler to install the gem:
26
-
27
- ```sh
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
- Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes
32
- the `google-cloud-debugger` gem.
29
+ ### Initializing the Debugger
33
30
 
34
- ## Enable Stackdriver Debugger API
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
- The Stackdriver Debugger agent needs the [Stackdriver Debugger
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
- ### With other Rack-based frameworks
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
- ### Without Rack-based framework
61
+ #### Setup without a Rack-based framework
72
62
 
73
- Non-rack-based applications can start the agent explicitly at the entry point of
74
- your application:
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
- ### Configuring the agent
71
+ ### Connecting to the Debugger
82
72
 
83
- You can customize the behavior of the Stackdriver Debugger agent. See the
84
- [agent configuration](../stackdriver/docs/configuration.md) for a list of
85
- possible configuration options.
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
- ## Running on Google Cloud Platform
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
- The Stackdriver Debugger agent should work without you manually providing
90
- authentication credentials for instances running on Google Cloud Platform, as
91
- long as the Stackdriver Debugger API access scope is enabled on that instance.
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
- ### App Engine
87
+ #### Connecting from Google App Engine (GAE)
94
88
 
95
- On Google App Engine, the Stackdriver Debugger API access scope is enabled by
96
- default, and the Stackdriver Debugger agent can be used without providing
97
- credentials or a project ID.
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
- ### Container Engine
93
+ #### Connecting from Google Kubernetes Engine (GKE)
100
94
 
101
- On Google Container Engine, you must explicitly add the `cloud_debugger` OAuth
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
- ### Compute Engine
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
- To use Stackdriver Debugger, Compute Engine VM instances should have one of the
114
- following access scopes. These are only relevant when you use Compute Engine's
115
- default service account:
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 must be supplied manually using the SDK's
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
- ## Running locally and elsewhere
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. See the [Authentication section](#authentication) for
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.keyfile = "/path/to/key.json"
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.keyfile = "/path/to/key.json"
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 use
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.keyfile = "/path/to/key.json"
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.keyfile = "/path/to/key.json"
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
- ## Supported Ruby Versions
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
- This library is supported on Ruby 2.2+.
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
- ## Versioning
225
+ ## Compatibility
192
226
 
193
- This library follows [Semantic Versioning](http://semver.org/).
227
+ This library is supported on Ruby 2.2 or later.
194
228
 
195
- It is currently in major version zero (0.y.z), which means that anything may change at any time and the public API should not be considered stable.
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 = rb_tracearg_event_flag(trace_arg);
25
- VALUE evaluator = (VALUE)data;
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, 2, obj, method_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, self, RUBY_EVENT_HOOK_FLAG_RAW_ARG | RUBY_EVENT_HOOK_FLAG_SAFE);
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 mEvaluator = rb_define_module_under(cBreakpoint, "Evaluator");
111
+ VALUE cEvaluator = rb_define_class_under(cBreakpoint, "Evaluator", rb_cObject);
107
112
 
108
- rb_define_module_function(mEvaluator, "enable_method_trace_for_thread", rb_enable_method_trace_for_thread, 0);
109
- rb_define_module_function(mEvaluator, "disable_method_trace_for_thread", rb_disable_method_trace_for_thread, 0);
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
- # Initialize :error_reporting as a nested Configuration under
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
- # The default scope is `https://www.googleapis.com/auth/cloud-platform`
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 || Debugger::Project.default_project_id)
375
+ project_id ||= (project || default_project_id)
375
376
  project_id = project_id.to_s # Always cast to a string
376
- service_name ||= Debugger::Project.default_service_name
377
+
378
+ service_name ||= default_service_name
377
379
  service_name = service_name.to_s
378
- service_version ||= Debugger::Project.default_service_version
380
+
381
+ service_version ||= default_service_version
379
382
  service_version = service_version.to_s
380
383
 
381
- fail ArgumentError, "project_id is missing" if project_id.empty?
382
- fail ArgumentError, "service_name is missing" if service_name.empty?
383
- fail ArgumentError, "service_version is missing" if service_version.nil?
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 || Debugger::Credentials.default(scope: scope))
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 [Stackdriver::Core::Configuration] The configuration object
405
- # the Google::Cloud::ErrorReporting module uses.
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[:debugger] if block_given?
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
- Google::Cloud.configure[:debugger]
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