Cloud Debugger is deprecated and will be shutdown May 31, 2023. See the deprecations page and release notes for more information.

Debug Snapshots

Stay organized with collections Save and categorize content based on your preferences.

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

Visit the Debug page of the Google Cloud console to use Debugger.

Before you begin

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

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


Snapshots capture local variables and the call stack at a specific line location in your app's source code. You can specify certain conditions and locations to return a snapshot of your app's data, and view it in detail to debug your app.

Debugger agent with canarying

After you set a snapshot, the Debugger agent tests the snapshot on a subset of your instances. After the Debugger agent verifies the snapshot can execute successfully, the snapshot is applied to all your instances. This takes about 40 seconds.

After this process, when the snapshot is triggered, the results appear in the Variables and Call Stack panes. If the snapshot is triggered within 40 seconds after setting it, you see the results from those instances that had the canary snapshot applied to it.

The Debugger agent implements several strategies for minimizing the amount of latency caused when capturing the data.

The following text is displayed when the Debugger agent is canarying:

"Verifying the breakpoint on a subset of application instances."

The Debugger agent is canarying instances

To learn what to do if the Debugger agent fails while in canary mode, go to the Troubleshooting section on the Debug snapshots page.

To learn what Debugger agent versions have canary functionality, see the language-specific pages.

Debugger agent without canarying

When you use the Debugger agent without canarying and set a snapshot, it applies to all running instances of your app. The first time any instance executes the code at the snapshot location, the Debugger agent takes a snapshot and makes it available for viewing. The Debugger agent implements several strategies for minimizing the amount of latency caused when capturing the data.

Take a debug snapshot


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

  1. Make sure that the Snapshot panel is selected.
  2. Select the file that contains the source code. 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 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.


To set a snapshot location from the command line:

gcloud debug snapshots create LOCATION


  • LOCATION is the filename and line at which to set the snapshot. 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 (optional)

A snapshot condition is a simple expression in the app's 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.

Use of snapshot conditions is optional.

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

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


To specify the condition, create a snapshot. In the Condition field, enter a condition, and then select Update. If the condition evaluates to true, the snapshot is triggered.

Set a snapshot condition.


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:


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.


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.


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 (optional)

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.

Use of expressions is optional.

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:


  1. Enter the expression in the Expression field. You can add as many expressions as needed.
  2. Select Retake.

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

Set an expression.


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

gcloud debug snapshots create LOCATION \

View a snapshot


Snapshot data appears in Debugger when the app 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:

View snapshot history.


To retrieve the Google Cloud console URL for a snapshot from the command line:

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE                             53bd97d4-b6c6-74fc

Copy and paste the value of the VIEW column into your browser to view the snapshot in the Google Cloud 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.

createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
<... snip ...>

Retake a snapshot

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


To retake a snapshot, select Retake:

Retake button selected.

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.


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

gcloud debug snapshots create LOCATION

Remove a snapshot location


Remove a snapshot location by clicking delete .

Remove snapshot selected.


To delete a snapshot from the command line:

gcloud debug snapshots delete (ID | LOCATION-REGEXP)


  • 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 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. 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 30 days after the snapshot has been taken.


Has the Debugger agent crashed my instances?

You might see the following error if the Debugger agent is faulty:

Variables pane is showing error message.

You could get false-positives that make it appear as if the Debugger agent has triggered its safeguards for the following reasons:

  • An instance was shut down while the Debugger agent was canarying.

    When an instance that has a canary snapshot applied to it is shut down, it appears like the Debugger agent terminated the instance. Verify no instances were shut down within 40 seconds after the snapshot was set. For example, autoscaling from Cloud Run and App Engine, or deploying new code could be reasons instances are shut down.

You should remove the Debugger agent from your instances and reinstall the previous version. To reinstall the previous version, follow the setup instructions for installing the previous version of the Debugger agent.

If the issue persists with the old version of the agent, verify that it isn't a false-positive, then disable the Debugger agent and send feedback.