Gravar e consultar entradas de registro usando um script Python

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

  • Gravar entradas de registro usando um script Python.
  • Veja as entradas de registro usando um script Python.
  • Exclua entradas de registro usando um script Python.
  • Encaminhar registros para um bucket do Cloud Storage.

O Logging pode rotear entradas de registro para os seguintes destinos:

  • Buckets do Cloud Storage
  • Conjuntos de dados do BigQuery
  • Pub/Sub
  • Buckets do Logging
  • Projetos do Google Cloud

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 não tiver o faturamento ativado para seu projeto do Google Cloud, faça o seguinte:
  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de 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. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

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

  4. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

Este guia de início rápido usa o Cloud Logging e o Cloud Storage. O uso desses recursos pode gerar um custo para você. Quando você concluir este guia de início rápido, poderá evitar o faturamento contínuo excluindo os recursos criados. Veja mais detalhes em Limpar nesta página.

Como começar

Use o ambiente do Cloud Shell ou um ambiente Linux genérico para concluir este guia de início rápido. O Python está pré-instalado no Cloud Shell.

Cloud Shell

  1. Abra o Cloud Shell e verifique a configuração do seu projeto do Google Cloud:

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

      No console do Google Cloud, clique no ícone do Cloud Shell.

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

      Esta é uma mensagem do Cloud Shell.

    2. A mensagem de recepção mostra o ID do projeto configurado no Google Cloud. Se esse não for o projeto do Google Cloud que você quer usar, execute o seguinte comando depois de substituir PROJECT_ID pelo ID do projeto:

       gcloud config set project PROJECT_ID

Linux

  1. Verifique se o Python está instalado e configurado. Para informações sobre como preparar a máquina para desenvolvimento em Python, consulte Como configurar um ambiente de desenvolvimento em Python.

  2. Instale a biblioteca de cliente do Cloud Logging:

    pip install --upgrade google-cloud-logging

  3. Configurar as permissões do Identity and Access Management do seu projeto do Google Cloud. Nas etapas a seguir, você vai criar uma conta de serviço para seu projeto do Google Cloud, gerar e fazer o download de um arquivo para a estação de trabalho do Linux.

    1. No painel de navegação do console do Google Cloud, selecione IAM e administrador e depois Contas de serviço:

      Acesse Contas de serviço

    2. Selecione seu projeto de início rápido do Google Cloud e clique em Criar conta de serviço:

      • Insira um nome para a conta.
      • Digite uma descrição para a conta.
      • Clique em Criar e continuar.

    3. Clique no campo Selecionar um papel e selecione Administrador do Logging.

    4. Clique em Concluído para terminar a criação da conta de serviço.

    5. Crie um arquivo de chave e faça o download para sua estação de trabalho:

      • Para sua conta de serviço, clique em Mais opções e selecione Gerenciar chaves.
      • No painel Chaves, clique em Adicionar chave.
      • Clique em Criar nova chave.

      • Selecione JSON como o Tipo e chave e clique em Criar. Depois de um momento, uma janela pop-up mostra uma mensagem semelhante à mostrada abaixo:

        A chave privada foi salva no seu computador.

  4. Na sua estação de trabalho do Linux, forneça suas credenciais de autenticação ao app definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho para seu arquivo de chave. Exemplo:

     export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/FILE_NAME.json"

    Essa variável de ambiente aplica-se apenas à sessão de shell atual. Portanto, se você abrir uma nova sessão, defina a variável novamente.

Clonar fonte

Para configurar o Cloud Shell neste guia de início rápido, faça o seguinte:

  1. Clone o projeto python-logging do GitHub:

      git clone https://github.com/googleapis/python-logging

    O diretório samples/snippets contém os dois scripts usados neste guia de início rápido:

    • snippets.py permite que você gerencie as entradas em um registro.
    • export.py permite que você gerencie as exportações de registros.

  2. Altere para o diretório snippets:

      cd python-logging/samples/snippets

Gravar entradas de registro

O script snippets.py usa as bibliotecas de cliente em Python para gravar entradas de registro no Logging. Quando a opção write for especificada na linha de comando, o script gravará as seguintes entradas de registro:

  • Uma entrada com dados não estruturados e nenhum nível de gravidade especificado.
  • Uma entrada com dados não estruturados e um nível de gravidade de ERROR.
  • Uma entrada com dados estruturados em JSON e nenhum nível de gravidade especificado.

Para gravar novas entradas de registro no registro my-log, execute o script snippets.py com a opção write:

python snippets.py my-log write

Exibir entradas de registro

Para visualizar as entradas de registro no Cloud Shell, execute o script snippets.py com a opção list:

python snippets.py my-log list

O comando é concluído com o resultado:

    Listing entries for logger my-log:
    * 2018-11-15T16:05:35.548471+00:00: Hello, world!
    * 2018-11-15T16:05:35.647190+00:00: Goodbye, world!
    * 2018-11-15T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}

Se o resultado não mostrar entradas, tente o comando novamente. Demora alguns momentos para o Logging receber e processar entradas de registro.

Também é possível ver suas entradas de registro usando o Explorador de registros. Para mais detalhes, acesse Visualizar registros usando o Explorador de registros.

Excluir entradas de registro

Para excluir todas as entradas de registro no my-log, execute o script snippets.py com a opção delete:

python snippets.py my-log delete

O comando é concluído com o resultado:

Deleted all logging entries for my-log.

Encaminhar registros

Nesta seção, você realizará as ações a seguir:

  • Criar um bucket do Cloud Storage como o destino dos seus dados.
  • Criar um coletor que copie novas entradas de registro para o destino.
  • Atualizar as permissões do seu bucket do Cloud Storage.
  • Gravar entradas de registro no Logging.
  • Como opção, verificar o conteúdo do seu bucket do Cloud Storage.

Criar destino

O destino de exportação para este guia de início rápido é um bucket do Cloud Storage. Para criar um bucket do Cloud Storage, siga estas etapas:

  1. No painel de navegação do console do Google Cloud, selecione Cloud Storage e clique em Buckets:

    Acesse Buckets

  2. Clique em Criar bucket.
  3. Digite um nome para o bucket.
  4. Em Tipo de local, selecione Região, que seleciona um local de bucket com a menor latência.
  5. Em Classe de armazenamento padrão, selecione Padrão.
  6. Em Controle de acesso, selecione Detalhado.
  7. Em Ferramentas de proteção, selecione Nenhum e clique em Criar.

O nome de bucket do Cloud Storage deste guia de início rápido é myloggingproject-1.

Criar coletor

Um coletor é uma regra que determina se o Logging encaminha uma entrada de registro recém-chegada para um destino. Um coletor tem três atributos:

  • Nome
  • Destino
  • Filtro

Para mais informações sobre coletores, consulte Coletores.

Se uma entrada de registro recente atender às condições da consulta, ela será encaminhada para o destino.

O script export.py usa as bibliotecas de cliente em Python para criar, listar, modificar e excluir coletores. Para criar o coletor mysink que exporta todas as entradas de registro com gravidade de pelo menos INFO para o bucket myloggingproject-1 do Cloud Storage, execute o seguinte comando:

python export.py create mysink myloggingproject-1 "severity>=INFO"

Para visualizar os coletores, execute o script export.py com a opção list:

python export.py list

O script retorna o resultado a seguir:

    mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

Atualizar permissões de destino

As permissões do destino, neste caso o bucket do Cloud Storage, não são modificadas quando você cria um coletor usando o script export.py. Altere as configurações de permissão do bucket do Cloud Storage para conceder permissão de gravação ao coletor. Para informações sobre contas de serviço, escopos de acesso e papéis do gerenciamento de identidade e acesso, consulte Contas de serviço.

Para atualizar as permissões no seu bucket do Cloud Storage:

  1. Identifique a Identidade do gravador do seu coletor:

    1. No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

      Acessar o roteador de registros

      Você verá uma tabela de resumo dos seus coletores.

    2. Encontre seu coletor na tabela, selecione Menu e depois Visualizar detalhes do coletor.

    3. Copie a identidade do gravador para a área de transferência.

  2. No painel de navegação do console do Google Cloud, selecione Cloud Storage e clique em Buckets:

    Acesse Buckets

  3. Para abrir a visualização detalhada, clique no nome do seu bucket.

  4. Selecione Permissões e clique em Conceder acesso.

  5. Cole a identidade do gravador na caixa Novas principais. Remova o prefixo serviceAccount: do endereço de identidade do gravador.

  6. Defina o Papel como Storage Object Creator e clique em Salvar.

Para mais informações, consulte Definir permissões de destino.

Validar o coletor

Para validar que seu coletor e o destino estão configurados corretamente, faça o seguinte:

  1. Grave novas entradas de registro no registro my-log:

    python snippets.py my-log write

  2. Veja o conteúdo do bucket do Cloud Storage:

    1. No painel de navegação do console do Google Cloud, selecione Cloud Storage e clique em Buckets:

      Acesse Buckets

    2. Para abrir a visualização detalhada, clique no nome do seu bucket. A vista detalhada lista as pastas que contêm dados. Se não houver dados no seu bucket, esta mensagem será exibida:

      There are no live objects in this bucket.

      Conforme descrito em Entradas de registro tardias, pode levar de 2 a 3 horas para que as primeiras entradas apareçam no destino ou antes de você ser notificado sobre um erro de configuração.

      Depois que o bucket tiver recebido dados, a visualização detalhada mostrará um resultado semelhante a este:

      Visualização detalhada do conteúdo do bucket

    3. Os dados em cada pasta são organizados em uma série de pastas identificadas. A pasta do nível superior consiste no nome do registro, seguida pelo ano, mês e dia. Para acessar os dados que foram exportados pelo coletor, clique no nome da pasta my-log e continue clicando nas subpastas de ano, mês e dia até chegar a um arquivo que termine com json:

      Visualização de subpastas de conteúdo do bucket.

    4. O arquivo JSON contém as entradas de registro que foram exportadas para seu bucket do Cloud Storage. Clique no nome do arquivo JSON para ver o conteúdo dele. O conteúdo é semelhante a:

       {"insertId":"yf1cshfoivz48",
 "logName":"projects/loggingproject-222616/logs/my-log",
 "receiveTimestamp":"2018-11-15T23:06:14.738729911Z",
 "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"},
 "severity":"ERROR",
 "textPayload":"Goodbye, world!",
 "timestamp":"2018-11-15T23:06:14.738729911Z"}

      Como o nível de gravidade de ERROR é maior que o nível de gravidade de INFO, a entrada de registro que contém a string "Goodbye, world!" é exportada para o destino do coletor. As outras entradas de registros gravadas não são exportadas para o destino porque o nível de gravidade foi configurado para o valor padrão, e o nível de gravidade padrão é menor que INFO.

Solução de problemas

Um bucket do Cloud Storage pode estar vazio por vários motivos:

  • O bucket não recebeu dados. Pode levar de 2 a 3 horas para que as primeiras entradas apareçam no destino ou antes de você ser notificado sobre um erro de configuração. Para mais informações, consulte Entradas de registro tardias.

  • Ocorreu um erro de configuração. Nesse caso, você receberá uma mensagem de e-mail parecida com a seguinte linha de assunto:

     [ACTION REQUIRED] Logging export config error in myloggingproject.

    O conteúdo do corpo do e-mail descreve o problema de configuração. Por exemplo, se você não atualizar as permissões de destino, o e-mail listará o seguinte código de erro:

     bucket_permission_denied

    Para corrigir essa condição específica, consulte Atualizar permissões de destino nesta página.

  • Nenhuma entrada de registro foi gravada após a criação do coletor. O coletor é aplicado apenas a entradas de registro recentes. Para corrigir esta situação, grave novas entradas de registro:

     python snippets.py my-log write

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.

  1. (Opcional) Exclua as entradas de registro criadas. Se você não excluir as entradas de registro, elas expirarão e serão removidas. Consulte Cotas e limites.

    Para excluir todas as entradas de registro no my-log, execute o seguinte comando:

     python snippets.py my-log delete

  2. Exclua seu projeto do Google Cloud ou os recursos do guia de início rápido.

    • Para excluir seu projeto do Google Cloud, no painel Informações do projeto do console do Google Cloud, clique em Acessar configurações do projeto e em Encerrar.

    • Para excluir os recursos do guia de início rápido:

      1. Execute o seguinte comando para excluir o coletor:

        python export.py delete mysink

      2. Exclua o bucket do Cloud Storage. Acesse o console do Google Cloud e clique em Armazenamento > Buckets. Marque a caixa ao lado do nome do bucket e clique em Excluir.

A seguir