Using Stackdriver Debugger

Stackdriver Debugger can capture and inspect the call stack and local variables of a live application running in the cloud, specifically on Google App Engine or Google 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.

Stackdriver Debugger is enabled automatically for Java applications running on App Engine. On Google Compute Engine, you’ll need to turn it on by running a bootstrap script.

Requirements

To run the Stackdriver Debugger, you need the following:

  • IntelliJ IDEA version 15 or higher, either Community or Ultimate Edition.
  • The Cloud Tools for IntelliJ plugins.
  • Java 7 or higher, with the caveat that apps written in Java 8 can only be deployed to the App Engine flexible environment.
  • Git
  • A Google account that can deploy App Engine apps.

For instructions on how to install IntelliJ IDEA and the Cloud Tools plugins, see Installation and Setup.

Use the Stackdriver Debugger

To use the Stackdriver Debugger:

  1. Open your project inside IDEA.
  2. Choose Run > Edit Configurations.
  3. Click the plus sign (+) in the upper left corner, and choose Cloud Debug from the dropdown list.
  4. Type a name for your configuration in the Name field.
  5. Make sure that your project is selected in the Project field.
  6. At the right-hand side of the Project popup, click the arrow to display a sign in pane. Log in.
  7. A window appears asking you to grant a list of permissions to IDEA. Click Allow. You will see a window saying “IntelliJ is now authorized to access your account.” Close the browser window and return to IntelliJ.
  8. Click the green bug "debug" icon in the toolbar to start the debugger.
  9. In the Attach to an Application dialog, select the backend module you want to debug, and click Attach.

Set a Snapshot Location

A snapshot captures the local variables and call stack at a specific line location in your source code. The snapshot location applies to all running instances of your application. The first time any instance executes the code at the location, 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.

To set a snapshot location:

  1. Attach to a running application as described above, and navigate to the file that contains the source code you want to watch.
  2. Click the line 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.

In the following example, the snapshot location is set on the line if (userAgent != null) {.

Set a snapshot location

The blue circle that appears in the gutter when you click represents the snapshot location. When you mouse over it, a tooltip shows you exactly where it's set. Clicking the blue circle a second time removes the snapshot location.

Once you've set a snapshot location, you will also see a pending snapshot in the lower left hand pane.

You can set snapshot locations on executable lines. You cannot set snapshot locations on non-executable lines such as comments, declarations, and empty lines. You can set multiple snapshot locations at once, in one or more classes.

Run the application

Once you've set the snapshot location, you can run the app in a web browser. When the server first executes the statement at the snapshot location, it sends a snapshot to IDEA. You'll see a brief pop-up saying "Snapshot received," and the label on the snapshot in the Snapshots pane changes from "Pending' to the time the snapshot was sent. Display the stack trace in IDEA by clicking on the snapshot.

View stack trace

Advanced Concepts

Set a snapshot condition

A snapshot condition is a boolean Java 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.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Tools for IntelliJ