Collecting diagnostic information

This document describes how to collect information about a virtual machine (VM) instance by using a diagnostic tool. Use the information that the tools collects to help with basic troubleshooting before contacting Cloud Customer Care.

The tool does the following:

  • Collects information only from the VM that you specify.

  • Stores the information only in your project.

  • Stores the information for 10 days in a Cloud Storage bucket, which, by default, only you can access.

Before sharing the collected information with Customer Care, do the following:

  1. Review the information for confidential or personally identifiable information (PII).

  2. Delete or mask the information as necessary.

Before you begin

  • Compute Engine installs the diagnostic tool by default on public versions of Windows Server images later than v20190714. Otherwise, if your Windows Server image version is earlier than v20190714, or you are using a custom image, install the tool by using the googet install google-compute-engine-diagnostics command.
  • If you haven't already, set up authentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    2. Set a default region and zone.

Diagnostic information collected from the VM

This diagnostic tool collects information about the following:

For detailed information about how Compute Engine collects this information, see the public GitHub repository.

Limitations

  • You can only collect diagnostic information from VMs created based on Windows Server.

Required roles

To get the permissions that you need to run the diagnostic tool by using Google Cloud CLI, ask your administrator to grant you the Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Collecting diagnostic information from a VM

Run the diagnostic tool either directly from the VM, or remotely, by using the Google Cloud CLI.

gcloud

  1. If you haven't already, grant the iam.serviceAccountTokenCreator role on the project to the user account or service account that will run the gcloud compute diagnose export-logs command:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member user:EMAIL \
    --role roles/iam.serviceAccountTokenCreator

    Replace the following:

    • PROJECT_ID: the project ID
    • EMAIL: the email address to grant the iam.serviceAccountTokenCreator role

  2. Export the diagnostic information as an object to a Cloud Storage bucket using the diagnose export-logs command.

    gcloud compute diagnose export-logs VM_NAME \
  [--collect-process-traces]

    The optional --collect-process-traces flag specifies whether the diagnostic tool collects a 10 minute trace of the running system, which includes CPU, disk, file, and network activity. On Windows-based VMs, this uses the Windows Performance Recorder.

    Replace VM_NAME with the name of the VM to collect diagnostic information from.

  3. The log exporting process might take a few minutes to complete. View the status by using the gcloud compute instances get-serial-port-output command.

  4. Compute Engine formats the name of the bucket containing the diagnostic information as diagnostic_logs_project_PROJECT_NUMBER. View or download the bucket by using the gcloud CLI, or, in the Google Cloud console, from the Cloud Storage page:

    Go to Storage

Locally (Windows only)

To run the diagnostic tool from within a Windows VM, do the following:

  1. Connect to the Windows VM.

  2. Open a command prompt or PowerShell window with Administrator privileges.

  3. Navigate to the directory containing the diagnostic tool:

    cd "C:\Program Files\Google\Compute Engine\diagnostics"

  4. Run the diagnostic tool:

    .\diagnostics.exe

    After the tool finishes running, it saves the collected diagnostic information to the compressed file logs.zip in your current working directory.

Optional flags

  • -trace: captures additional tracing information. The tool captures a 10-minute trace of the system using the Windows Performance Recorder, which includes CPU, disk, file, and network activity.

What's next