Migrar para o Cloud Logging

A geração de registros em ambientes de execução de segunda geração é diferente dos ambientes de primeira geração. Uma das maiores mudanças ao fazer upgrade para ambientes de execução mais recentes é que a geração de registros pré-integrado com o App Engine não é compatível com ambientes de execução de segunda geração, e os registros não são correlacionados automaticamente. Se você estiver migrando para ambientes de execução de segunda geração, use a biblioteca de cliente do Cloud Logging.

Neste guia, descrevemos como atualizar seu app para usar o Cloud Logging e conseguir quase os mesmos recursos de filtragem e correlação de registros que estavam disponíveis com a integração da geração de registros no App Engine.

O Cloud Logging é um sistema de gerenciamento de registros em tempo real com suporte para armazenamento, pesquisa, análise e monitoramento. O Cloud Logging coleta registros dos recursos do Google Cloud automaticamente. Também é possível coletar registros dos aplicativos, recursos no local e recursos de outros provedores de nuvem.

Principais diferenças

A tabela a seguir aborda as diferenças na geração de registros entre os ambientes de execução de primeira e segunda geração:

	Ambientes de execução de primeira geração	Ambientes de execução de segunda geração
Registros de solicitações e apps (também chamados de registros de aplicativos)	O App Engine incorpora todos os registros de apps no registro de solicitação. A geração de registros nos ambientes de execução de primeira geração usa o campo protoPayload.line.logMessage do registro de solicitação para incorporar registros de aplicativos.	O App Engine não incorpora registros de aplicativos ao registro de solicitações associado. O App Engine omite o atributo protoPayload.line no registro da solicitação. Os registros de apps são roteados com base no seu método de geração de registros: stdout e stderr: encaminha registros como print() para logs/stdout ou logs/stderr. Módulo de geração de registros do Python após a configuração do cliente do Cloud Logging: encaminha todos os registros gravados pelo módulo de geração de registros raiz do Python, como logging.info() e logging.error(). para logs/python. Se a biblioteca de cliente do Cloud Logging para Python não estiver configurada para correlação, o módulo de registro raiz do Python será roteado para logs/stderr por padrão.
Como ver registros na Análise de registros	Os ambientes de execução de primeira geração contêm apenas um tipo de registro, appengine.googleapis.com/request_log. Ao expandir um registro de solicitação, é possível ver os registros de aplicativos aninhados abaixo dele.	Os ambientes de execução de segunda geração incluem registros de vários tipos, como registros de solicitação emappengine.googleapis.com/request_log .stdout , stderr .logs/python E muito mais, dependendo de como o app emite registros. Os registros internos do Google também estão disponíveis em /var/log/google_init.log. Como os registros de aplicativos não são correlacionados automaticamente com os de solicitações, são necessárias outras etapas para exibir a visualização aninhada dos registros de solicitação e de aplicativos na Análise de registros. Para mais informações, acesse Relacionar registros de solicitações a registros de apps e Ver registros correlacionados na Análise de registros.
Integração do Cloud Trace	Integração automática com o Cloud Trace para coleta de dados de latência.	Integre manualmente seu aplicativo ao Cloud Trace para coletar dados de latência do App Engine. Para mais informações, consulte Instrumentar para o Cloud Trace.
Correlação do nível de erro	Registra o erro gerado nos registros de solicitação do App Engine com o nível de gravidade ERROR. O Error Reporting correlaciona esses detalhes automaticamente no painel do Error Reporting.	Por padrão, o App Engine não integra o Error Reporting aos ambientes de execução de segunda geração. Para configurar a integração da geração de registros com o Error Reporting, consulte Instrumentar os apps usando bibliotecas de cliente .
Nível de gravidade	A Análise de registros atribui um nível de gravidade aos registros de solicitação, e o nível de gravidade reflete a mais alta gravidade de qualquer entrada de registro de app correlacionada à entrada de registro da 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.	Por padrão, todos os registros de solicitação têm gravidade DEFAULT ou INFO. Mesmo que os registros de solicitações estejam correlacionados a registros de aplicativos e a Análise de registros esteja configurada para visualizar registros correlacionados, os registros de solicitação não refletem a gravidade dos registros de aplicativos associados.
API Logservice	A API Logservice faz parte do SDK de serviços incluídos.	A API Logservice foi removida do SDK do Bundled Services. Para mais informações, consulte a lista de APIs disponíveis.

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.

   Caso seu app use umconta de serviço diferente Ou, se você tiver alterado as permissões da conta de serviço padrão, verifique se a conta usada tem o logging.logEntries.create permissão para gravar registros.

3. Conheça os diferentes tipos de registros no App Engine.

Visão geral do processo de migração

Para migrar seu app para usar o Cloud Logging:

1. Instalar as bibliotecas de cliente do Cloud para o Cloud Logging
2. Gravar registros com o Cloud Logging
3. Relacionar registros de solicitação a registros de apps
4. Ver registros
5. Testar seu aplicativo

Como instalar as bibliotecas de cliente do Cloud para o Cloud Logging

Para instalar e atualizar seus arquivos de configuração, adicione as bibliotecas de cliente do Cloud para o Cloud Logging à sua lista de dependências no arquivo requirements.txt, como a seguir:

google-cloud-logging

Gravar registros com o módulo padrão 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. 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.

Por 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, todos os registros no nível INFO ou superior emitidos no seu aplicativo serão enviados para o Logging por padrão:

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

Correlacionar registros de solicitação com registros de apps

Alguns recursos disponíveis nos ambientes de execução de primeira geração, como a correlação automática de registros de solicitação com registros de apps, não estão disponíveis nos ambientes de execução de segunda geração.

Os aplicativos que usam ambientes de execução de segunda geração podem alcançar um comportamento de geração de registros aninhado semelhante ao dos ambientes de execução de primeira geração ao:

• Configurar o cliente do Cloud Logging no aplicativo e registros correlacionados.
• Como usar um identificador trace com stdout e stderr.

O comportamento de geração de registros em ambientes de execução de primeira e segunda geração é diferente das seguintes maneiras:

• Em ambientes de execução de primeira geração, o App Engine incorpora todos os registros de aplicativos emitidos durante o processamento de uma solicitação no campo protoPayload.line.logMessage do registro de solicitação. Esses registros ficam visíveis na Análise de registros usando appengine.googleapis.com/request_log.

  A imagem a seguir mostra registros correlacionados de solicitações e aplicativos nos ambientes de execução de primeira geração:

  

• Em ambientes de execução de segunda geração, o App Engine omite o atributo protoPayload.line no registro da solicitação. O conteúdo dos registros de aplicativos não está presente nos registros de solicitação JSON na Análise de registros. Cada registro de aplicativo aparecerá separadamente pelo nome na Análise de registros.

  A imagem a seguir mostra registros separados de solicitações e aplicativos nos ambientes de execução de segunda geração:

  

As seções a seguir abordam como usar o cliente do Cloud Logging ou a geração de registros estruturada com stdout e stderr para correlacionar registros.

Usar o módulo de geração de registros do Python

Para adicionar a correlação de solicitação aos registros de aplicativos registrados pelo módulo de geração de registros do Python, configure a biblioteca de cliente do Cloud Logging.

Quando vocêexecuteclient.setup_logging() método na inicialização do aplicativo, esse método adiciona o trace e os detalhes da solicitação HTTP para registros de aplicativos gravados pelo Pythonlogging como logging.info() e logging.error(). Esses registros são roteados para logs/python.

O App Engine também adiciona esse campo trace ao registro de solicitações associado, o que possibilita visualizar entradas de registro correlacionadas na Análise de registros.

Usar stdout e stderr

Se você usar stdout e stderr para gravar entradas de registro, elas aparecerão na Análise de registros. No entanto, para ativar a filtragem e a correlação com os registros de solicitação, é preciso formatar as entradas como um objeto JSON e fornecer metadados específicos. Para mais informações sobre essa abordagem, consulte Gravar registros estruturados em stdout e stderr. Essa abordagem adiciona o identificador de rastreamento da solicitação aos registros do aplicativo da seguinte forma:

1. Extraia o identificador de trace do cabeçalho da solicitação X-Cloud-Trace-Context.
2. Gravar o ID em um campo chamado logging.googleapis.com/trace na entrada de registro estruturada. Saiba mais sobre o cabeçalho X-Cloud-Trace-Context em Como forçar uma solicitação a ser rastreada.

Ver registros

É possível consultar e solicitar registros de apps de várias maneiras:

• Use a Análise de registros do Cloud Logging no console do Google Cloud.
• Usar a Google Cloud CLI para visualizar registros com a gcloud.
• Ler registros de maneira programática usando vários métodos.

Usar a Análise de registros

É possível visualizar o aplicativo e solicitar registros usando o Explorador de registros:

1. Acesse o Explorador de registros no console do Google Cloud:

   Acessar o Explorador de registros

2. Selecione um projeto atual do Google Cloud na parte superior da página.

3. Em Tipo de recurso, selecione Aplicativo GAE.

Você pode filtrar o Explorador de registros por serviço e versão do App Engine e outros critérios. Também é possível pesquisar entradas específicas nos registros. Consulte Como usar o Explorador de registros para ver mais detalhes.

Se você enviar entradas de texto simples para a saída padrão, não será possível usar o Visualizador de registros para filtrar entradas de aplicativos por gravidade, nem ver quais registros de aplicativos correspondem a solicitações específicas. É possível continuar usando outros tipos de filtragem no Explorador de registros, como texto e carimbo de data/hora.

Conferir entradas de registro correlacionadas na Análise de registros

Na Análise de registros, para visualizar as entradas de registro filhas correlacionadas a uma entrada de registro pai, expanda a entrada de registro.

Por exemplo, para exibir a entrada de registro de solicitação do App Engine e as entradas de registro do aplicativo, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Logging e clique em Análise de registros:

   Acessar o Explorador de registros

2. Em Tipo de recurso, selecione Aplicativo GAE.

3. Para visualizar e correlacionar registros de solicitações, em Nome do registro, selecione request_log. Como alternativa, para correlacionar por registros de solicitação, clique em Correlacionar por e selecione request_log.

   

4. No painel Resultados da consulta, clique em Expandir para expandir uma entrada de registro. Na expansão, cada registro de solicitação mostrará os registros de aplicativos associados.

Depois de criar um filtro para os registros, cada registro de solicitação mostra registros de app correspondentes como registros filhos. Para isso, a Análise de registros correlaciona o campo trace nos registros de aplicativos e um determinado registro de solicitação, supondo que o aplicativo use a biblioteca google-cloud-logging.

A imagem a seguir mostra os registros de aplicativos agrupados pelo campo trace:

Use a Google Cloud CLI

Para ver os registros do App Engine na linha de comando, use o seguinte comando:

gcloud app logs tail

Saiba mais em gcloud app logs tail.

Como ler registros de maneira programática

Se você quiser ler os registros de maneira programática, use um destes métodos:

• Use um coletor de registros para o Pub/Sub e um script para extrair do Pub/Sub.
• Chame a API Cloud Logging por meio da biblioteca de cliente para sua linguagem de programação.
• Chame os endpoints da API REST do Cloud Logging diretamente.

Teste seu app

A migração será bem-sucedida se você conseguir implantar o app sem erros. Para verificar se o Cloud Logging está funcionando, siga estas etapas:

1. Acesse a Análise de registros e expanda uma entrada do registro de solicitação.

   Acessar o Explorador de registros

2. Garanta que os registros de aplicativos gerados pelo aplicativo ao processar uma solicitação estejam aninhados no registro de solicitações.

3. Se todos os endpoints do app funcionarem conforme esperado, use a divisão de tráfego para aumentar lentamente o tráfego do app atualizado. Monitore de perto o aplicativo em busca de problemas antes de rotear mais tráfego para o aplicativo atualizado.