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 se o faturamento não estiver ativado para o projeto do Google Cloud, faça o seguinte:
  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

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.

Primeiros passos

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 projeto do Google Cloud:

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

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

    2. A mensagem de boas-vindas ecoa o ID do projeto do Google Cloud configurado. Se este não for o projeto do Google Cloud que você quer usar, execute o seguinte comando depois de substituir PROJECT_ID pelo ID do seu 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. Configure 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 e gerar e fazer o download de um arquivo para sua estação de trabalho do Linux.

    1. No console do Google Cloud, acesse a página Contas de serviço:

      Acesse Contas de serviço

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

    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 de registro.

    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:

      • Na 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 mostra uma mensagem semelhante a esta:

        Chave privada 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. Por 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, consulte Conferir 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 console do Google Cloud, acesse a página Buckets:

    Acessar Buckets

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

  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 Console do Google Cloud, acesse a página Roteador de registros:

      Acessar o roteador de registros

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

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

    2. Encontre o coletor na tabela, selecione Menu e Ver detalhes do coletor.

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

  2. No console do Google Cloud, acesse a página Buckets:

    Acessar Buckets

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

  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 escritor na caixa Novos 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 console do Google Cloud, acesse a página Buckets:

      Acessar Buckets

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

    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 com atraso, 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 da subpasta 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 com atraso.

  • 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 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, acesse o painel Informações do projeto do console do Google Cloud e clique em Acessar configurações do projeto e 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