Como configurar o Cloud Logging para Python

É possível gravar registros no Cloud Logging a partir de aplicativos Python usando o gerenciador de geração de registros padrão ou a biblioteca de cliente da API Cloud Logging para Python diretamente. Ao usar o gerenciador de geração de registros padrão do Python, é preciso anexar um gerenciador do Cloud Logging ao gerenciador raiz do Python. Este documento ilustra essa abordagem.

Antes de começar

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

4. Enable the Cloud Logging API.

   Enable the API

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

7. Enable the Cloud Logging API.

   Enable the API

8. Prepare o ambiente para o desenvolvimento do Python.

   Acessar o guia de configuração do Python

Instalar a biblioteca

Para instalar a biblioteca do Cloud Logging para Python, consulte Instalar a biblioteca de cliente para Python. Essa biblioteca permite anexar um gerenciador do Cloud Logging ao gerenciador raiz padrão do Python. Também é possível usar essa biblioteca para enviar solicitações de API ao Cloud Logging.

Para mais informações sobre a instalação, consulte a documentação da biblioteca do Cloud Logging para Python (em inglês). Além disso, use o rastreador de problemas (em inglês) para informá-los.

Gravar registros com o gerenciador de geração de registros padrão do Python

Para enviar todas as entradas de registro gravadas com o gerenciador raiz padrão do Python para o Cloud Logging, faça o seguinte:

1. Anexe o gerenciador do Cloud Logging ao logger raiz do Python chamando o método setup_logging:

   # Imports the Cloud Logging client library
   import google.cloud.logging
   
   # Instantiates a client
   client = google.cloud.logging.Client()
   
   # Retrieves a Cloud Logging handler based on the environment
   # you're running in and integrates the handler with the
   # Python logging module. By default this captures all logs
   # at INFO level and higher
   client.setup_logging()

   Para informações sobre como configurar o gerenciador de geração de registros, consulte Integração com a biblioteca padrão de geração de registros.

   Para informações sobre os parâmetros da função setup_logging, acesse o Cliente do Cloud Logging e pesquise setup_logging. Esta página, por exemplo, descreve como configurar os níveis de geração de registros.

2. Grave dados de registro usando o registrador raiz do Python:

   # Imports Python standard library logging
   import logging
   
   # The data to log
   text = "Hello, world!"
   
   # Emits the data using the standard logging module
   logging.warning(text)

   Por padrão, qualquer registro com nível de gravidade de pelo menos INFO que seja gravado pelo seu aplicativo é enviado para o Cloud Logging.

   Se as mensagens forem registradas no Logging do App Engine ou do Google Kubernetes Engine, o gerenciador as enviará aos respectivos tipos de recurso desses ambientes. Caso contrário, os registros serão listados no registro python no tipo de recurso Global.

Gravar registros com a biblioteca de cliente do Cloud Logging

Para informações sobre como usar diretamente a biblioteca de cliente do Cloud Logging para Python, consulte Bibliotecas de cliente do Cloud Logging.

Executar no Google Cloud

Para que um aplicativo grave registros usando a biblioteca do Cloud Logging para Python, a conta de serviço do recurso subjacente precisa ter o papel de gravador de registros (roles/logging.logWriter) IAM. A maioria dos ambientes do Google Cloud configura automaticamente a conta de serviço padrão para ter esse papel.

App Engine

O Cloud Logging é ativado automaticamente para o App Engine, e a conta de serviço padrão do aplicativo tem as permissões do IAM por padrão para gravar entradas de registro.

Saiba mais em Gravar e visualizar registros.

Google Kubernetes Engine (GKE)

O GKE concede automaticamente à conta de serviço padrão o papel do IAM Gravador de registros (roles/logging.logWriter). Se você usar a Federação de identidade da carga de trabalho para o GKE com essa conta de serviço padrão para permitir que as cargas de trabalho acessem APIs específicas do Google Cloud, nenhuma configuração adicional será necessária. No entanto, se você usar a Federação de Identidade da Carga de Trabalho para GKE com uma conta de serviço personalizada do IAM, verifique se a conta de serviço personalizada tem a função de Logs Writer (roles/logging.logWriter).

Se necessário, também é possível usar o seguinte comando para adicionar o escopo de acesso logging.write ao criar o cluster:

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

Observação: para usar a biblioteca do Cloud Logging para Python em uma instância de VM do Compute Engine, não é necessário instalar o agente do Cloud Logging.

Ao usar instâncias de VM do Compute Engine, adicione o escopo de acesso cloud-platform a cada instância. Ao criar uma nova instância no console do Google Cloud, faça isso na seção Identidade e acesso à API do painel Criar instância. Use a conta de serviço padrão do Compute Engine ou outra de sua escolha e selecione Permitir acesso completo a todas as APIs do Cloud na seção Identidade e acesso à API. Seja qual for a conta de serviço selecionada, verifique se ela recebeu o papel de gravador de registros na seção IAM e administrador do Console do Google Cloud.

Execute localmente e em outro lugar

Para usar a biblioteca do Cloud Logging para Python fora do Google Cloud, incluindo a execução da biblioteca na sua própria estação de trabalho, nos computadores do seu data center ou nas instâncias de VM de outro provedor de nuvem, você precisa fornecer o ID do projeto do Google Cloud e as credenciais da conta de serviço adequadas diretamente à biblioteca do Cloud Logging para Python.

Para contas de serviço existentes, faça o seguinte:

1. Conceda à conta de serviço o papel do IAM de gravador de registros (roles/logging.logWriter). Para mais informações sobre os papéis do IAM, consulte Controle de acesso.

2. Configure as credenciais padrão do aplicativo.

Se você não tiver uma conta de serviço, crie uma. Para saber mais sobre esse processo, consulte Criar contas de serviço.

Para informações gerais sobre os métodos que podem ser usados para autenticação, consulte Terminologia: contas de serviço.

Visualize os registros

No console do Google Cloud, acesse a página 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.

No Explorador de registros, é preciso especificar um ou mais recursos, mas a escolha deles pode não ser óbvia. Veja a seguir algumas dicas para ajudar você a começar:

• Se você estiver implantando seu aplicativo no App Engine ou usando as bibliotecas específicas dele, defina seu recurso como Aplicativo do GAE.

• Se você estiver implantando seu aplicativo no Compute Engine, defina o recurso como Instância de VM do GCE.

• Se você estiver implantando seu aplicativo no Google Kubernetes Engine, a configuração de geração de registros do cluster determinará o tipo de recurso das entradas de registro. Para uma discussão detalhada sobre o Legacy Google Cloud Observability e as soluções do Kubernetes Monitoring do Google Cloud Observability e como essas opções afetam o tipo de recurso, consulte Como migrar para o Kubernetes Monitoring do Google Cloud Observability.

• Se o aplicativo estiver usando a API Cloud Logging diretamente, o recurso dependerá da API e da configuração. Por exemplo, no seu aplicativo, é possível especificar um recurso ou usar um recurso padrão.

• Se você não vir registros no Explorador de registros, alterne para o modo de consulta avançada e use uma consulta vazia para ver todas as entradas de registro.

  1. Se quiser alternar para o modo de consulta avançada, clique no menu (▾) na parte superior do Explorador de registros e selecione Converter para filtro avançado.
  2. Limpe o conteúdo que aparece na caixa de filtro.
  3. Clique em Enviar filtro.

  É possível examinar as entradas individuais para identificar seus recursos.

Para mais informações, consulte Como usar o Explorador de registros.