A virtual machine (VM) instance has four virtual serial ports. The instance's operating system, BIOS, and other system-level entities often write output to the serial ports, which makes serial port output useful for troubleshooting crashes, failed boots, startup issues, or shutdown issues.
This page describes methods to view serial port output, including using Cloud Logging to retain serial port output even after an instance is stopped or deleted. If you need to send commands to a serial port while an instance is running, see Interacting with the serial console.
Serial port output is accessible through the Cloud Console, the
gcloud tool, and the Compute Engine API, but only while the VM instance
is running. Logs are limited to the most recent 1 MB of output per port.
If you enable serial port output logging, Cloud Logging provides the first 50 gibibytes (GiB) per month of logging for free and retains logs for 30 days.
Before you begin
- If you want to use the command-line examples in this guide, do the following:
- If you want to use the API examples in this guide, set up API access.
- If you want to log serial port output in Cloud Logging, familiarize yourself with Cloud Logging.
Enabling and disabling serial port output logging
You can control whether your instances send serial port output to Cloud Logging by setting project- or instance-level metadata. You can also disable the feature for all of the users in your organization by setting an organization policy.
Setting project and instance metadata
If serial port output logging to Cloud Logging is not
constrained for your organization,
then you can enable or disable it for projects and for individual VM
instances by setting the
serial-port-logging-enable metadata entry to
If you set a project-wide metadata entry, all VM instances in the project inherit that setting implicitly. If you set an instance metadata entry, the metadata entry is enabled for that VM only, regardless of the project setting.
You can set a metadata entry by using the Google Cloud Console, the
gcloud tool, or the Compute Engine API. For more information, see
Setting custom metadata.
For example, the following
gcloud tool command enables serial port
output logging to Cloud Logging for your project:
gcloud compute project-info add-metadata \ --metadata serial-port-logging-enable=true
Similarly, the following
gcloud tool command enables serial port output logging
to Cloud Logging for a specific instance instead:
gcloud compute instances add-metadata INSTANCE_NAME \ --metadata serial-port-logging-enable=true
To disable serial port output logging to Cloud Logging, set
gcloud compute instances add-metadata INSTANCE_NAME \ --metadata serial-port-logging-enable=false
From within Cloud Logging, you can
create an exclusion filter to
remove specific serial port entries from the Logs Viewer. For example, with
a project-wide metadata entry that is set to
you can disable serial port output logging for specific VM instances by using
an 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 entire
organization by setting an
Organization Policy, which
constrains certain configurations of Google Cloud resources. Specifically,
set the following boolean constraint:
constraints/compute.disableSerialPortLogging. For more information, see
Creating and managing organization policies.
Disabling serial port logging by setting
true is not
retroactive. Existing VM instances with a metadata entry that enables
serial port logging to Cloud Logging continue to log to Cloud Logging
unless you reset the metadata for
After setting this organization constraint to
true, you cannot set instance or
project metadata to enable serial port output logging to Cloud Logging for
any instances within the organization.
Viewing serial port output
In the Google Cloud Console, go to the VM instances page.
Select the VM instance for which you want to view serial port output.
Under Logs, click Serial port 1, 2, 3, or 4. System-level entities typically use the first serial port (port 1), which is also known as the serial console.
gcloud compute instances get-serial-port-output INSTANCE_NAME \ --port PORT \ --start START \ --zone ZONE
Replace the following:
INSTANCE_NAME: the name of the instance.
PORT: the number of the port (
4) for which you want to view output. System-level entities typically use the first serial port (port 1), which is also known as the serial console. By default, the output of the first serial port is returned.
START: the byte index (zero-based) of the first byte you want returned. Use this flag if you want to continue getting the output from a previous request that was too long to return in one attempt.
ZONE: the zone of your instance.
In the API, create a
get request to the
- Enable serial port logging to Cloud Logging.
Go to the VM instances page.
Select the VM instance for which you want to view startup agent logs.
Under Logs, click Cloud Logging to view Cloud Logging logs.
Expand the All logs drop-down menu and select the serial port output that you want to see. System-level entities typically use the first serial port (port 1), which is also known as the serial console. If a port does not appear in the drop-down menu, it has no available output.
Optionally, expand the Any log level drop-down menu to mute logs that are below the severity level that you want to see. For example, if you select the "Info" log level, you will mute "Debug" log entries. "Debug" entries are typically used only by the BIOS at boot time.
For more information, including information about basic and advanced filtering, see Viewing logs.
Handling non-UTF8 characters
Serial port output is escaped by using the open source
Abseil C++ library's
so non-UTF8 characters are encoded as hex strings. You can use the corresponding
to get the exact output that was sent to the serial port.