Como visualizar a saída da porta serial

Uma instância do Compute Engine 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. Se você precisa enviar comandos para uma porta serial enquanto uma instância está em execução, consulte Como interagir com o console serial.

Para ver a saída da porta serial de uma instância de computação em execução, use o console Google Cloud , a CLI gcloud ou a REST. Esses métodos fornecem apenas o 1 MB de saída mais recente por porta. Para ver a saída que excede 1 MB por porta ou de instâncias interrompidas, use o Cloud Logging.

Antes de começar

  • Para registrar a saída da porta serial no Cloud Logging, familiarize-se com o Cloud Logging.
  • Configure a autenticação, caso ainda não tenha feito isso. Com isso, você confirma sua identidade para acesso a serviços e APIs do Google Cloud . Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o console Google Cloud para acessar serviços Google Cloud e APIs, não é necessário configurar a autenticação.

    gcloud

    1. Instale a CLI do Google Cloud. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

      gcloud init

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  • Defina uma região e uma zona padrão.

    • REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para CLI gcloud.

      Instale a CLI do Google Cloud.

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

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 definindo uma política da organização.

Por padrão, a geração de registros de saída da porta serial para o Cloud Logging está desativada. 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 sem custo financeiro e manterá os registros por 30 dias.

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 computação 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 computação no projeto herdam essa configuração implicitamente. Se você definir uma entrada de metadados de instância, ela será ativada apenas para essa instância de computação, independentemente da configuração do projeto.

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

Por exemplo, o comando da CLI 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 CLI 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 da Análise 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 computação 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. Para mais informações, consulte 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 computação 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.

Ver a saída da porta serial

Use o console do Google Cloud , a CLI gcloud ou REST para ver o 1 MB mais recente de saída por porta serial de instâncias em execução. Para ver a saída que excede 1 MB por porta ou de instâncias interrompidas, use o Cloud Logging.

Console

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

    Acessar a página "Instâncias de VM"

  2. Selecione a instância de computação para visualizar a saída da porta serial.

  3. Em Registros, clique em Porta serial 1 (console), Porta serial 2 (console), Porta serial 3 ou Porta serial 4.

    As entidades no nível do sistema geralmente usam a porta serial 1, que também é conhecida como console serial.

gcloud

Para ver a saída da porta serial de uma instância de computação em execução, 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.

REST

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

Antes de visualizar esses registros, é necessário enviar a saída da porta serial para o Cloud Logging.

  1. No console do Google Cloud , acesse a página Análise de registros.

    Acessar a Análise de registros

  2. No painel Consulta, insira a consulta a seguir e clique em Executar consulta:

    resource.type="gce_instance"
logName="projects/PROJECT_ID/logs/serialconsole.googleapis.com%2Fserial_port_1_output"
resource.labels.instance_id="INSTANCE_ID"

    Substitua:

    • PROJECT_ID: o ID do projeto que continha a instância.
    • INSTANCE_ID: o ID da instância de computação.

Para mais informações sobre como filtrar na Análise de registros, consulte Ver registros usando a Análise de 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.