Como migrar para o Cloud Logging

Com apenas algumas linhas de código, você pode atualizar seu aplicativo para usar o Cloud Logging e alcançar quase os mesmos recursos de filtragem e correlação de registros disponíveis com o serviço de geração de registros do App Engine.

Para migrar para o Cloud Logging, anexe o gerenciador de registro AppEngineHandler ao módulo de criação de registro do Python, em seguida, continue usando o módulo para gravar as entradas de registro. É possível fazer essas atualizações no seu aplicativo Python 2 e ver o mesmo comportamento de geração de registros quando o aplicativo é executado nos ambientes de execução do Python 2 ou 3.

Principais diferenças entre a geração de registros do App Engine e o Cloud Logging

  • A geração de registros do App Engine requer o uso do módulo de geração de registros do Python para gravar as entradas de registro no aplicativo. O Cloud Logging é compatível com todas as abordagens a seguir:

    • (Recomendado) Use o módulo de geração de registros do Python com AppEngineHandler como gerenciador de geração de registro. Esta abordagem idiomática requer apenas algumas linhas adicionais de código para registrar o gerenciador do Cloud Logging e, portanto, torna o aplicativo mais portátil a outros ambientes Python.

    • Grave entradas em stdout ou stderr. Estas entradas são exibidas no Explorador de Registros, mas para permitir a filtragem e correlação com os registros solicitados, é necessário formatar as entradas como um objeto JSON e fornecer metadados específicos. Para mais informações sobre essa abordagem, consulte Geração de registros estruturada.

    • Use a biblioteca de cliente do Cloud Logging diretamente. Se você usar o AppEngineHandler, essa abordagem alcança o mesmo resultado de um módulo de geração de registros do Python, porém, alterar desta biblioteca para uma estrutura diferente de geração de registros poderia exigir atualizações significativas do código.

  • Com o gerador de registros do App Engine, o Explorador de Registros atribui um nível de gravidade aos registros solicitados e este nível reflete a gravidade mais alta de qualquer entrada de registro do aplicativo que esteja correlacionada à solicitação. Por exemplo, se uma solicitação resultar na emissão de uma entrada de registro de alerta pelo aplicativo, o Explorador de Registros exibirá um ícone de alerta ao lado da entrada de registro da solicitação. Ao expandir a entrada da solicitação, será possível ver a entrada de registro de alerta aninhada dentro da entrada da solicitação.

    Com o Cloud Logging, o visualizador de registros não atribui um nível de gravidade aos registros de solicitação. Ao expandir uma entrada de solicitação, será possível ver as entradas do aplicativo aninhadas na entrada da solicitação e as entradas do aplicativo exibirão um ícone de gravidade. Porém, a entrada da solicitação não exibirá um ícone de gravidade e não poderá ser filtrada pelo nível de gravidade.

  • Cotas e retenção de dados são iguais para o App Engine e o Cloud Logging, mas se você exceder a cota gratuita de dados de registros, os preços do Cloud Logging podem ser diferentes dos preços de registros do App Engine.

Antes de começar a migração

  1. Ative a API do Cloud Logging no projeto que contém o aplicativo.

    Ativar a API

  2. Verifique se o aplicativo tem permissão para gravar registros.

    Por padrão, a conta de serviço padrão do aplicativo tem permissão para gravar registros.

    Se o aplicativo usa uma conta de serviço ou de usuário diferente ou se você alterou as permissões da conta de serviço padrão, verifique se a conta usada tem permissão para gravar registros.

Visão geral do processo de migração

Para migrar seu aplicativo Python para usar o Cloud Logging em vez do registro do App Engine:

  1. Instale a biblioteca de cliente do Cloud para o Cloud Logging.

  2. Anexe AppEngineHandler ao módulo de geração de registros do Python.

  3. Implante seu aplicativo no App Engine e confirme se a geração de registros funciona conforme o esperado.

Como instalar a biblioteca de cliente do Cloud para Cloud Logging

Para disponibilizar AppEngineHandler para seu aplicativo quando ele é executado no App Engine:

  1. Crie um arquivo requirements.txt na mesma pasta do app.yaml e adicione as seguintes linhas:

     google-cloud-logging==1.14.0
    

    Recomendamos que você use a versão 1.14.0 da biblioteca de cliente do Cloud Logging, já que ela é compatível com aplicativos Python 2.7.

  2. No arquivo app.yaml do aplicativo, especifique as bibliotecas RPC e setuptools do Google e a biblioteca SSL opcional na seção libraries:

    libraries:
    - name: grpcio
      version: 1.0.0
    - name: setuptools
      version: 36.6.0
    - name: ssl
      version: latest
    

    Algumas bibliotecas de cliente não precisam da biblioteca SSL. Se você não incluir a biblioteca SSL para uma biblioteca de cliente que precisa dela, verá um erro SSL no Explorador de registros quando o aplicativo receber uma solicitação.

  3. Crie um diretório para armazenar bibliotecas de terceiros, como lib/. Em seguida, use pip install para instalar as bibliotecas no diretório. Por exemplo:

      pip install -t lib -r requirements.txt
      

  4. Crie um arquivo appengine_config.py na mesma pasta que seu arquivo app.yaml. Adicione a instrução a seguir ao seu arquivo appengine_config.py:

    # appengine_config.py
    import pkg_resources
    from google.appengine.ext import vendor
    
    # Set path to your libraries folder.
    path = 'lib'
    # Add libraries installed in the path folder.
    vendor.add(path)
    # Add libraries to pkg_resources working set to find the distribution.
    pkg_resources.working_set.add_entry(path)
    

    O arquivo appengine_config.py no exemplo anterior pressupõe que a pasta lib está localizada no diretório de trabalho atual. Se não for possível garantir que lib estará sempre no diretório de trabalho atual, especifique o caminho completo para a pasta lib. Por exemplo:

    import os
    path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
    

Para desenvolvimento local, recomendamos que você instale dependências em um ambiente virtual, como o virtualenv para Python 2.

Como anexar AppEngineHandler ao módulo de geração de registro do Python

Em cada arquivo que grava entradas de registro:

  1. Importe a biblioteca de cliente do Cloud Logging.
  2. Instancie o cliente do Cloud Logging.
  3. Recupere o gerenciador do Cloud Logging apropriado para o ambiente atual. Quando o aplicativo é executado no App Engine, o cliente do Cloud Logging recupera AppEngineHandler.

    AppEngineHandler formatará as entradas como um objeto JSON e fornecerá os metadados necessários para oferecer suporte à filtragem por gravidade e correlacionar as entradas do aplicativo com as entradas de registro de solicitação.

  4. Execute o método setup_logging() do cliente do Cloud Logging, que anexa o listener padrão dele como o gerenciador de geração de registros do logger raiz do Python.

Exemplo:

# 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()

Depois que o gerenciador for anexado, os registros no nível INFO ou superior que são emitidos no seu aplicativo serão enviados, por padrão, para o Logging:

# 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)

Como implantar o aplicativo

Quando estiver pronto para implantar o aplicativo, você deverá:

  1. Teste o aplicativo no App Engine.

    A única maneira de testar as atualizações e confirmar que os níveis de gravidade estão atribuídos e as entradas do aplicativo estão correlacionadas às entradas da solicitação é implantar o aplicativo no ambiente de execução do Python 3.

    Se você implantar as atualizações no ambiente de execução do Python 2, o serviço de geração de registros do App Engine detectará as entradas do logger raiz do Python e as formatará adequadamente para o Explorador de Registros.

    Se você executar o aplicativo localmente, o Cloud Logging não usará AppEngineHandler, o App Engine não poderá gravar entradas de solicitação.

  2. Visualize o Explorador de Registros e confirme se os níveis de gravidade estão atribuídos às entradas do seu aplicativo. Expanda uma entrada de solicitação e confirme se as entradas escritas pelo seu aplicativo durante o processamento da solicitação aparecem aninhadas abaixo dela.

  3. Se o aplicativo for executado sem erros, use a divisão de tráfego para aumentar gradualmente o tráfego de seu aplicativo atualizado. Monitore de perto o aplicativo em busca de problemas antes de direcionar mais tráfego para o aplicativo atualizado.