Debugging an Instance

You can enable debug mode for a VM. In debug mode, project members with Owner, Editor, Viewer, and App Engine Admin roles have root access to the VM. While debug mode is turned on, the automatic rollout of operating system updates and security patches is disabled. However, the VM is still part of the load balancer pool, and continues to receive external requests.

Whenever you enable or disable debugging, a "VM instance debugging enable/disable" event appears in the Google Cloud Platform Console and the event will be logged in the VM's /var/log/syslog.log file.

Enabling and disabling debug mode

You can use gcloud to enable and disable debug mode for an instance.

To enable and disable debug mode in gcloud:

  1. Use the gcloud app instances enable-debug command to debug the VMs for a particular instance and version, as follows:
    gcloud app --project [PROJECT-ID] instances enable-debug
    Replace PROJECT-ID with your own project ID, and follow the prompts to specify the instance version to debug.
  2. When finished debugging, disable debug mode as follows:
    gcloud app --project [PROJECT-ID] instances disable-debug
    Follow the prompts to specify the instance version

When you disable debug mode, the VM is stopped and a new instance of your app is started, running on a clean, new VM.

Connecting to the instance

If a VM instance is in debug mode, you can connect to its host by using SSH in the console or with gcloud.

Console

To connect to an instance in the console:

  1. Visit the Cloud Platform Console instances page for your project:
    Go to the instances page
  2. Click SSH in the far right of the row containing the instance you want to access:

    This puts the instance into debug mode, and opens an SSH session for the instance in a terminal window.

    You can also select different options to start an SSH session from the drop-down list.

  3. At this point you are in the instance host, which has several containers running in it. See Understanding common containers next for more information about these.
  4. In the terminal window, list the containers running in the instance:
    sudo docker ps
  5. The output of the sudo docker ps command lists each container by row; locate the row that contains your project ID: this is the container running your code. Note the NAME of this container.
  6. Optionally, list logging information for your application by invoking:
    sudo docker logs [CONTAINER-NAME]
  7. Start a shell in the container that is running your code:
    container_exec [CONTAINER-NAME] /bin/bash
  8. When finished debugging, enter exit to exit the container, then exit again to exit the SSH session.
  9. Disable debugging for your instance to allow it to resume normal operation.

gcloud

To connect to an instance using gcloud:

  1. With the instance enabled for debugging, look up and note the instance name, the zone it is running in, and the project ID, using the console.
  2. Invoke the command:
    gcloud compute --project [PROJECT-ID] ssh --zone  
  3. At this point you are in the instance host, which has several containers running. See Understanding common containers next for more information about these.
  4. In the terminal window, list the containers running in the instance:
    sudo docker ps
  5. The output of the sudo docker ps command lists each container by row; locate the row that contains your project ID: this is the container running your code. Note the NAME of this container.
  6. Optionally, list logging information for your application by invoking:
    sudo docker logs [CONTAINER-NAME]
  7. Start a shell in the container that is running your code:
    container_exec [CONTAINER-NAME] /bin/bash
  8. When finished debugging, enter exit to exit the container, then exit again to exit the SSH session.
  9. Disable debugging for your instance to allow it to resume normal operation.

Understanding common containers

In addition to the container running your application code, your instance may also have the following containers

Container and Source Code Open Source Org Description
fluentd_logger fluentd.org/ Logging agent.
memcache_proxy memcache proxy open source Provides memcache functionality to the application.
nginx_proxy nginx.org Proxies requests to the application.

Send feedback about...

App Engine flexible environment for Node.js docs