Guia de início rápido sobre como usar as ferramentas do Logging

Neste guia de início rápido, apresentamos alguns dos recursos do Cloud Logging e mostramos como:

  • gravar entradas de registro usando a ferramenta de linha de comando do gcloud;
  • listar entradas de registro usando a ferramenta de linha de comando do gcloud;
  • listar entradas de registro usando a API Logging;
  • visualizar e consultar as entradas de registro usando o Visualizador de registros.

Antes de começar

Você precisa ter um projeto do Google Cloud com faturamento ativado para concluir este guia de início rápido. Se você não tiver um projeto do Google Cloud ou se o faturamento não estiver ativado para o projeto, faça o seguinte:
  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página do seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

Primeiros passos

O SDK do Cloud tem um grupo de comandos, gcloud logging, que fornece uma interface de linha de comando para a API Cloud Logging.

É possível usar o ambiente do Cloud Shell ou uma instância de máquina virtual (VM) do Compute Engine para os comandos da ferramenta de linha de comando gcloud abordadas neste guia de início rápido.

Cloud Shell

  1. O SDK do Cloud está pré-instalado no ambiente do Cloud Shell. Você não precisa instalar ou configurar nenhum outro software.

  2. Abra o Cloud Shell e verifique a configuração do projeto:

    1. No Console do Cloud, clique em Ativar o Cloud Shell:

      Ativar o Cloud Shell

      O Cloud Shell é aberto em uma janela e exibe uma mensagem de boas-vindas:

      Bem-vindo ao Cloud Shell

    2. A mensagem de boas-vindas exibe o código do projeto configurado. Se esse não for o projeto que você quer usar, execute o seguinte comando depois de substituir [PROJECT_ID] pelo código do projeto:

       gcloud config set project [PROJECT_ID]
      

Instância da VM

  1. Crie uma instância de VM no Compute Engine.

    1. No Console do Cloud, selecione Compute Engine > instâncias de VM. Selecione Criar. Se a mensagem a seguir for exibida, aguarde até que o Compute Engine esteja pronto para prosseguir:

      Preparação do Compute

    2. Em Identidade e acesso à API, selecione Definir acesso para cada API. Percorra a listagem até encontrar a API Cloud Logging. Alterne o acesso de Somente gravação para Completo:

      Preparação do Compute

    3. Deixe todas as outras configurações nos valores padrão e clique em Criar. Depois de um momento, a instância de VM estará pronta para seu uso.

  2. Para se conectar ao shell da instância da VM, vá para SSH > Abrir na janela do navegador. Depois de um momento, um shell do Debian GNU/Linux será aberto em uma janela exibindo uma mensagem de boas-vindas.

  3. O SDK do Cloud é pré-instalado na instância de VM do GCM. Para verificar se o SDK do Cloud está configurado para o projeto do Compute Engine, execute este comando:

     gcloud config list
    
  4. Se o projeto listado não for o que você quer usar, execute o seguinte comando depois de substituir [PROJECT_ID] pelo código do projeto:

     gcloud config set project [PROJECT_ID]
    

Gravar entradas de registro usando a ferramenta gcloud

A geração de registros aceita entradas de registro com dados estruturados e não estruturados. Os dados estruturados consistem em uma estrutura de dados JSON (por exemplo, {"weather": "partly cloudy"}). Os dados não estruturados são uma string de caracteres (por exemplo, "A simple entry"). Nas próximas etapas, você usará a ferramenta gcloud para gravar uma entrada de registro com dados não estruturados e uma entrada de registro com dados estruturados:

  1. Grave uma entrada de registro com dados não estruturados no registro my-test-log:

    gcloud logging write my-test-log "A simple entry."
    

    Depois que o comando for concluído, você verá a mensagem: Created log entry.

  2. Grave uma entrada de registro com dados estruturados em my-test-log:

    gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
    

    Ao gravar uma entrada de registro com dados estruturados, é preciso incluir --payload-type=json. Se você omitir esse campo, o payload será interpretado como texto não estruturado no Logging.

Se my-test-log não existir, o Logging criará o registro quando a entrada for recebida.

Listar entradas de registro usando a ferramenta gcloud

É possível recuperar entradas de registro do Logging e exibi-las usando a ferramenta gcloud. Por exemplo, para recuperar e exibir as entradas de registro com o tipo de recurso global, execute o seguinte comando:

gcloud logging read "resource.type=global"

O comando retorna um resultado semelhante ao seguinte:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

Listar entradas de registro usando o API Explorer

Use o API Explorer para executar os métodos da API Logging sem gravar códigos. Para ler uma lista de entradas de registro no Logging:

  1. Acesse a página de referência da API sobre o método de API entries.list:

    Acessar a página da "API entries.list"

  2. O widget do API Explorer é exibido. Ele tem o cabeçalho Testar esta API. Copie e cole o texto a seguir no Corpo da solicitação. Antes de clicar em Executar, substitua [PROJECT_ID].

      "resourceNames": [
        "projects/[PROJECT_ID]"
      ],
      "filter": "resource.type=global",
      "orderBy": "timestamp desc"
    

    Um exemplo de um corpo de solicitação preenchido com essas configurações é mostrado abaixo:

    Testar esta API

  3. Clique em Executar. O método retorna uma resposta semelhante à seguinte:

    {
      "entries": [
        {
          "textPayload": "A simple entry",
          "insertId": "vd4m1if7h7u1a",
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:19.718100792Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
        },
        {
          "insertId": "jpj9zjf73t1mn",
          "jsonPayload": {
            "message": "My second entry",
            "weather": "partly cloudy"
          },
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:31.114507977Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
        }
      ]
    }
    

Ver registros no Visualizador de registros

O Visualizador de registros é uma ferramenta para visualizar, consultar e fazer o download das entradas de registro. Para visualizar os registros no Visualizador de registros, faça o seguinte:

  1. Acesse o Visualizador de registros no Console do Google Cloud:

    Acessar o "Visualizador de registros"

    Você verá a página Visualizador de registros:

    Visualizador de registros

    Verifique na barra de navegação do Google Cloud se o seu projeto está selecionado. Use a lista suspensa do projeto para selecioná-lo, se necessário.

  2. Na lista suspensa do tipo de recurso, selecione Global para visualizar as entradas de registro que você gravou:

    Visualizador de registros Global

    Se a opção de menu Global ou as entradas de registro não forem exibidas, aguarde alguns minutos e atualize a página. Pode demorar alguns minutos para o Logging receber entradas de registro.

  3. Para expandir uma entrada de registro, clique no menu .

    Visualizador de registros

    A primeira entrada de registro tem os dados armazenados em textPayload. A segunda entrada de registro contém dados estruturados armazenados em jsonPayload. O payload estruturado contém as chaves message e weather.

Para mais informações sobre formatos de dados de entrada de registro, consulte o tipo LogEntry.

Consultar entradas de registro no Visualizador de registros

É possível consultar entradas de registro usando um campo de texto e, as que têm registros estruturados, pela chave e pelo valor. Por exemplo, para exibir todas as entradas de registro que têm o texto simple, faça o seguinte:

  1. Na caixa de consulta de pesquisa, insira a string simple. Apenas a entrada de registro A simple entry. será exibida.

  2. Após ter visualizado seu registro, remova a string de consulta que você adicionou e clique em atualizar (). As duas entradas de registro voltam a aparecer na exibição.

Para exibir todas as entradas de registro com dados estruturados que tenham uma chave weather em que o campo value contém partly, faça o seguinte:

  1. Alterne para o modo de consulta avançada clicando no menu suspenso na caixa de consulta e selecionando Converter para filtro avançado.
  2. A caixa de consulta contém a linha resource.type="global". Abaixo dessa linha, insira esta linha:

    jsonPayload.weather:partly
    
  3. Clique em Enviar filtro. O resultado é My second entry como a única entrada de registro:

    Consulta avançada de entradas de registro

Para mais informações sobre consultas, acesse Consultas de registros avançados.

Solução de problemas

  • Os erros tipográficos e os nomes de campos desconhecidos resultam em comandos da ferramenta gcloud preenchidos com mensagens de argumento inválido. Por exemplo, se você esquecer o ponto em resource.type, o resultado será o erro:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • Quando o Cloud Logging não tiver recebido as permissões de acesso necessárias, os comandos da ferramenta gcloud resultarão em mensagens de permissão negada. Por exemplo, se uma instância de VM do Compute Engine estiver configurada com as configurações padrão da API, o comando list resultará em um erro de permissão negada:

     ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
    

    Para resolver essa condição, modifique as permissões da instância de VM do Compute Engine para conceder permissão de leitura ao Cloud Logging da seguinte forma:

    1. Acesse a página Detalhes da instância de VM. Clique em Interromper. Essa ação pode levar um ou dois minutos para ser concluída.
    2. Para modificar a configuração, clique em Editar.
    3. Procure o cabeçalho Escopos de acesso da API Cloud e clique em Detalhes para exibir as configurações de cada API. Altere a entrada da API Cloud Logging para Total. Clique em Salvar.
    4. Para reiniciar a instância de VM, clique em Iniciar. Depois de alguns momentos, sua VM estará pronta para uso.
  • Quando não consegue concluir seu comando ou requer outras autorizações, o API Explorer exibe uma mensagem ou um código de erro:

    • Código de resposta 200 e nenhuma entrada: a mensagem nextPageToken indica que o API Explorer não teve tempo para concluir a pesquisa. Adicione um pageToken à solicitação, defina o valor para ser o mesmo fornecido com a chave nextPageToken e, em seguida, tente executar o comando novamente.
    • Código de resposta 400: o valor da consulta é inválido. Por exemplo, se você digitou global como gloobal, a mensagem é Unsupported resource type: gloobal.
    • Código de resposta 404: o código do projeto é inválido. Verifique a ortografia do identificador de projeto.
    • Você pode ser solicitado a fazer login na conta do Google e permitir que o API Explorer acesse a conta.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, siga estas etapas:

  1. (Opcional) Para excluir as entradas de registro que você criou, execute o seguinte comando do gcloud:

    gcloud logging logs delete my-test-log
    

    Se você não excluir as entradas de registro, elas expirarão e serão removidas. Para informações sobre retenção, acesse Cotas e limites.

A seguir

  • Para detalhes sobre a interface de linha de comando do Logging, leia as páginas de referência para o grupo de comandos gcloud logging.
  • Para ver a documentação sobre a API Logging, leia API Cloud Logging.
  • Para detalhes sobre o Visualizador de registros, acesse Visualizador de registros.
  • Para saber como coletar entradas de registro de suas instâncias de VM no Logging, acesse Sobre o agente do Logging.