Gravar e consultar entradas de registro com a CLI gcloud

Este documento apresenta alguns dos recursos do Cloud Logging e mostra como fazer o seguinte:

  • Gravar entradas de registro usando a Google Cloud CLI.
  • Listar entradas de registro usando a CLI gcloud.
  • Listar entradas de registro usando a API Logging.
  • visualizar e consultar entradas de registros usando o Logs Explorer.

Antes de começar

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

  1. Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  2. Instale a Google Cloud CLI.

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

  4. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Crie um Google Cloud projeto:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

    • Selecione o Google Cloud projeto que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto.

  6. Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

  7. Verifique se o faturamento está ativado para o Google Cloud projeto.

  8. Instale a Google Cloud CLI.

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

  10. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  11. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Crie um Google Cloud projeto:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

    • Selecione o Google Cloud projeto que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto.

  12. Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

  13. Verifique se o faturamento está ativado para o Google Cloud projeto.

Funções exigidas

Para receber as permissões necessárias para criar, listar e excluir entradas de registro, peça ao administrador para conceder a você o papel de administrador do Logging (roles/logging.admin) do IAM no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Os papéis de gravador de registros (roles/logging.logWriter) e visualizador de registros (roles/logging.viewer) contêm as permissões para criar e listar entradas de registro. Para excluir entradas de registro, conceda o papel de administrador do Logging (roles/logging.admin), que contém as permissões para criar, listar e excluir entradas de registro. Observe que o papel de administrador da geração de registros (roles/logging.admin) também concede permissões para realizar todas as ações na geração de registros.

Gravar entradas de registro usando a CLI 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 CLI gcloud para gravar uma entrada de registro com dados não estruturados e uma entrada de registro com dados estruturados. A CLI gcloud fornece uma interface de linha de comando para a API Cloud Logging.

  1. Para gravar uma entrada de registro com dados não estruturados no registro my-test-log, execute o gcloud logging write comando:

    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 no registro 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 dados não estruturados no Logging.

Se o registro my-test-log não existir, a geração de registros criará o registro quando a entrada de registro for recebida.

Listar entradas de registro usando a CLI gcloud

É possível recuperar entradas de registro do Logging e exibi-las usando a CLI 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'

Para informações sobre como ler registros, consulte a gcloud logging read documentação de referência.

Listar entradas de registro usando o APIs Explorer

Para executar os métodos da API Logging sem escrever código, consulte Usar o APIs Explorer. Para ler uma lista de entradas de registro do Logging, faça o seguinte:

  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. Configure e execute o comando da API:

    1. Substitua PROJECT_ID no texto a seguir:

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

    2. Copie o texto atualizado da etapa anterior e cole-o no campo Corpo da solicitação do APIs Explorer.

    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 entradas de registro na Análise de registros

Para visualizar entradas de registro no Google Cloud console, use a Análise de registros. A maioria dos Google Cloud projetos armazena um grande número de registros. É possível selecionar determinadas entradas de registro escrevendo uma consulta.

Para ver as entradas de registro que você escreveu usando a Análise de registros, faça o seguinte:

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

    Acessar a Análise de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

    Verifique se o Google Cloud projeto está selecionado na Google Cloud barra de navegação. Se necessário, use a lista suspensa do Google Cloud projeto para selecionar o Google Cloud projeto.

  2. No menu Recurso, selecione 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 ver os detalhes de uma entrada de registro, clique no Menu.

    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 informações sobre o formato de dados de entradas de registro, consulte o LogEntry tipo.

Consultar entradas de registro na Análise de registros

É possível consultar entradas de registro usando o editor de consultas 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. No Google Cloud console do, acesse a página segmento Análise de registros:

    Acessar a Análise de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

  2. No menu Recurso, selecione Global.

  3. No editor de consultas, insira a string simple entre aspas. Apenas a entrada de registro A simple entry. será exibida.

  4. Após ter visualizado seu registro, remova a string de consulta que você adicionou e clique em Executar consulta. As entradas de registro são reexibidas na tela.

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. O editor de consultas contém a linha resource.type="global". Digite este comando:

    jsonPayload.weather:partly

  2. Clique em Executar consulta. O resultado é a única entrada de registro My second entry.

O Explorador de registros também oferece consultas salvas, sugeridas e recentes. Para mais informações sobre consultas, acesse Criar consultas no Explorador de registros.

Para ver exemplos de consultas, veja Amostra de consultas usando o Explorador de registros.

Solução de problemas

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

     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 CLI 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 corrigir 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. Mude a entrada da API Cloud Logging para Completa. 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, as APIs Explorer exibe uma mensagem ou um código de erro:

    • Código de resposta 200 e nenhuma entrada: se a mensagem nextPageToken for exibida, isso indica que as APIs Explorer não tiveram 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ê escrever global como gloobal, a mensagem será Unsupported resource type: gloobal.
    • Código de resposta 404: o ID do projeto é inválido. Verifique a ortografia do identificador de projeto.
    • Você pode ser solicitado a fazer login no seu Google Cloud projeto e permitir que as APIs Explorer acessem sua conta.

Liberar espaço

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, exclua o Google Cloud projeto do e os recursos.

  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 mais informações, consulte Cotas e limites.

A seguir