Como visualizar a saída da porta serial

Uma instância de máquina virtual (VM) tem quatro portas seriais virtuais. O sistema operacional da instância, a BIOS e outras entidades no nível do sistema geralmente gravam a saída nas portas seriais, o que torna a saída da porta serial útil para solucionar falhas, inicializações com falha, problemas de inicialização ou de desligamento.

Nesta página, você aprenderá sobre os métodos para visualizar a saída da porta serial, incluindo o uso do Cloud Logging para reter a saída da porta serial mesmo depois que uma instância for interrompida ou excluída. Se você precisa enviar comandos para uma porta serial enquanto uma instância está em execução, consulte Como interagir com o console serial.

A saída da porta serial pode ser acessada pelo Console do Cloud, pela ferramenta gcloud e pela API Compute Engine, mas somente enquanto a instância de VM estiver em execução. Os registros são limitados ao 1 MB de saída mais recente por porta.

Se você ativar a geração de registros de saída da porta serial, o Cloud Logging fornecerá os primeiros 50 gibibytes (GiB) por mês de geração de registros gratuitamente e manterá os registros por 30 dias.

Antes de começar

Para usar os exemplos de linha de comando deste guia, faça o seguinte:
1. Instale a ferramenta de linha de comando gcloud ou a atualize para a versão mais recente.
2. Defina uma região e uma zona padrão.
Para usar os exemplos da API deste guia, configure o acesso a ela.
Para registrar a saída da porta serial no Cloud Logging, familiarize-se com o Cloud Logging.

Como ativar e desativar a geração de registros de saída da porta serial

É possível controlar se as instâncias enviam a saída da porta serial para o Cloud Logging ao definir metadados no nível da instância ou para envolvidos no projeto. Também é possível desativar o recurso para todos os usuários em sua organização ao definir uma política da organização.

Como definir metadados de projeto e instância

Se a geração de registros de saída da porta serial para o Cloud Logging não for restrita para sua organização, será possível ativá-la ou desativá-la para projetos e instâncias de VM individuais definindo a entrada de metadados serial-port-logging-enable como true ou false.

Quando você define uma entrada de metadados para todo o projeto, todas as instâncias de VM no projeto herdam essa configuração implicitamente. Se você definir uma entrada de metadados de instância, essa entrada será ativada apenas para essa VM, independentemente da configuração do projeto.

É possível definir uma entrada de metadados usando o Console do Google Cloud, a ferramenta gcloud ou a API do Compute Engine. Saiba mais em Como configurar metadados personalizados.

Por exemplo, o comando da ferramenta gcloud a seguir ativa a geração de registros de saída da porta serial para o Cloud Logging no projeto:

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

Da mesma forma, o comando da ferramenta gcloud a seguir ativa a geração de registros de saída da porta serial para o Cloud Logging em uma instância específica:

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

Para desativar a geração de registros de saída da porta serial para o Cloud Logging, defina serial-port-logging-enable como false.

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

Filtros de exclusão

No Cloud Logging, é possível criar um filtro de exclusão para remover entradas de porta serial específicas do visualizador de registros. Por exemplo, com uma entrada de metadados para todo o projeto definida como serial-port-logging-enable=true, é possível desativar a geração de registros de saída da porta serial para instâncias de VM específicas usando um filtro avançado:

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"

Como definir uma política da organização

Desative a geração de registros de saída da porta serial para o Cloud Logging em toda a organização configurando uma política da organização, que restringe certas configurações de recursos do Google Cloud. Especificamente, defina a seguinte restrição booleana: constraints/compute.disableSerialPortLogging. Saiba mais em Como criar e gerenciar políticas da organização.

A desativação da geração de registros da porta serial definindo constraints/compute.disableSerialPortLogging como true não é retroativa. As instâncias de VM atuais com uma entrada de metadados que permite a geração de registros da porta serial para o Cloud Logging continuarão a registrar no Cloud Logging, a menos que você redefina os metadados dessas instâncias.

Depois de definir essa restrição de organização como true, não será possível definir metadados de instância ou projeto para ativar a geração de registros de saída da porta serial no Cloud Logging em instâncias da organização.

Como visualizar a saída da porta serial

Console

No Console do Google Cloud, acesse a página Instâncias de VM.

Acessar a página "Instâncias de VM"
Selecione a instância de VM para visualizar a saída da porta serial.
Em Registros, clique em Porta serial 1, 2, 3 ou 4. As entidades no nível do sistema geralmente usam a primeira porta serial (porta 1), que também é conhecida como console serial.

gcloud

Use o comando gcloud compute instances get-serial-port-output.

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

Substitua:

INSTANCE_NAME: o nome da instância.
PORT: o número da porta (1, 2, 3 ou 4) da qual você quer visualizar a saída. As entidades no nível do sistema costumam usar a primeira porta serial (porta 1), que também é conhecida como console serial. Por padrão, a saída da primeira porta serial é retornada.
START: o índice de bytes (base zero) do primeiro byte que você quer retornar. Use essa sinalização se quiser continuar recebendo a saída de uma solicitação anterior que era longa demais para ser retornada em uma tentativa.
ZONE: a zona da instância.

API

Na API, crie uma solicitação get para o método instances.getSerialPortOutput.

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

Cloud Logging

Ative a geração de registros da porta serial para o Cloud Logging.
Acesse a página Instâncias da VM.

Acessar a página "Instâncias de VM"
Selecione a instância de VM em que você quer ver os registros do agente de inicialização.
Em Registros, clique em Cloud Logging para visualizar os registros do Cloud Logging.
Expanda o menu suspenso Todos os registros e selecione a saída da porta serial que você quer ver. As entidades no nível do sistema geralmente usam a primeira porta serial (porta 1), que também é conhecida como console serial. Se uma porta não for exibida no menu suspenso, significa que ela não tem saída disponível.
Se quiser, expanda o menu suspenso Qualquer nível de registro para desativar os registros que estão abaixo do nível de gravidade que você quer ver. Por exemplo, se você selecionar o nível de registro "Informações", desativará as entradas de registro "Depurar". As entradas "Depurar" são normalmente usadas apenas pelo BIOS no momento da inicialização.

Veja mais informações, inclusive sobre filtros básicos e avançados, em Como ver os registros.

Como processar caracteres não UTF8

A saída da porta serial é marcada com escape usando o método CHexEscape() de código aberto da biblioteca C++ do Abseil (em inglês), para que os caracteres não UTF8 sejam codificados como strings hexadecimais. É possível usar o método CUnescape() correspondente para ver a saída exata que foi enviada para a porta serial.