Stackdriver Debugger can capture and inspect the call stack and local variables of a live application running in the cloud, specifically on App Engine or Compute Engine, without stopping the app or slowing it down.
It works much like your IDE's standard debugger, and provides the same user interface, with two key differences:
- Stackdriver Debugger does not pause execution of the running application.
- You cannot step through an application in Stackdriver Debugger.
On App Engine, Stackdriver Debugger only runs in, and is enabled automatically for, Java and Kotlin applications. On Compute Engine, you need to enable it by running a bootstrap script.
Requirements
To run the Stackdriver Debugger, you need the following:
- Cloud Code.
- Java 7 or 8.
- Git.
- A Google account that can deploy App Engine apps.
Using the Stackdriver Debugger
To use the Stackdriver Debugger:
- Open your project inside IntelliJ.
- Choose Run > Edit Configurations.
- Click the plus sign (+) in the upper left corner, and select Google Stackdriver Debug from the dropdown list.
- Type a name for your configuration in the Name field.
- Make sure that your project is selected in the Project field.
- Click OK.
- Click the green bug "debug" icon in the toolbar to start the debugger.
- In the Attach to an Application dialog, select the backend module you want to debug and click Attach.
Setting a Snapshot Location
A snapshot captures the local variables and call stack at the specified location in your source code. The snapshot location applies to all running instances of your application.
To set a snapshot location:
- After attaching Stackdriver Debugger to a running application, navigate to the file that contains the source code you want to watch.
- Click the executable lines you want to snapshot in the left gutter area, just as you would
when setting a line breakpoint for a local application using the regular IDEA debugger.
A blue circle appears in the gutter to mark the snapshot location, and the Stackdriver Debugger Snapshots pane displays pending snapshots.
- Click the blue circle to remove the snapshot location.
In the following example, the snapshot location is set on the line
if (userAgent != null) {.
Getting the snapshot
The first time any instance executes the code at the snapshot location you set, the debugger takes a snapshot and makes it available for viewing. You can then examine the snapshot and use the data to debug your application.
The label on the snapshot in the Stackdriver Debugger Snapshots pane changes from Pending to the time Stackdriver captured the snapshot.
Advanced Concepts
Set a snapshot condition
A snapshot condition is a boolean expression that tells the debugger to take a snapshot only
when it evaluates to true. For example, x !=0. The condition is a full boolean
expression that can include logical and numeric operators, for example,
score < 0 || score > 500.
Watch Expressions
Sometimes the information you need to debug a problem is not immediately apparent in the
application's local variables and fields. In particular, when running on App Engine, the
Security Manager prevents you from delving too deeply into the private members of system classes
such as java.util.Hashmap. In cases like this, a watch expression serves as an
effective temporary local variable to expose additional information. Watch expressions can
evaluate complex expressions and traverse object hierarchies when a snapshot is taken.
You can specify a watch expression after you have set the snapshot location. Watch expressions support the same language features as snapshot conditions, described above.
Learn More
For an in-depth run-through of Stackdriver Debugger features in IntelliJ IDEA, see the IntelliJ IDEA Google Cloud Debugger Tutorial.
