Guia de início rápido sobre o uso do 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

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 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 o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  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 o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

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 Cloud:

    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 ecoa o ID do projeto do Cloud configurado. Se este não for o projeto do 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. Configure as permissões de gerenciamento de identidade e acesso do projeto do Cloud. Nas etapas a seguir, você criará uma conta de serviço para seu projeto e gerará e fará o download de um arquivo para sua estação de trabalho do Linux.

    1. No Console do Cloud, vá para IAM e administrador> Contas de serviço:

      Acessar Contas de serviço

    2. Selecione seu projeto de início rápido do 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
    3. No painel Permissões da conta de serviço (opcional), em Papel, selecione Administrador do Logging na lista suspensa. Clique em Continuar.

    4. Ignore a opção para conceder aos usuários acesso à conta de serviço.

    5. Clique em Concluído.

    6. 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.
      • 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:

        Chave privada salva

  3. 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. Consulte Ver registros no explorador de registros para mais detalhes.

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 Cloud, acesse Storage e selecione Navegador:

    Acessar o navegador

  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. Acesse a página Roteador de registros:

      Acessar o roteador de registros

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

    2. Localize o coletor na tabela, selecione o menu e, depois, Visualizar detalhes do coletor.

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

  2. No Console do Cloud, clique em Storage e selecione Navegador:

    Acessar o navegador

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

  4. Selecione Permissões e clique em Adicionar.

  5. Defina o Papel como Storage Object Creator e insira a identidade do gravador do coletor.

Consulte Permissões de destino para mais informações.

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 Cloud, clique em Storage e selecione Navegador:

      Acessar o navegador

    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 Disponibilidade de registros exportados, 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:

      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:

      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 saber mais sobre por que os registros podem atrasar, consulte Disponibilidade dos registros exportados.

  • 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 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 ou os recursos do guia de início rápido.

    • Para excluir o projeto, acesse o painel Informações do projeto do Console do 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 Cloud e clique em Armazenamento > Navegador. Marque a caixa ao lado do nome do bucket e clique em Excluir.

A seguir