Escreva e consulte entradas do registo através de um script Python

Este início rápido apresenta algumas das capacidades do Cloud Logging e mostra como fazer o seguinte:

  • Escrever entradas de registo com um script Python.
  • Veja as entradas do registo através de um script Python.
  • Elimine entradas do registo através de um script Python.
  • Encaminhe os registos para um contentor do Cloud Storage.

O registo pode encaminhar as entradas de registo para os seguintes destinos:

  • Contentores do Cloud Storage
  • Conjuntos de dados do BigQuery
  • Pub/Sub
  • Contentores de registo
  • Google Cloud projetos

Antes de começar

Tem de ter um Google Cloud projeto com a faturação ativada para concluir este início rápido. Se não tiver um Google Cloud projeto ou se a faturação não estiver ativada para o seu Google Cloud projeto, 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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify 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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

    6. Este início rápido usa o Cloud Logging e o Cloud Storage. A utilização destes recursos pode incorrer num custo para si. Quando terminar este início rápido, pode evitar a faturação contínua eliminando os recursos que criou. Consulte a secção Limpar nesta página para ver mais detalhes.

Começar

Pode usar o ambiente do Cloud Shell ou um ambiente Linux genérico para concluir este 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 Google Cloud projeto:

    1. Na Google Cloud consola, clique em Ativar Cloud Shell.

      O Cloud Shell é aberto numa janela e apresenta uma mensagem de boas-vindas.

    2. A mensagem de boas-vindas reflete o Google Cloud ID do projeto configurado. Se este não for o projeto que quer usar, execute o seguinte comando depois de substituir PROJECT_ID pelo ID do seu projeto: Google Cloud 

      gcloud config set project PROJECT_ID

Linux

  1. Certifique-se de que o Python está instalado e configurado. Para informações sobre como preparar a sua máquina para o desenvolvimento em Python, consulte o artigo Configurar um ambiente de desenvolvimento em Python.

  2. Instale a biblioteca cliente do Cloud Logging:

    pip install --upgrade google-cloud-logging

  3. Configure as autorizações da gestão de identidade e de acesso para o seu Google Cloud projeto. Nos passos seguintes, cria uma conta de serviço para o seu projetoGoogle Cloud e, em seguida, gera e transfere um ficheiro para a sua estação de trabalho Linux.

    1. Na Google Cloud consola, aceda à página Contas de serviço:

      Aceda a Contas de serviço

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é IAM e administração.

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

      • Introduza um nome da conta.
      • Introduza uma descrição da conta.
      • Clique em Criar e continuar.

    3. Clique no campo Selecionar uma função e selecione Administrador de registos.

    4. Clique em Concluído para terminar de criar a conta de serviço.

    5. Crie um ficheiro de chave e transfira-o para a sua estação de trabalho:

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

      • Para o Tipo de chave, selecione JSON e, de seguida, clique em Criar. Após alguns momentos, é apresentada uma janela com uma mensagem semelhante à seguinte:

        Chave privada guardada no computador.

  4. Na sua estação de trabalho Linux, indique as suas credenciais de autenticação à sua aplicação definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para o caminho do seu ficheiro de chave. Por exemplo:

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

    Esta variável de ambiente aplica-se apenas à sessão de shell atual. Por isso, se abrir uma nova sessão, defina a variável novamente.

Clonar origem

Para configurar o Cloud Shell para este início rápido, faça o seguinte:

  1. Clone o projeto do GitHub python-logging:

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

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

    • snippets.py permite-lhe gerir entradas num registo.
    • O export.py permite-lhe gerir as exportações de registos.

  2. Altere para o diretório snippets:

      cd python-logging/samples/snippets

Escrever entradas do registo

O script snippets.py usa as bibliotecas cliente Python para escrever entradas de registo no Logging. Quando a opção write é especificada na linha de comandos, o script escreve as seguintes entradas de registo:

  • Uma entrada com dados não estruturados e sem um 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 JSON e sem nível de gravidade especificado.

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

python snippets.py my-log write

Ver entradas do registo

Para ver as entradas do registo no Cloud Shell, execute o script com a opção list:snippets.py

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 apresentar nenhuma entrada, tente novamente o comando. O Logging demora alguns momentos a receber e processar as entradas do registo.

Também pode ver as entradas do registo através do Explorador de registos. Para mais detalhes, consulte o artigo Veja registos através do Explorador de registos.

Elimine entradas do registo

Para eliminar todas as entradas de registo no registo 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.

Registos de rotas

Nesta secção, faz o seguinte:

  • Crie um contentor do Cloud Storage como destino dos seus dados.
  • Crie um destino que copie novas entradas de registo para o destino.
  • Atualize as autorizações do seu contentor do Cloud Storage.
  • Escrever entradas de registo no Logging.
  • Opcionalmente, valide o conteúdo do seu contentor do Cloud Storage.

Crie um destino

O destino de exportação para este início rápido é um contentor do Cloud Storage. Para criar um contentor do Cloud Storage, faça o seguinte:

  1. Na Google Cloud consola, aceda à página Recipientes:

    Aceda a Recipientes

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Cloud Storage.

  2. Clique em Criar contentor.
  3. Introduza um nome para o contentor.
  4. Para Tipo de localização, selecione Região, que seleciona uma localização de contentor com a latência mais baixa.
  5. Para Classe de armazenamento predefinida, selecione Padrão.
  6. Para o Controlo de acesso, selecione Detalhado.
  7. Para Ferramentas de proteção, selecione Nenhuma e, de seguida, clique em Criar.

Este início rápido usa um nome de contentor do Cloud Storage de myloggingproject-1.

Criar sink

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

  • Nome
  • Destino
  • Filtro

Para mais informações sobre os destinos, consulte o artigo Destinos.

Se uma entrada de registo recém-chegada cumprir as condições da consulta, essa entrada de registo é encaminhada para o destino.

O script export.py usa as bibliotecas cliente Python para criar, listar, modificar e eliminar destinos. Para criar o destino mysink que exporta todas as entradas de registo com uma gravidade de, pelo menos, INFO para o contentor do Cloud Storage myloggingproject-1, execute o seguinte comando:

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

Para ver os seus destinos, execute o script export.py com a opção list:

python export.py list

O script devolve o seguinte:

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

Atualize as autorizações de destino

As autorizações do destino, neste caso, o seu contentor do Cloud Storage, não são modificadas quando cria um destino através do script export.py. Tem de alterar as definições de autorização do seu contentor do Cloud Storage para conceder autorização de escrita ao destino. Para obter informações sobre contas de serviço, âmbitos de acesso e funções de gestão de identidade e de acesso, consulte o artigo Contas de serviço.

Para atualizar as autorizações no seu contentor do Cloud Storage:

  1. Identifique a identidade do escritor do seu destino:

    1. Na Google Cloud consola, aceda à página Log Router:

      Aceda a Registar router

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

      É apresentada uma tabela de resumo dos seus ralos.

    2. Encontre o ralo na tabela, selecione Menu e, de seguida, selecione Ver detalhes do ralo.

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

  2. Na Google Cloud consola, aceda à página Recipientes:

    Aceda a Recipientes

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Cloud Storage.

  3. Para abrir a vista detalhada, clique no nome do seu contentor.

  4. Selecione Autorizações e clique em Conceder acesso.

  5. Cole a identidade do escritor na caixa Novos diretores. Remova o prefixo serviceAccount: do endereço de identidade do escritor.

  6. Defina a Função como Storage Object Creator e, de seguida, clique em Guardar.

Para mais informações, consulte o artigo Defina autorizações de destino.

Valide o destino

Para validar se o destino e o ponto de recolha estão configurados corretamente, faça o seguinte:

  1. Escrever novas entradas no registo my-log:

    python snippets.py my-log write

  2. Ver o conteúdo do seu contentor do Cloud Storage:

    1. Na Google Cloud consola, aceda à página Recipientes:

      Aceda a Recipientes

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Cloud Storage.

    2. Para abrir a vista detalhada, clique no nome do seu contentor. A vista detalhada apresenta as pastas que contêm dados. Se não existirem dados no seu contentor, é apresentada a seguinte mensagem:

      There are no live objects in this bucket.

      Conforme descrito no artigo Entradas de registo com atraso, podem decorrer 2 ou 3 horas antes de as primeiras entradas aparecerem no destino ou antes de receber uma notificação de um erro de configuração.

      Depois de o grupo ter recebido dados, a vista detalhada mostra um resultado semelhante ao seguinte:

      Vista detalhada do conteúdo do contentor.

    3. Os dados em cada pasta estão organizados numa série de pastas etiquetadas com o nome da pasta de nível superior, seguido do ano, mês e dia. Para ver os dados que foram exportados pelo destino, clique no nome da pasta my-log e, de seguida, continue a clicar nas subpastas do ano, mês e dia até aceder a um ficheiro que termina com json:

      Vista da subpasta de conteúdos do intervalo.

    4. O ficheiro JSON contém as entradas do registo que foram exportadas para o seu contentor do Cloud Storage. Clique no nome do ficheiro JSON para ver o respetivo conteúdo. 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"}

      Uma vez que o nível de gravidade de ERROR é superior ao nível de gravidade de INFO, a entrada de registo que contém a string "Goodbye, world!" é exportada para o destino do coletor. As outras entradas de registo que foram escritas não foram exportadas para o destino porque o respetivo nível de gravidade foi definido para o valor predefinido, e o nível de gravidade predefinido é inferior a INFO.

Resolução de problemas

Existem vários motivos pelos quais um contentor do Cloud Storage pode estar vazio:

  • O contentor não recebeu dados. Pode demorar 2 ou 3 horas até que as primeiras entradas apareçam no destino ou até que receba uma notificação de erro de configuração. Para mais informações, consulte o artigo Entradas de registo com atraso.

  • Existe um erro de configuração. Neste caso, recebe uma mensagem de email com uma linha de assunto semelhante à seguinte:

     [ACTION REQUIRED] Logging export config error in myloggingproject.

    O conteúdo do corpo do email descreve o problema de configuração. Por exemplo, se não atualizar as autorizações de destino, as listas de correio eletrónico apresentam o seguinte código de erro:

     bucket_permission_denied

    Para corrigir esta condição específica, consulte a secção Atualize as autorizações do destino nesta página.

  • Não foram escritas entradas de registo após a criação do destino. O destino é aplicado apenas a entradas de registo recebidas recentemente. Para corrigir esta situação, escreva novas entradas de registo:

     python snippets.py my-log write

Limpar

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

  1. (Opcional) Elimine as entradas no registo que criou. Se não eliminar as entradas do registo, estas expiram e são removidas. Consulte as quotas e os limites.

    Para eliminar todas as entradas do registo no registo my-log, execute o seguinte comando:

     python snippets.py my-log delete

  2. Elimine o Google Cloud projeto ou elimine os recursos de início rápido.

    • Para eliminar o seu Google Cloud projeto, no painel Google Cloud Informações do projeto da consola, clique em Aceder às definições do projeto e, de seguida, clique em Encerrar.

    • Para eliminar os recursos de início rápido:

      1. Elimine o seu destino executando o seguinte comando:

        python export.py delete mysink

      2. Elimine o seu contentor do Cloud Storage. Aceda à Google Cloud consola e clique em Armazenamento > Contentores. Selecione a caixa junto ao nome do contentor e, de seguida, clique em Eliminar.

O que se segue?