Module: Google::Cloud::Debugger

Defined in:
lib/google/cloud/debugger.rb,
lib/google/cloud/debugger/v2.rb,
lib/google/cloud/debugger/agent.rb,
lib/google/cloud/debugger/rails.rb,
lib/google/cloud/debugger/tracer.rb,
lib/google/cloud/debugger/backoff.rb,
lib/google/cloud/debugger/project.rb,
lib/google/cloud/debugger/service.rb,
lib/google/cloud/debugger/version.rb,
lib/google/cloud/debugger/debuggee.rb,
lib/google/cloud/debugger/logpoint.rb,
lib/google/cloud/debugger/snappoint.rb,
lib/google/cloud/debugger/breakpoint.rb,
lib/google/cloud/debugger/middleware.rb,
lib/google/cloud/debugger/credentials.rb,
lib/google/cloud/debugger/transmitter.rb,
lib/google/cloud/debugger/v2/doc/overview.rb,
lib/google/cloud/debugger/breakpoint_manager.rb,
lib/google/cloud/debugger/breakpoint/variable.rb,
lib/google/cloud/debugger/v2/debugger2_client.rb,
lib/google/cloud/debugger/breakpoint/evaluator.rb,
lib/google/cloud/debugger/breakpoint/validator.rb,
lib/google/cloud/debugger/request_quota_manager.rb,
lib/google/cloud/debugger/v2/controller2_client.rb,
lib/google/cloud/debugger/breakpoint/stack_frame.rb,
lib/google/cloud/debugger/breakpoint/status_message.rb,
lib/google/cloud/debugger/breakpoint/variable_table.rb,
lib/google/cloud/debugger/breakpoint/source_location.rb,
lib/google/cloud/debugger/debuggee/app_uniquifier_generator.rb

Overview

Ruby Client for Stackdriver Debugger API (Beta)

Stackdriver Debugger API: Examines the call stack and variables of a running application without stopping or slowing it down.

Quick Start

In order to use this library, you first need to go through the following steps:

  1. Select or create a Cloud Platform project.
  2. Enable the Stackdriver Debugger API.
  3. Setup Authentication.

Installation

$ gem install google-cloud-debugger

Next Steps

Defined Under Namespace

Modules: V2 Classes: Agent, Breakpoint, BreakpointManager, Credentials, Debuggee, Logpoint, Middleware, Project, Railtie, RequestQuotaManager, Snappoint, Tracer, Transmitter

Constant Summary collapse

VERSION = 
"0.32.0".freeze

Class Method Summary collapse

Class Method Details

.allow_mutating_methods!(&block) ⇒ Object

Allow calling of potentially state-changing methods even if mutation detection is configured to be active.

Generally it is unwise to run code that may change the program state (e.g. modifying instance variables or causing other side effects) in a breakpoint expression, because it could change the behavior of your program. However, the checks are currently quite conservative, and may block code that is actually safe to run. If you are certain your expression is safe to evaluate, you may use this method to disable side effect checks.

This method may be called with a block, in which case checks are disabled within the block. It may also be called without a block to disable side effect checks for the rest of the current expression; the default setting will be restored for the next expression.

This method may be called only from a debugger condition or expression evaluation, and will throw an exception if you call it from normal application code. Set the allow_mutating_methods configuration if you want to disable the side effect checker globally for your app.

Examples:

Disabling side effect detection in a block

# This is an expression evaluated in a debugger snapshot
Google::Cloud::Debugger.allow_mutating_methods! do
  obj1.method_with_potential_side_effects
end

Disabling side effect detection for the rest of the expression

# This is an expression evaluated in a debugger snapshot
Google::Cloud::Debugger.allow_mutating_methods!
obj1.method_with_potential_side_effects
obj2.another_method_with_potential_side_effects

Globally disabling side effect detection at app initialization

require "google/cloud/debugger"
Google::Cloud::Debugger.configure.allow_mutating_methods = true


523
524
525
526
527
528
529
 
# File 'lib/google/cloud/debugger.rb', line 523

def self.allow_mutating_methods! &block
  evaluator = Breakpoint::Evaluator.current
  if evaluator.nil?
    raise "allow_mutating_methods can be called only during evaluation"
  end
  evaluator.allow_mutating_methods!(&block)
end

.configure {|Google::Cloud.configure.debugger| ... } ⇒ Google::Cloud::Config

Configure the Stackdriver Debugger agent.

The following Stackdriver Debugger configuration parameters are supported:

  • project_id - (String) Project identifier for the Stackdriver Debugger service you are connecting to. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • service_name - (String) Name for the debuggee application.
  • service_version - (String) Version identifier for the debuggee application.
  • root - (String) The root directory of the debuggee application as an absolute file path.
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • timeout - (Integer) Default timeout to use in requests.
  • client_config - (Hash) A hash of values to override the default behavior of the API client.
  • allow_mutating_methods - (boolean) Whether expressions and conditional breakpoints can call methods that could modify program state. Defaults to false.
  • evaluation_time_limit - (Numeric) Time limit in seconds for expression evaluation. Defaults to 0.05.

See the Configuration Guide for full configuration parameters.

Yields:

Returns:

  • (Google::Cloud::Config) —

    The configuration object the Google::Cloud::Debugger module uses.



445
446
447
448
449
 
# File 'lib/google/cloud/debugger.rb', line 445

def self.configure
  yield Google::Cloud.configure.debugger if block_given?

  Google::Cloud.configure.debugger
end

.new(project_id: nil, credentials: nil, service_name: nil, service_version: nil, scope: nil, timeout: nil, client_config: nil, project: nil, keyfile: nil) ⇒ Google::Cloud::Debugger::Project

Creates a new debugger object for instrumenting Stackdriver Debugger for an application. Each call creates a new debugger agent with independent connection service.

For more information on connecting to Google Cloud see the Authentication Guide.

Examples:

require "google/cloud/debugger"

debugger = Google::Cloud::Debugger.new
debugger.start

Parameters:

  • project_id (String) —

    Project identifier for the Stackdriver Debugger service you are connecting to. If not present, the default project for the credentials is used.

  • credentials (String, Hash, Google::Auth::Credentials) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

  • service_name (String) —

    Name for the debuggee application. Optional.

  • service_version (String) —

    Version identifier for the debuggee application. Optional.

  • scope (String, Array<String>) —

    The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs.

    The default scope is:

    • https://www.googleapis.com/auth/cloud_debugger
    • https://www.googleapis.com/auth/logging.admin
  • timeout (Integer) —

    Default timeout to use in requests. Optional.

  • client_config (Hash) —

    A hash of values to override the default behavior of the API client. Optional.

  • project (String) —

    Project identifier for the Stackdriver Debugger service.

  • keyfile (String, Hash) —

    Keyfile downloaded from Google Cloud: either the JSON data or the path to a readable file.

Returns:

Raises:

  • (ArgumentError) 


372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/google/cloud/debugger.rb', line 372

def self.new project_id: nil, credentials: nil, service_name: nil,
             service_version: nil, scope: nil, timeout: nil,
             client_config: nil, project: nil, keyfile: nil
  project_id ||= (project || default_project_id)
  project_id = project_id.to_s # Always cast to a string

  service_name ||= default_service_name
  service_name = service_name.to_s

  service_version ||= default_service_version
  service_version = service_version.to_s

  raise ArgumentError, "project_id is missing" if project_id.empty?
  raise ArgumentError, "service_name is missing" if service_name.empty?
  if service_version.nil?
    raise ArgumentError, "service_version is missing"
  end

  scope ||= configure.scope
  timeout ||= configure.timeout
  client_config ||= configure.client_config

  credentials ||= (keyfile || default_credentials(scope: scope))
  unless credentials.is_a? Google::Auth::Credentials
    credentials = Debugger::Credentials.new credentials, scope: scope
  end

  Debugger::Project.new(
    Debugger::Service.new(project_id, credentials,
                          timeout: timeout, client_config: client_config),
    service_name: service_name,
    service_version: service_version
  )
end