Viewing Serial Port Output

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, 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, logs are retained for 30 days and Stackdriver provides the first 50 GB per month of logging for free. See Stackdriver pricing for details.

Before you begin

Enabling and disabling serial port output logging to Stackdriver

You can control whether your instances send serial port output to Stackdriver 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 is not constrained for your organization, then you can enable or disable it for projects and for individual VM instances setting the metadata serial-port-logging-enable to true or false.

At the project level, if serial-port-logging-enable is set to true, then all VM instances in the project inherit that setting implicitly. If it is set to true at the VM instance level, 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 the 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 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 Platform Console, the gcloud tool, or the API. See Setting custom metadata for details.

For example, you can use the following gcloud command to enable serial port output logging to Stackdriver for an existing instance. The command will fail if an organizational policy prevents this configuration.

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

Exclusion filters

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]"

Setting an organization policy

You can disable serial port output logging to Stackdriver for your entire organization by setting an Organization Policy, which constrains certain configurations of GCP resources. Specifically, set the following boolean constraint: constraints/compute.disableSerialPortLogging. See Creating and managing organization policies for more information.

Disabling serial port logging by setting constraints/compute.disableSerialPortLogging to true is not retroactive: existing VM instances that have metadata to enable serial port logging to Stackdriver will continue to log to Stackdriver unless you reset the metadata for those instances.

After setting this organization constraint to true, you cannot set instance or project metadata to enable serial port output logging to Stackdriver for any instances within the organization.

Viewing serial port output

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. Select the VM instance for which you want to view serial port output.
  3. 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

Use the gcloud instances get-serial-port-output command.

gcloud compute instances get-serial-port-output [INSTANCE_NAME] \
  --port [PORT] \
  --start [START] \
  --zone [ZONE]

where:

  • [INSTANCE_NAME] is the name of the instance.
  • [PORT] is number of the port (1, 2, 3, or 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.

API

In the API, create a get request to the instances.getSerialPortOutput method.

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

Stackdriver

  1. Enable serial port logging to Stackdriver
  2. Go to the VM instances page.

    Go to the VM instances page

  3. Select the VM instance for which you want to view startup agent logs.
  4. Under Logs, click Stackdriver Logging to view Stackdriver logs.

  5. 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.

  6. 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.

  7. 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 CHexEscape() method, so non-UTF8 characters are encoded as hex strings. You can use the corresponding CUnescape() method to get the exact output that was emitted to the serial port.

Bu sayfayı yararlı buldunuz mu? Lütfen görüşünüzü bildirin:

Şunun hakkında geri bildirim gönderin...

Compute Engine Documentation