google-cloud-debugger 0.40.0

data/LOGGING.md

@@ -0,0 +1,32 @@
+# Enabling gRPC Logging
+
+To enable logging for this library, set the logger for the underlying
+[gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
+that you set may be a Ruby stdlib
+[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+shown below, or a
+[`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
+that will write logs to [Stackdriver
+Logging](https://cloud.google.com/logging/). See
+[grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+and the gRPC
+[spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
+for additional information.
+
+Configuring a Ruby stdlib logger:
+
+```ruby
+require "logger"
+
+module MyLogger
+  LOGGER = Logger.new $stderr, level: Logger::WARN
+  def logger
+    LOGGER
+  end
+end
+
+# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+module GRPC
+  extend MyLogger
+end
+```

data/OVERVIEW.md

@@ -0,0 +1,266 @@
+# Stackdriver Debugger
+
+Stackdriver Debugger is a feature of the Google Cloud Platform that lets you
+inspect the state of an application at any code location without using logging
+statements and without stopping or slowing down your applications. Your users
+are not impacted during debugging. Using the production debugger you can capture
+the local variables and call stack and link it back to a specific line location
+in your source code. You can use this to analyze the production state of your
+application and understand the behavior of your code in production.
+
+For general information about Stackdriver Debugger, read [Stackdriver Debugger
+Documentation](https://cloud.google.com/debugger/docs/).
+
+The Stackdriver Debugger Ruby library, `google-cloud-debugger`, provides:
+
+* Easy-to-use debugger instrumentation that reports state data, such as value of
+  program variables and the call stack, to Stackdriver Debugger when the code at
+  a breakpoint location is executed in your Ruby application. See the
+  [instrumenting your app](#instrumenting-your-app) section for how to debug
+  your application, in both development and production.
+* An idiomatic Ruby API for registerying debuggee application, and querying or
+  manipulating breakpoints in registered Ruby debuggee application. See
+  [Debugger API](#stackdriver-debugger-api) section for an introduction to
+  Stackdriver Debugger API.
+
+## Instrumenting Your App
+
+This instrumentation library provides the following features to help you debug
+your applications in production:
+
+* Automatic application registration. It facilitates multiple running instances
+  of same version of application when hosted in production.
+* A background debugger agent that runs side-by-side with your application that
+  automatically collects state data when code is executed at breakpoint
+  locations.
+* A Rack middleware and Railtie that automatically manages the debugger agent
+  for Ruby on Rails and other Rack-based Ruby applications.
+
+When this library is configured in your running application, and the source code
+and breakpoints are setup through the Google Cloud Console, You'll be able to
+[interact](https://cloud.google.com/debugger/docs/debugging) with your
+application in real time through the [Stackdriver Debugger
+UI](https://console.cloud.google.com/debug?_ga=1.84295834.280814654.1476313407).
+This library also integrates with Google App Engine Flexible to make debuggee
+application configuration more seemless.
+
+Note that when no breakpoints are created, the debugger agent consumes very
+little resource and has no interference with the running application. Once
+breakpoints are created and depends on where the breakpoints are located, the
+debugger agent may add a little latency onto each request. The application
+performance will be back to normal after all breakpoints are finished being
+evaluated. Be aware the more breakpoints are created, or the harder to reach the
+breakpoints, the more resource the debugger agent would need to consume.
+
+### Using instrumentation with Ruby on Rails
+
+To install application instrumentation in your Ruby on Rails app, add this gem,
+`google-cloud-debugger`, to your Gemfile and update your bundle. Then add the
+following line to your `config/application.rb` file:
+
+```ruby
+require "google/cloud/debugger/rails"
+```
+
+This will load a Railtie that automatically integrates with the Rails framework
+by injecting a Rack middleware. The Railtie also takes in the following Rails
+configuration as parameter of the debugger agent initialization:
+
+```ruby
+# Explicitly enable or disable Stackdriver Debugger Agent
+config.google_cloud.use_debugger = true
+# Shared Google Cloud Platform project identifier
+config.google_cloud.project_id = "gcloud-project"
+# Google Cloud Platform project identifier for Stackdriver Debugger only
+config.google_cloud.debugger.project_id = "debugger-project"
+# Shared Google Cloud authentication json file
+config.google_cloud.keyfile = "/path/to/keyfile.json"
+# Google Cloud authentication json file for Stackdriver Debugger only
+config.google_cloud.debugger.keyfile = "/path/to/debugger/keyfile.json"
+# Stackdriver Debugger Agent service name identifier
+config.google_cloud.debugger.service_name = "my-ruby-app"
+# Stackdriver Debugger Agent service version identifier
+config.google_cloud.debugger.service_version = "v1"
+```
+
+See the {Google::Cloud::Debugger::Railtie} class for more information.
+
+### Using instrumentation with Sinatra
+
+To install application instrumentation in your Sinatra app, add this gem,
+`google-cloud-debugger`, to your Gemfile and update your bundle. Then add the
+following lines to your main application Ruby file:
+
+```ruby
+require "google/cloud/debugger"
+use Google::Cloud::Debugger::Middleware
+```
+
+This will install the debugger middleware in your application.
+
+Configuration parameters may also be passed in as arguments to Middleware.
+
+```ruby
+require "google/cloud/debugger"
+use Google::Cloud::Debugger::Middleware project: "debugger-project-id",
+                                        keyfile: "/path/to/keyfile.json",
+                                        service_name: "my-ruby-app",
+                                        service_version: "v1"
+```
+
+### Using instrumentation with other Rack-based frameworks
+
+To install application instrumentation in an app using another Rack-based web
+framework, add this gem, `google-cloud-debugger`, to your Gemfile and update
+your bundle. Then add install the debugger middleware in your middleware stack.
+In most cases, this means adding these lines to your `config.ru` Rack
+configuration file:
+
+```ruby
+require "google/cloud/debugger"
+use Google::Cloud::Debugger::Middleware
+```
+
+Some web frameworks have an alternate mechanism for modifying the middleware
+stack. Consult your web framework's documentation for more information.
+
+### The Stackdriver diagnostics suite
+
+The debugger library is part of the Stackdriver diagnostics suite, which also
+includes error reporting, log analysis, and tracing analysis. If you include the
+`stackdriver` gem in your Gemfile, this debugger library will be included
+automatically. In addition, if you include the `stackdriver` gem in an
+application using Ruby On Rails, the Railties will be installed automatically.
+See the documentation for the "stackdriver" gem for more details.
+
+## Stackdriver Debugger API
+
+This library also includes an easy to use Ruby client for the Stackdriver
+Debugger API. This API provides calls to register debuggee application, as well
+as creating or modifying breakpoints.
+
+For further information on the Debugger API, see
+{Google::Cloud::Debugger::Project}
+
+### Registering debuggee application
+
+```ruby
+require "google/cloud/debugger/v2"
+
+controller_client = Google::Cloud::Debugger::V2::Controller::Client.new
+debuggee = Google::Cloud::Debugger::V2::Debuggee.new
+response = controller_client.register_debuggee debuggee: debuggee
+debuggee_id = response.debuggee.id
+```
+See [Stackdriver Debugger Debuggee
+doc](https://cloud.google.com/debugger/api/reference/rpc/google.devtools.clouddebugger.v2#google.devtools.clouddebugger.v2.Debuggee)
+on fields necessary for registerying a debuggee.
+
+Upon successful registration, the response debuggee object will contain a
+debuggee_id that's later needed to interact with the other Stackdriver Debugger
+API.
+
+### List Active Breakpoints
+
+```ruby
+require "google/cloud/debugger/v2"
+
+controller_client = Google::Cloud::Debugger::V2::Controller::Client.new
+
+debuggee_id = ''
+response = controller_client.list_active_breakpoints debuggee_id: debuggee_id
+breakpoints = response.breakpoints
+```
+
+### Update Active Breakpoint
+
+Users can send custom snapshots for active breakpoints using this API.
+
+```ruby
+require "google/cloud/debugger/v2"
+
+controller_client = Google::Cloud::Debugger::V2::Controller::Client.new
+debuggee_id = ''
+breakpoint = Google::Cloud::Debugger::V2::Breakpoint.new
+response = controller_client.update_active_breakpoint(
+  debuggee_id: debuggee_id, breakpoint: breakpoint)
+```
+
+See [Stackdriver Debugger Breakpoint
+doc](https://cloud.google.com/debugger/api/reference/rpc/google.devtools.clouddebugger.v2#google.devtools.clouddebugger.v2.Breakpoint)
+for all available fields for breakpoint.
+
+### Set Breakpoint
+
+```ruby
+require "google/cloud/debugger/v2"
+
+debugger_client = Google::Cloud::Debugger::V2::Debugger::Client.new
+debuggee_id = ''
+breakpoint = Google::Cloud::Debugger::V2::Breakpoint.new
+client_version = ''
+response = debugger_client.set_breakpoint(
+  debuggee_id: debuggee_id, breakpoint: breakpoint,
+  client_version: client_version)
+```
+
+See [Stackdriver Debugger Breakpoint
+doc](https://cloud.google.com/debugger/api/reference/rpc/google.devtools.clouddebugger.v2#google.devtools.clouddebugger.v2.Breakpoint)
+for fields needed to specify breakpoint location.
+
+### Get Breakpoint
+
+```ruby
+require "google/cloud/debugger/v2"
+
+debugger_client = Google::Cloud::Debugger::V2::Debugger::Client.new
+debuggee_id = ''
+breakpoint_id = ''
+client_version = ''
+response = debugger_client.get_breakpoint(
+  debuggee_id: debuggee_id, breakpoint_id: breakpoint_id,
+  client_version: client_version)
+```
+
+### Delete Breakpoint
+
+```ruby
+require "google/cloud/debugger/v2"
+
+debugger_client = Google::Cloud::Debugger::V2::Debugger::Client.new
+debuggee_id = ''
+breakpoint_id = ''
+client_version = ''
+debugger_client.delete_breakpoint(
+  debuggee_id: debuggee_id, breakpoint_id: breakpoint_id,
+  client_version: client_version)
+```
+
+### List Breakpoints
+
+```ruby
+require "google/cloud/debugger/v2"
+
+debugger_client = Google::Cloud::Debugger::V2::Debugger::Client.new
+debuggee_id = ''
+client_version = ''
+response = debugger_client.list_breakpoints(
+  debuggee_id: debuggee_id, client_version: client_version)
+```
+
+### List Debuggees
+
+```ruby
+require "google/cloud/debugger/v2"
+
+debugger_client = Google::Cloud::Debugger::V2::Debugger::Client.new
+project = ''
+client_version = ''
+response = debugger_client.list_debuggees(
+  project: project, client_version: client_version)
+```
+
+## Additional information
+
+Stackdriver Debugger can be configured to use gRPC's logging. To learn more, see
+the {file:LOGGING.md Logging guide}.

data/TROUBLESHOOTING.md

@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## Where can I get more help?
+
+### Ask the Community
+
+If you have a question about how to use a Google Cloud client library in your
+project or are stuck in the Developer's console and don't know where to turn,
+it's possible your questions have already been addressed by the community.
+
+First, check out the appropriate tags on StackOverflow:
+  - [`google-cloud-platform+ruby+debugger`][so-ruby]
+
+Next, try searching through the issues on GitHub:
+
+  - [`api:debugger` issues][gh-search-ruby]
+
+Still nothing?
+
+### Ask the Developers
+
+If you're experiencing a bug with the code, or have an idea for how it can be
+improved, *please* create a new issue on GitHub so we can talk about it.
+
+  - [New issue][gh-ruby]
+
+[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+debugger
+
+[gh-search-ruby]: https://github.com/googleapis/google-cloud-ruby/issues?q=label%3A%22api%3A+debugger%22
+
+[gh-ruby]: https://github.com/googleapis/google-cloud-ruby/issues/new

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

@@ -0,0 +1,31 @@
+/*
+    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
+
+        https://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.
+*/
+
+#include "ruby/ruby.h"
+#include "debugger.h"
+
+static VALUE mGoogle, mCloud, mDebugger;
+
+void
+Init_debugger_c()
+{
+    mGoogle = rb_define_module("Google");
+    mCloud = rb_define_module_under(mGoogle, "Cloud");
+    mDebugger = rb_define_module_under(mCloud, "Debugger");
+
+    Init_tracer(mDebugger);
+    Init_evaluator(mDebugger);
+}

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

@@ -0,0 +1,26 @@
+/*
+    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
+
+        https://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.
+*/
+
+#ifndef GOOGLE_CLOUD_RUBY_DEBUGGER_H_
+#define GOOGLE_CLOUD_RUBY_DEBUGGER_H_
+
+#include "tracer.h"
+#include "evaluator.h"
+
+void
+Init_debugger_c();
+
+#endif // GOOGLE_CLOUD_RUBY_DEBUGGER_H_

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

@@ -0,0 +1,115 @@
+/*
+    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
+
+        https://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.
+*/
+
+#include "ruby/ruby.h"
+#include "ruby/debug.h"
+#include "evaluator.h"
+
+static void
+eval_trace_callback(void *data, rb_trace_arg_t *trace_arg)
+{
+    rb_event_flag_t event;
+    VALUE evaluator;
+    VALUE klass;
+    VALUE obj;
+    VALUE method_id;
+    ID trace_func_cb_id;
+    ID trace_c_func_cb_id;
+
+    CONST_ID(trace_func_cb_id, "trace_func_callback");
+    CONST_ID(trace_c_func_cb_id, "trace_c_func_callback");
+
+    event = rb_tracearg_event_flag(trace_arg);
+    evaluator = (VALUE)data;
+    obj = rb_tracearg_self(trace_arg);
+    method_id = rb_tracearg_method_id(trace_arg);
+    klass = rb_tracearg_defined_class(trace_arg);
+
+    if (event & RUBY_EVENT_CALL) {
+        rb_funcall(evaluator, trace_func_cb_id, 3, obj, klass, method_id);
+    }
+    if (event & RUBY_EVENT_C_CALL) {
+        rb_funcall(evaluator, trace_c_func_cb_id, 3, obj, klass, method_id);
+    }
+
+    return;
+}
+
+static VALUE
+rb_disable_method_trace_for_thread(VALUE self)
+{
+    VALUE current_thread;
+    VALUE thread_variables_hash;
+    VALUE trace_set;
+    ID locals_id;
+    ID eval_trace_thread_id;
+    VALUE eval_trace_thread_flag;
+
+    CONST_ID(locals_id, "locals");
+    CONST_ID(eval_trace_thread_id, "gcloud_eval_trace_set");
+    eval_trace_thread_flag = ID2SYM(eval_trace_thread_id);
+
+    current_thread = rb_thread_current();
+    thread_variables_hash = rb_ivar_get(current_thread, locals_id);
+    trace_set = rb_hash_aref(thread_variables_hash, eval_trace_thread_flag);
+
+    if (RTEST(trace_set)) {
+        rb_thread_remove_event_hook(current_thread, (rb_event_hook_func_t)eval_trace_callback);
+        rb_hash_aset(thread_variables_hash, eval_trace_thread_flag, Qfalse);
+    }
+
+    return Qnil;
+}
+
+static VALUE
+rb_enable_method_trace_for_thread(VALUE self)
+{
+    VALUE current_thread;
+    VALUE thread_variables_hash;
+    VALUE trace_set;
+    VALUE evaluator;
+    ID current_evaluator_id;
+    ID locals_id;
+    ID eval_trace_thread_id;
+    VALUE eval_trace_thread_flag;
+
+    CONST_ID(current_evaluator_id, "current");
+    CONST_ID(locals_id, "locals");
+    CONST_ID(eval_trace_thread_id, "gcloud_eval_trace_set");
+    eval_trace_thread_flag = ID2SYM(eval_trace_thread_id);
+
+    current_thread = rb_thread_current();
+    thread_variables_hash = rb_ivar_get(current_thread, locals_id);
+    trace_set = rb_hash_aref(thread_variables_hash, eval_trace_thread_flag);
+    evaluator = rb_funcall(self, current_evaluator_id, 0);
+
+    if (!RTEST(trace_set)) {
+        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);
+        rb_hash_aset(thread_variables_hash, eval_trace_thread_flag, Qtrue);
+    }
+
+    return Qnil;
+}
+
+void
+Init_evaluator(VALUE mDebugger)
+{
+    VALUE cBreakpoint = rb_define_class_under(mDebugger, "Breakpoint", rb_cObject);
+    VALUE cEvaluator  = rb_define_class_under(cBreakpoint, "Evaluator", rb_cObject);
+
+    rb_define_module_function(cEvaluator, "enable_method_trace_for_thread", rb_enable_method_trace_for_thread, 0);
+    rb_define_module_function(cEvaluator, "disable_method_trace_for_thread", rb_disable_method_trace_for_thread, 0);
+}