Class: Google::Cloud::Debugger::Agent

Inherits:
Object
  • Object
show all
Includes:
Stackdriver::Core::AsyncActor
Defined in:
lib/google/cloud/debugger/agent.rb

Overview

Agent

The Stackdriver Debugger Agent runs on the same system where a debuggee application is running. The agent is responsible for sending state data, such as the value of program variables and the call stack, to Stackdriver Debugger when the code at a breakpoint location is executed.

The Debugger Agent runs in its own child thread when started. It ensures the instrumented application is registered properly and constantly monitors for any active breakpoints. Once the agent gets updated with active breakpoints from Stackdriver Debugger service, it facilitates the breakpoints in application requests thread, then transport the result snapshot back to Stackdriver Debugger service asynchronously.

Examples:

require "google/cloud/debugger"

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

Constant Summary collapse

DEFAULT_LOG_NAME =

Name of the logpoints log file.

"debugger_logpoints".freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service, service_name:, service_version:, logger: nil, app_root: nil) ⇒ Agent

Create a new Debugger Agent instance.

Parameters:

  • service (Google::Cloud::Debugger::Service) —

    The gRPC Service object

  • logger (Google::Cloud::Logging::Logger) (defaults to: nil) —

    The logger used to write the results of Logpoints.

  • service_name (String) —

    Name for the debuggee application.

  • service_version (String) —

    Version identifier for the debuggee application.

  • app_root (String) (defaults to: nil) —

    Absolute path to the root directory of the debuggee application. Default to Rack root.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/google/cloud/debugger/agent.rb', line 123

def initialize service,
               service_name:,
               service_version:,
               logger: nil,
               app_root: nil
  super()

  @service = service
  @debuggee = Debuggee.new service, service_name: service_name,
                                    service_version: service_version
  @tracer = Debugger::Tracer.new self
  @breakpoint_manager = BreakpointManager.new self, service
  @breakpoint_manager.on_breakpoints_change =
    method :breakpoints_change_callback

  @transmitter = Transmitter.new self, service

  @logger = logger || default_logger

  init_app_root app_root

  # Agent actor thread needs to force exit immediately.
  set_cleanup_options timeout: 0
end

Instance Attribute Details

#app_root ⇒ String

Absolute path to the debuggee Ruby application root directory. The Stackdriver Debugger service creates canonical breakpoints with only relative path. So the debugger agent combines the relative path to the application directory to trace and evaluate breakpoints.

Returns:

  • (String) 


104
105
106
 
# File 'lib/google/cloud/debugger/agent.rb', line 104

def app_root
  @app_root
end

#breakpoint_manager ⇒ Google::Cloud::Debugger::BreakpointManager (readonly)

It manages syncing breakpoints between the Debugger Agent and Stackdriver Debugger service

Returns:



75
76
77
 
# File 'lib/google/cloud/debugger/agent.rb', line 75

def breakpoint_manager
  @breakpoint_manager
end

#debuggee ⇒ Google::Cloud::Debugger::Debuggee (readonly)

The gRPC Debuggee representation of the debuggee application. It contains identification information to match running application to specific Cloud Source Repository code base, and correctly group same versions of the debuggee application together through a generated unique identifier.

Returns:



69
70
71
 
# File 'lib/google/cloud/debugger/agent.rb', line 69

def debuggee
  @debuggee
end

#logger ⇒ Object

The logger used to write the results of Logpoints.



91
92
93
 
# File 'lib/google/cloud/debugger/agent.rb', line 91

def logger
  @logger
end

#quota_manager ⇒ Object

A quota tracking object helps tracking resource consumption during evaluations.



96
97
98
 
# File 'lib/google/cloud/debugger/agent.rb', line 96

def quota_manager
  @quota_manager
end

#tracer ⇒ Google::Cloud::Debugger::Tracer (readonly)

It monitors the debuggee application and triggers breakpoint evaluation when breakpoints are set.

Returns:



81
82
83
 
# File 'lib/google/cloud/debugger/agent.rb', line 81

def tracer
  @tracer
end

#transmitter ⇒ Google::Cloud::Debugger::Transmiter (readonly)

It sends evaluated breakpoints snapshot back to Stackdriver Debugger Service.

Returns:

  • (Google::Cloud::Debugger::Transmiter) 


87
88
89
 
# File 'lib/google/cloud/debugger/agent.rb', line 87

def transmitter
  @transmitter
end

Instance Method Details

#start ⇒ Object

Starts the Debugger Agent in a child thread, where debuggee application registration and breakpoints querying will take place. It also starts the transmitter in another child thread.



153
154
155
156
 
# File 'lib/google/cloud/debugger/agent.rb', line 153

def start
  transmitter.start
  async_start
end

#stop ⇒ Object

Stops and terminates the Debugger Agent. It also properly shuts down transmitter and tracer.

Once Debugger Agent is stopped, it cannot be started again.



164
165
166
167
 
# File 'lib/google/cloud/debugger/agent.rb', line 164

def stop
  transmitter.stop
  async_stop
end

#stop_tracer ⇒ Object

Stops the tracer regardless of whether any active breakpoints are present. Once the tracer stops monitoring the debuggee application, the application can return to normal performance.



173
174
175
 
# File 'lib/google/cloud/debugger/agent.rb', line 173

def stop_tracer
  tracer.stop
end