google-cloud-debugger 0.28.1 → 0.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c830b378b4d42961196533588aaf0c9de64d777
-  data.tar.gz: 8c7f28747d36f7a912d91f70864450ef7d53f044
+  metadata.gz: 4f6c7702998c26106d5d7d8c9da1da90a23a85a9
+  data.tar.gz: 9e792c21da0a3224c17df88921f635eddbdd8b90
 SHA512:
-  metadata.gz: 1f69ee4d95699271c7c03cfc34568e6110b9d43c265c89c367c88b80ce3e2709be02135185eec68fafcd1425f7b1caa70e9219136b57fb4a295f1b7242832717
-  data.tar.gz: d60ae09e0b72d201533acd290631f18331ab9bbeefd6a963f5fc9e521732db07df6fc93aebfa54017f534084949efa6c70cb1e0ad4232c0d7c9851ce9ac4ea2e
+  metadata.gz: 10b6cf1fbdfa245b73e5d40f83736e5e74444060484d13a18352be3ffcbb14dc0cba4fa9502e845b82874f04bde6ccce2eb52b56e2ebcdb0ee04d57c62526754
+  data.tar.gz: 4e249d586c912cc55b971547268b5ab79fe975892c84ac5e24e46eb29a98749e8b4f21155815f9b735515fbf70f525eb41779c072532e80d4c7f628ab694b3b5

data/README.md

@@ -1,6 +1,6 @@
 # google-cloud-debugger
 
-[Stackdriver Debugger](https://cloud.google.com/debugger/) ([docs](https://cloud.google.com/debugger/docs/)) 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.
+[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.
 
 - [google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger)
 - [google-cloud-debugger on RubyGems](https://rubygems.org/gems/google-cloud-debugger)
@@ -8,25 +8,181 @@
 
 ## Quick Start
 
-Setting up Stackdriver Debugger involves three steps:
+Install the gem directly:
 
-1. Add the `google-cloud-debugger` library to your app.
-2. Register your app's source code.
-3. Deploy your app and set a breakpoint.
+```sh
+$ gem install google-cloud-debugger
+```
 
-See the
-[google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger)
-for a quick tutorial.
+Or install through Bundler:
 
-## Authentication
+1. Add the `google-cloud-debugger` gem to your Gemfile:
+
+```ruby
+gem "google-cloud-debugger"
+```
+
+2. Use Bundler to install the gem:
+
+```sh
+$ bundle install
+```
+
+Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes 
+the `google-cloud-debugger` gem.
+
+## Enable Stackdriver Debugger API
+
+The Stackdriver Debugger agent needs the [Stackdriver Debugger 
+API](https://console.cloud.google.com/apis/library/clouddebugger.googleapis.com) 
+to be enabled on your Google Cloud project. Make sure it's enabled if not 
+already.
+
+## Enabling the Debugger agent
+
+The Stackdriver Debugger library provides a Debugger agent that helps instrument
+breakpoints in your running applications. The library also comes with a Railtie
+and a Rack Middleware to help control the Debugger agent in popular Rack based
+frameworks, such as Ruby on Rails and Sinatra.
+
+### With Ruby on Rails
+
+You can load the Railtie that comes with the library into your Ruby 
+on Rails application by explicitly requiring it during the application startup:
+
+```ruby
+# In config/application.rb
+require "google/cloud/debugger/rails"
+```
+
+If you're using the `stackdriver` gem, it automatically loads the Railtie into 
+your application when it starts.
+
+### With other Rack-based frameworks
+
+Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware 
+provided by the library:
+
+```ruby
+require "google/cloud/debugger"
+use Google::Cloud::Debugger::Middleware
+```
+
+### Without Rack-based framework
+
+Non-rack-based applications can start the agent explicitly at the entry point of
+your application:
 
-This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine the credentials will be discovered automatically. When running on other environments the Service Account credentials can be specified by providing the path to the JSON file, or the JSON itself, in environment variables.
+```ruby
+require "google/cloud/debugger"
+Google::Cloud::Debugger.new.start
+```
 
-Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
+### Configuring the agent
 
-## Usage
+You can customize the behavior of the Stackdriver Debugger agent. See the 
+[agent configuration](../stackdriver/docs/configuration.md) for a list of 
+possible configuration options.
+
+## Running on Google Cloud Platform
+
+The Stackdriver Debugger agent should work without you manually providing 
+authentication credentials for instances running on Google Cloud Platform, as 
+long as the Stackdriver Debugger API access scope is enabled on that instance.
+
+### App Engine
+
+On Google App Engine, the Stackdriver Debugger API access scope is enabled by 
+default, and the Stackdriver Debugger agent can be used without providing 
+credentials or a project ID.
+
+### Container Engine
+
+On Google Container Engine, you must explicitly add the `cloud_debugger` OAuth 
+scope when creating the cluster:
+
+```sh
+$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud_debugger
+```
+
+You can also do this through the Google Cloud Platform Console. Select 
+**Enabled** in the Cloud Platform section of **Create a container cluster**.
+
+### Compute Engine
+
+To use Stackdriver Debugger, Compute Engine VM instances should have one of the 
+following access scopes. These are only relevant when you use Compute Engine's 
+default service account:
+
+* `https://www.googleapis.com/auth/cloud-platform`
+* `https://www.googleapis.com/auth/cloud_debugger`
+
+The `cloud-platform` access scope can be supplied when creating a new instance 
+through the Google Cloud Platform Console. Select **Allow full access to all 
+Cloud APIs** in the **Identity and API access** section of **Create an 
+instance**.
+
+The `cloud_debugger` access scope must be supplied manually using the SDK's 
+`gcloud compute instances create` command or the `gcloud compute instances 
+set-service-account` command.
+
+## Running locally and elsewhere
+
+To run the Stackdriver Debugger agent outside of Google Cloud Platform, you must 
+supply your GCP project ID and appropriate service account credentials directly 
+to the Stackdriver Debugger agent. This applies to running the agent on your own 
+workstation, on your datacenter's computers, or on the VM instances of another 
+cloud provider. See the [Authentication section](#authentication) for 
+instructions on how to do so.
+
+## Authentication
 
-This library provides a Stackdriver Debugger Agent that's able to work with Ruby applications. It also integrates with Ruby on Rails and other popular Rack-based frameworks. See the [Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/instrumentation) for more details.
+This library uses Service Account credentials to connect to Google Cloud
+services. When running on Compute Engine the credentials will be discovered 
+automatically. When running on other environments the Service Account 
+credentials can be specified by providing in several ways.
+
+The best way to provide authentication information if you're using Ruby on Rails
+is through the Rails configuration interface:
+
+```ruby
+# in config/environments/*.rb
+Rails.application.configure do |config|
+  # Shared parameters
+  config.google_cloud.project_id = "your-project-id"
+  config.google_cloud.keyfile = "/path/to/key.json"
+  # Or Stackdriver Debugger agent specific parameters
+  config.google_cloud.debugger.project_id = "your-project-id"
+  config.google_cloud.debugger.keyfile = "/path/to/key.json"
+end
+```
+
+Other Rack-based applications that are loading the Rack Middleware directly can use
+the configration interface:
+ 
+```ruby
+require "google/cloud/debugger"
+Google::Cloud.configure do |config|
+  # Shared parameters
+  config.project_id = "your-project-id"
+  config.keyfile = "/path/to/key.json"
+  # Or Stackdriver Debugger agent specific parameters
+  config.debugger.project_id = "your-project-id"
+  config.debugger.keyfile = "/path/to/key.json"
+end
+```
+
+Or provide the parameters to the Stackdriver Debugger agent when it starts:
+
+```ruby
+require "google/cloud/debugger"
+Google::Cloud::Debugger.new(project_id: "your-project-id",
+                            keyfile: "/path/to/key.json").start
+```
+
+This library also supports the other authentication methods provided by the 
+`google-cloud-ruby` suite. Instructions and configuration options are covered 
+in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
 
 ## Supported Ruby Versions
 

data/ext/google/cloud/debugger/debugger_c/tracer.c

@@ -18,6 +18,13 @@
 #include "ruby/debug.h"
 #include "tracer.h"
 
+#define FILE_TRACEPOINT_EVENTS (RUBY_EVENT_CLASS | RUBY_EVENT_CALL | RUBY_EVENT_B_CALL)
+#define RETURN_TRACEPOINT_EVENTS (RUBY_EVENT_END | RUBY_EVENT_RETURN | RUBY_EVENT_B_RETURN)
+#define FIBER_TRACEPOINT_EVENT RUBY_EVENT_FIBER_SWITCH
+
+/* To prevent unused parameter warnings */
+#define UNUSED(x) (void)(x)
+
 /**
  *  hash_get_keys_callback
  *  Helper callback function for hash_get_keys.
@@ -259,7 +266,7 @@ enable_line_trace_for_thread(VALUE self)
 /**
  * return_trace_callback
  * Callback function for tracer#return_tracepoint. It gets called on
- * RUBY_EVENT_END, RUBY_EVENT_RETURN, RUBY_EVENT_C_RETURN, and
+ * RUBY_EVENT_END, RUBY_EVENT_RETURN, and
  * RUBY_EVENT_B_RETURN events. It keeps line tracing consistent when Ruby
  * program counter interleaves files. Everytime called, it checks caller stack
  * frame's file path, if it matches any of the breakpoints, it turns line
@@ -375,8 +382,7 @@ enable_return_trace_for_thread(VALUE self)
     return_trace_set = rb_hash_aref(thread_variables_hash, return_trace_thread_flag);
 
     if (!RTEST(return_trace_set)) {
-        int return_tracepoint_event = RUBY_EVENT_END | RUBY_EVENT_RETURN | RUBY_EVENT_C_RETURN | RUBY_EVENT_B_RETURN;
-        rb_thread_add_event_hook2(current_thread, (rb_event_hook_func_t)return_trace_callback, return_tracepoint_event, self, RUBY_EVENT_HOOK_FLAG_RAW_ARG | RUBY_EVENT_HOOK_FLAG_SAFE);
+        rb_thread_add_event_hook2(current_thread, (rb_event_hook_func_t)return_trace_callback, RETURN_TRACEPOINT_EVENTS, self, RUBY_EVENT_HOOK_FLAG_RAW_ARG | RUBY_EVENT_HOOK_FLAG_SAFE);
         rb_hash_aset(thread_variables_hash, return_trace_thread_flag, Qtrue);
     }
 
@@ -386,7 +392,7 @@ enable_return_trace_for_thread(VALUE self)
 /**
  * file_tracepoint_callback
  * Callback function for tracer#file_tracepoint. It gets called on
- * RUBY_EVENT_CLASS, RUBY_EVENT_CALL, RUBY_EVENT_C_CALL, and RUBY_EVENT_B_CALL
+ * RUBY_EVENT_CLASS, RUBY_EVENT_CALL, and RUBY_EVENT_B_CALL
  * events. It check if any breakpoints matches current file the VM program counter
  * is in, and turn on line event tracing for that thread. Otherwise turn off
  * line tracing if in wrong file. The first time it turns on line even tracing,
@@ -523,7 +529,7 @@ rb_enable_traces(VALUE self)
     VALUE file_tracepoint;
     VALUE fiber_tracepoint;
 
-    file_tracepoint = register_tracepoint(self, FILE_TRACEPOINT_EVENT, "@file_tracepoint", file_tracepoint_callback);
+    file_tracepoint = register_tracepoint(self, FILE_TRACEPOINT_EVENTS, "@file_tracepoint", file_tracepoint_callback);
     UNUSED(fiber_tracepoint);
 
     // Immediately activate file tracepoint and fiber tracepoint

data/ext/google/cloud/debugger/debugger_c/tracer.h

@@ -19,12 +19,6 @@
 
 #include "ruby/debug.h"
 
-#define FILE_TRACEPOINT_EVENT (RUBY_EVENT_CLASS | RUBY_EVENT_CALL | RUBY_EVENT_C_CALL | RUBY_EVENT_B_CALL)
-#define FIBER_TRACEPOINT_EVENT RUBY_EVENT_FIBER_SWITCH
-
-/* To prevent unused parameter warnings */
-#define UNUSED(x) (void)(x)
-
 void
 Init_tracer(VALUE mDebugger);
 

data/lib/google/cloud/debugger/backoff.rb

@@ -0,0 +1,70 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # @private Helps keep tracking of backoff on calling APIs in loop
+      class Backoff
+        ##
+        # Small interval to start with
+        DEFAULT_START_INTERVAL = 1
+
+        ##
+        # Maximum interval value to use
+        DEFAULT_MAX_INTERVAL = 600
+
+        ##
+        # Interval incremental multiplier
+        DEFAULT_MULTIPLIER = 2
+
+        ##
+        # The current time interval should wait until next iteration
+        attr_reader :interval
+
+        def initialize start_interval = DEFAULT_START_INTERVAL,
+                       max_interval = DEFAULT_MAX_INTERVAL,
+                       multiplier = DEFAULT_MULTIPLIER
+          @start_interval = start_interval
+          @max_interval = max_interval
+          @multiplier = multiplier
+        end
+
+        ##
+        # Resets backoff
+        def succeeded
+          @interval = nil
+        end
+
+        ##
+        # Initialize backoff or increase backoff interval
+        def failed
+          @interval = if @interval
+                        [@max_interval, @interval * @multiplier].min
+                      else
+                        @start_interval
+                      end
+        end
+
+        ##
+        # Check if a backoff delay should be applied
+        def backing_off?
+          !@interval.nil?
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/debugger/debuggee.rb

@@ -14,6 +14,7 @@
 
 
 require "digest/sha1"
+require "google/cloud/debugger/backoff"
 require "google/cloud/debugger/debuggee/app_uniquifier_generator"
 require "google/cloud/debugger/version"
 require "json"
@@ -69,6 +70,7 @@ module Google
           @service_version = service_version
           @computed_uniquifier = nil
           @id = nil
+          @register_backoff = Google::Cloud::Debugger::Backoff.new
         end
 
         ##
@@ -76,13 +78,20 @@ module Google
         # Debuggee service.
         # @return [Boolean] True if registered sucessfully; otherwise false.
         def register
+          # Wait if backoff applies
+          sleep @register_backoff.interval if @register_backoff.backing_off?
+
           begin
             response = service.register_debuggee to_grpc
             @id = response.debuggee.id
           rescue
             revoke_registration
           end
-          registered?
+
+          registered = registered?
+          registered ? @register_backoff.succeeded : @register_backoff.failed
+
+          registered
         end
 
         ##

data/lib/google/cloud/debugger/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Debugger
-      VERSION = "0.28.1"
+      VERSION = "0.28.2"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-debugger
 version: !ruby/object:Gem::Version
-  version: 0.28.1
+  version: 0.28.2
 platform: ruby
 authors:
 - Heng Xiong
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-08 00:00:00.000000000 Z
+date: 2017-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
@@ -269,6 +269,7 @@ files:
 - lib/google-cloud-debugger.rb
 - lib/google/cloud/debugger.rb
 - lib/google/cloud/debugger/agent.rb
+- lib/google/cloud/debugger/backoff.rb
 - lib/google/cloud/debugger/breakpoint.rb
 - lib/google/cloud/debugger/breakpoint/evaluator.rb
 - lib/google/cloud/debugger/breakpoint/source_location.rb