Using Debug Snapshots

After you have deployed or started your application, you can open Stackdriver Debugger in the Google Cloud Platform Console. Stackdriver Debugger allows you to capture and inspect the call stack and local variables in your application without stopping or slowing it down.

Visit the Debug page of the GCP Console to use Google Stackdriver Debugger.

Before you begin

Stackdriver Debugger can be used with or without access to your application's source code. If your source code isn't available, see Take a debug snapshot below for instructions on entering the filename and line number manually.

If your source code is stored in Google Cloud Repositories, it's automatically displayed in the Debug view.

To access source code that's stored elsewhere, such as locally or in a git repository, you may need to select a source code location.

Snapshots

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, Stackdriver 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 debugger implements several strategies for minimizing the amount of latency caused when capturing the data.

Take a debug snapshot

Console

Click the source code line number to take a snapshot at that location.

  1. Make sure that the Snapshot panel is selected in the right panel.
  2. In the left panel, select the file that contains the source code to watch. The contents of the selected file are displayed in the center panel.
  3. Click the line number of the source code location.

Browse to a snapshot location

You can click multiple lines to set more than one snapshot location on a file.

See the Source code options section for other ways to load your source code in Stackdriver Debugger.

If no source code is available, you can manually enter the filename:line to take a snapshot in the Snapshot panel:

Set a snapshot location manually

gcloud

To set a snapshot location from the command line:

gcloud debug snapshots create LOCATION

Where:

  • LOCATION is the filename and line at which to set the logpoint. Format is FILE:LINE, where FILE can be the filename or the filename preceded by enough path components to differentiate it from other files with the same name. It's an error to provide a filename that is not unique in the debug target.

Snapshot conditions

A snapshot condition is a simple expression in the application language (Java, Python, and Go are supported) that must evaluate to true for the snapshot to be taken. Snapshot conditions are evaluated each time the line is executed, by any instance, until the condition evaluates to true or the snapshot times out.

The condition is a full boolean expression that can include logical operators:

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

Console

To specify the condition, enter it in the Condition field in the Snapshot panel.

Set a snapshot condition

gcloud

Conditions are specified using the --condition flag of snapshots create:

gcloud debug snapshots create LOCATION \
  --condition="ultimateAnswer <= 42 && foo==bar"

You can use the following language features to express conditions:

Java

Most Java expressions are supported, including:
  • Local variables: a == 8.
  • Numerical and boolean operations: x + y < 20.
  • Instance and static fields: this.counter == 20, this.myObj.isShutdown, myStatic, or com.mycompany.MyClass.staticMember.
  • String comparisons with the equality operator: myString == "abc".
  • Function calls. Only read-only functions can be used. For example, StringBuilder.indexOf() is supported, but StringBuilder.append() is not.
  • Type casting, with fully qualified types: ((com.myprod.ClassImpl) myInterface).internalField

The following language features are not supported:

  • Unboxing of numeric types, such as Integer; use myInteger.value instead.

Python

Most Python expressions are supported, including:
  • Reading local and global variables.
  • Reading from arrays, lists, slices, dictionaries and objects.
  • Calling simple methods.

The following language features are not supported:

  • Calling functions that allocate new objects or use complex constructs.
  • Creating new objects inside the expression.

Go

Most Go expression syntax is supported, including:
  • Reading local and global variables.
  • Reading from arrays, slices, maps, and structs.

The following language features are not supported:

  • Reading from interface values.
  • Type conversions and composite literals.
  • Function calls other than len.

Expressions

Stackdriver Debugger's Expressions feature allows you to evaluate complex expressions or traverse object hierarchies when a snapshot is taken. Expressions support the same language features as snapshot conditions, described above.

Typical uses for expressions are:

  • To view static or global variables that are not part of the local variable set.
  • To easily view deeply nested member variables without having to expand a local variable in the debugger panel every time.
  • To avoid repetitive mathematical calculations. For example, calculating a duration in seconds with (endTimeMillis - startTimeMillis) / 1000.0.

To add an expression:

Console

  1. Enter the expression in the Expression field. Press the tab key to add additional expressions.
  2. Press the Enter key or the Snapshot button Snapshot button.

The result of the expression is shown when the snapshot is taken.

Set an expression

gcloud

Expressions are defined using the --expression flag of snapshots create:

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

View a snapshot

Console

Snapshot data appears in Stackdriver Debugger when the application executes the source code at the location you specified. Instance variables and local variables appear in the Variables section of the panel. The stack trace appears in the Call Stack section of the panel.

View snapshot

You can examine the value of local variables at the moment the snapshot was taken, and drill down into deeper data structures. You can also click on any call stack frame, and examine the local variables at that level in the stack.

If you've set multiple snapshot locations on a file, or to view snapshots that you've already taken, expand the Snapshot History panel:

gcloud

To retrieve the GCP Console URL for a snapshot from the command line:

gcloud debug snapshots list

STATUS LOCATION CONDITION COMPLETED_TIME ID VIEW ACTIVE HighScoreService.java:105 53bd97d4-b6c6-74fc https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

Copy and paste the value of the VIEW column into your browser to view the snapshot in the GCP Console.

To view detailed snapshot data from the command line:

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

The describe command returns stack trace and local variable values, and is primarily intended to be machine-readable, rather than human-readable.

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

Retake a snapshot

A snapshot is only taken once. If you want to capture another snapshot of your application data at the same location, you can manually retake it.

Console

To retake a snapshot, click the camera icon at the top-right of the Snapshot panel:

Snapshot button

The new snapshot is added to the Snapshot History panel. Past snapshots on that line can be accessed from the Snapshot History or from the marker on that line number:

Previous snapshots shown on line marker

gcloud

To retake a snapshot from the command line, repeat the create command you used originally:

gcloud debug snapshots create LOCATION

Remove a snapshot location

Console

Remove a snapshot location by clicking the X in the snapshot marker.

Snapshot icon

gcloud

To delete a snapshot from the command line:

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

Where:

  • ID is the value returned by gcloud debug snapshots list.

  • LOCATION-REGEXP is a regular expression defining the code location of the snapshot(s).

Share snapshots

You can share a snapshot with another project member by copying the snapshot URL from your browser or from the output of the gcloud debug snapshots list command and giving it to another user who has access to your project. You can also save this URL for future reference and come back to it again to view its results. Stackdriver Debugger uses a new URL for each snapshot taken. This allows you to share distinct sets of results even if they were captured at the same location in the code. Sharing expires thirty days after the snapshot has been taken.

Send feedback about...

Stackdriver Debugger Documentation