README.md in google-cloud-debugger-0.30.0 vs README.md in google-cloud-debugger-0.31.0

- old
+ new

@@ -1,54 +1,44 @@ # google-cloud-debugger -[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. +[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 +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) - [Stackdriver Debugger documentation](https://cloud.google.com/debugger/docs/) ## Quick Start -Install the gem directly: +### Installing the gem -```sh -$ gem install google-cloud-debugger -``` +Add the `google-cloud-debugger` gem to your Gemfile: -Or install through Bundler: - -1. Add the `google-cloud-debugger` gem to your Gemfile: - ```ruby gem "google-cloud-debugger" ``` -2. Use Bundler to install the gem: +Alternatively, consider installing the [`stackdriver`](../stackdriver) gem. It +includes the `google-cloud-debugger` gem as a dependency, and automatically +initializes it for some application frameworks. -```sh -$ bundle install -``` +### Initializing the Debugger -Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes -the `google-cloud-debugger` gem. +The Stackdriver Debugger library provides a Debugger agent that helps create +breakpoints in your running applications. It then collects application snapshot +data and transmits it to the Stackdriver Debugger service for you to view on +the Google Cloud Console. 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. -## Enable Stackdriver Debugger API +#### Setup with Ruby on Rails -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 @@ -56,121 +46,124 @@ ``` If you're using the `stackdriver` gem, it automatically loads the Railtie into your application when it starts. -### With other Rack-based frameworks +#### Setup 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 +#### Setup without a Rack-based framework -Non-rack-based applications can start the agent explicitly at the entry point of -your application: +Non-rack-based applications can start the agent explicitly during the +initialization code: ```ruby require "google/cloud/debugger" Google::Cloud::Debugger.new.start ``` -### Configuring the agent +### Connecting to the Debugger -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. +You can set breakpoints and view snapshots using the Google Cloud Console. +If your app is hosted on Google Cloud (such as on Google App Engine, Google +Kubernetes Engine, or Google Compute Engine), you can use the same project. +Otherwise, if your application is hosted elsewhere, create a new project on +[Google Cloud](https://console.cloud.google.com/). -## Running on Google Cloud Platform +Make sure the +[Stackdriver Debugger API](https://console.cloud.google.com/apis/library/clouddebugger.googleapis.com) +is enabled on your Google Cloud project. -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. +To connect to the Stackdriver Debugger service, the agent needs to be +authenticated. If your application is hosted on Google Cloud Platform, much of +this is handled for you automatically. -### App Engine +#### Connecting from Google App Engine (GAE) -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. +If your app is running on Google App Engine, the Stackdriver Debugger agent +authenticates automatically by default, and no additional configuration is +required. -### Container Engine +#### Connecting from Google Kubernetes Engine (GKE) -On Google Container Engine, you must explicitly add the `cloud_debugger` OAuth -scope when creating the cluster: +If your app is running on Google Kubernetes 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 +After the OAuth scope is enabled, the Stackdriver Debugger agent authenticates +automatically by default, and no additional configuration is required. -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: +#### Connecting from Google Compute Engine (GCE) +If your app is running on Google Compute Engine, its 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 +The `cloud_debugger` access scope can 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 +After the OAuth scope is enabled, the Stackdriver Debugger agent authenticates +automatically by default using the VM's service account, and no additional +configuration is required. +#### Connecting from other hosting environments + 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. +cloud provider. -## Authentication - -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" + config.google_cloud.credentials = "/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" + config.google_cloud.debugger.credentials = "/path/to/key.json" end ``` -Other Rack-based applications that are loading the Rack Middleware directly can use -the configration interface: +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" + config.credentials = "/path/to/key.json" # Or Stackdriver Debugger agent specific parameters config.debugger.project_id = "your-project-id" - config.debugger.keyfile = "/path/to/key.json" + config.debugger.credentials = "/path/to/key.json" end ``` Or provide the parameters to the Stackdriver Debugger agent when it starts: @@ -182,18 +175,61 @@ 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 +### Using the Debugger -This library is supported on Ruby 2.2+. +When you set a breakpoint in the Stackdriver Debugger console, the agent takes +a snapshot of application data when the breakpoint is hit. The application then +continues running with minimal slowdown, and you can view the snapshot offline +in the console. -## Versioning +By default, the snapshot includes the local variables from the current and four +most recent stack frames. You may include additional data in the snapshot by +providing a list of _expressions_ when you create the breakpoint. Expressions +may be instance variables, global variables, or the result of calling Ruby +methods, or indeed, any Ruby expression. -This library follows [Semantic Versioning](http://semver.org/). +For more information on using the debugger features, see the +[Stackdriver Debugger Documentation](https://cloud.google.com/debugger/docs/). -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. +#### Working with Mutation Protection + +To reduce the risk of corrupting your application data or changing your +application's behavior, the debugger agent checks all expressions you provide +for possible side effects before it runs them. If an expression calls any code +that could modify the program state, by changing an instance variable for +example, it is not evaluated. + +This check is rather conservative, so if you are receiving mutation errors on +an expression you know to be safe, you may disable the check by wrapping your +expression in a call to `Google::Cloud::Debugger.allow_mutating_methods!`. For +example: + +```ruby +Google::Cloud::Debugger.allow_mutating_methods! { my_expression() } +``` + +You may disable side effect checks globally by setting the +`allow_mutating_methods` configuration. See the next section on configuring the +agent. + +#### Configuring the agent + +You can customize the behavior of the Stackdriver Debugger agent. This includes +setting the Google Cloud project and authentication, and customizing the +behavior of the debugger itself, such as side effect protection and data +size limits. See [agent configuration](../stackdriver/docs/configuration.md) +for a list of possible configuration options. + +## Compatibility + +This library is supported on Ruby 2.2 or later. + +This library follows [Semantic Versioning](http://semver.org/). 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. ## Contributing Contributions to this library are always welcome and highly encouraged.