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 Cloud Console, the
gcloud 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 Logging, logs are retained for 30 days and Stackdriver Logging provides the first 50 GB per month of logging for free. See Stackdriver Logging 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 Logging, familiarize yourself with Stackdriver Logging.
Enabling and disabling serial port output logging
You can control whether your instances send serial port output to Stackdriver 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 Stackdriver Logging is not
constrained for your organization,
then you can enable or disable it for projects and for individual VM
instances by setting the metadata
If you set project-wide metadata
serial-port-logging-enable:true, then all VM instances in the
project inherit that setting implicitly. If you
set instance metadata,
then it is enabled for that VM only, regardless of the project setting.
Conversely, to disable serial port output logging for projects or instances, set
serial-port-logging-enable metadata value to
false. When this metadata
is set to
false at the project level, serial port output logging to
Stackdriver Logging is disabled for all instances in the project. When it is set to
false at the instance level, then serial port logging is disabled for that VM
only, regardless of the project setting.
You can set metadata through the Google Cloud Console, the
gcloud tool, or
the API. See
Setting custom metadata
For example, you can use the following
gcloud tool command to enable
serial port output logging to Stackdriver Logging for your project.
gcloud compute project-info add-metadata \ --metadata serial-port-logging-enable=true \ --project bct-staging-loadtest
Or use the following
gcloud tool command to enable serial port
output logging to Stackdriver Logging for a specific instance.
gcloud compute instances add-metadata instance-name \ --metadata serial-port-logging-enable=true
To disable serial port output logging to Stackdriver Logging, set
gcloud compute instances add-metadata instance-name \ --metadata serial-port-logging-enable=false
From within Stackdriver Logging, 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/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 Stackdriver Logging for your entire
organization by setting an
Organization Policy, which
constrains certain configurations of Google Cloud resources. Specifically,
set the following boolean constraint:
Creating and managing organization policies for more information.
Disabling serial port logging by setting
true is not
retroactive: existing VM instances that have metadata to enable serial port
logging to Stackdriver Logging will continue to log to Stackdriver Logging unless
you reset the metadata for those
After setting this organization constraint to
true, you cannot set instance or
project metadata to enable serial port output logging to Stackdriver Logging for
any instances within the organization.
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 Logging
- 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 Logging 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.
Optionally, expand the Any log level dropdown 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.
See the Stackdriver Logging 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.