A virtual machine (VM) instance has four virtual serial ports. The instance'soperating system, BIOS, and other system-level entities often write output tothe serial ports, which makes serial port output useful for troubleshootingcrashes, failed boots, startup issues, or shutdown issues.

This page describes methods toview serial port output, including usingCloud Logging to retain serial port output even after an instance isstopped or deleted. If you need tosend commands to a serial port while aninstance is running, seeInteracting with the serial console.

Serial port output is accessible through the Google Cloud console, thegcloud CLI, and REST, but only while the VM instanceis running. Logs are limited to the most recent 1 MB of output per port.

If you enable serial port output logging, Cloud Loggingprovides the first50 gibibytes (GiB) per month of logging for free andretains logs for30 days.

Before you begin

• If you want to log serial port output in Cloud Logging, familiarize yourself withCloud Logging.
• If you haven't already, set upauthentication. 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:

     gcloudinit

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

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

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

  gcloudinit

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

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Enabling and disabling serial port output logging

You can control whether your instances send serial port output toCloud Logging bysetting project- or instance-level metadata.You can also disable the feature for all of the users in your organizationbysetting an organization policy.

By default, serial port output logging to Cloud Logging is disabled. If serial port output logging to Cloud Logging is notconstrained for your organization,then you can enable or disable it for projects and for individual VMinstances by setting theserial-port-logging-enable metadata entry totrueorfalse.

If you set a project-wide metadata entry, all VM instances in the projectinherit that setting implicitly. If you set an instance metadata entry, themetadata entry is enabled for that VM only, regardless of the project setting.

You can set a metadata entry by using the Google Cloud console, thegcloud CLI, or the Compute Engine API. For more information, seeSetting custom metadata.

For example, the following gcloud CLI command enables serial portoutput logging to Cloud Logging for your project:

gcloud compute project-info add-metadata \    --metadata serial-port-logging-enable=true

Similarly, the following gcloud CLI command enables serial port output loggingto Cloud Logging for a specific instance instead:

gcloud compute instances add-metadataINSTANCE_NAME \    --metadata serial-port-logging-enable=true

To disable serial port output logging to Cloud Logging, setserial-port-logging-enable tofalse:

gcloud compute instances add-metadataINSTANCE_NAME \    --metadata serial-port-logging-enable=false

Exclusion filters

From within Cloud Logging, you cancreate an exclusion filter toremove specific serial port entries from the Logs Explorer. For example, witha project-wide metadata entry that is set toserial-port-logging-enable=true,you can disable serial port output logging for specific VM instances by usingan advanced filter:

logName = "projects/PROJECT_ID/logs/serialconsole.googleapis.com%2Fserial_port_1_output"resource.type = "gce_instance"resource.labels.instance_id != "INSTANCE_1_ID"resource.labels.instance_id != "INSTANCE_2_ID"

Setting an organization policy

You can disable serial port output logging to Cloud Logging for your entireorganization by setting anOrganization Policy, whichconstrains certain configurations of Google Cloud resources. Specifically,set the following boolean constraint:constraints/compute.disableSerialPortLogging. For more information, seeCreating and managing organization policies.

Disabling serial port logging by settingconstraints/compute.disableSerialPortLogging totrue is notretroactive. Existing VM instances with a metadata entry that enablesserial port logging to Cloud Logging continue to log to Cloud Loggingunless youreset the metadata forthose instances.

After setting this organization constraint totrue, you cannot set instance orproject metadata to enable serial port output logging to Cloud Logging forany instances within the organization.

Viewing serial port output

gcloud compute instances get-serial-port-outputINSTANCE_NAME \  --portPORT \  --startSTART \  --zoneZONE

GET https://compute.googleapis.com/compute/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/serialPort

Handling non-UTF8 characters

Serial port output is escaped by using the open sourceAbseil C++ library'sCHexEscape() method,so non-UTF8 characters are encoded as hex strings. You can use the correspondingCUnescape() methodto get the exact output that was sent to the serial port.