A virtual machine 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 them useful for troubleshooting crashes, failed boots, startup issues, or shutdown issues.
This page describes methods to view serial port output, including using Stackdriver 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 GCP Console,
tool, and API, only when the VM instance is running, and logs are limited to the
most recent 1 MB of output per port.
If you enable serial port output logging to Stackdriver, logs are retained for 30 days by default and Stackdriver provides the first 50 GB per month of logging for free. See Stackdriver pricing for details.
Before you begin
- If you want to use the command-line examples in this guide:
- If you want to use the API examples in this guide, set up API access.
- If you want to log serial port output in Stackdriver, familiarize yourself with Stackdriver Logging.
Enabling and disabling serial port logging to Stackdriver
To enable this feature, set the
serial-port-logging-enable metadata attribute
true. When this key-value metadata is
set at the project level,
serial port output logging to Stackdriver is enabled for all instances in the
project. When it is
set at the VM instance level
it is enabled for that VM only, regardless of the project setting.
You can set custom metadata through the Google Cloud Platform Console, the
gcloud tool, or
the API. See Setting custom metadata
for all the details.
For example, you can use the following
gcloud command to enable serial port
output logging to Stackdriver for an existing instance.
gcloud compute instances add-metadata [INSTANCE_NAME] \ --metadata serial-port-logging-enable=true
To disable serial port output logging to Stackdriver, set
serial-port-logging-enable to false.
gcloud compute instances add-metadata [INSTANCE_NAME] \ --metadata serial-port-logging-enable=false
Alternatively, from within Stackdriver, you can
create an exclusion filter to
remove specific serial port entries from the Logs Viewer. For example, with
serial-port-logging-enable=true at the project level, you can disable
serial port outuput logging for specific VM instances with an advanced
filter like the following one.
logName = "projects/google.com:serial-output-logging-demo/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]"
Viewing serial port output
gcloud instances get-serial-port-output
gcloud compute instances get-serial-port-output [INSTANCE_NAME] \ --port [PORT] \ --start [START] \ --zone [ZONE]
[INSTANCE_NAME]is the name of the instance.
[PORT]is 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]specifies 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.
In the API, create a
get request to the
- Enable serial port logging to Stackdriver
- Go to the VM instances page.
- Select the VM instance for which you want to view startup agent logs.
Under Logs, click Stackdriver Logging to view Stackdriver logs.
Expand the All logs dropdown 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 dropdown menu, it has no available output.
See the Stackdriver documentation on Viewing logs for more details, including basic and advance filtering.
Handling non-UTF8 characters
Serial port output is escaped using the open source
Abseil C++ library's
method, so non-UTF8 characters are encoded as hex strings. You can use the
method to get the exact output that was emitted to the serial port.