Migre para o Cloud Logging

O registo de runtimes de segunda geração é diferente do registo de runtimes de primeira geração. Uma das maiores alterações quando atualiza para runtimes mais recentes é que o registo pré-integrado com o App Engine não é suportado em runtimes de segunda geração, e os registos não são correlacionados automaticamente. Se estiver a migrar para os runtimes de segunda geração, tem de usar a biblioteca de cliente do Cloud Logging.

Este guia descreve como pode atualizar a sua app para usar o Cloud Logging e alcançar quase as mesmas funcionalidades de filtragem e correlação de registos que estavam disponíveis com a integração de registos no App Engine.

O Cloud Logging é um sistema de gestão de registos em tempo real com suporte de armazenamento, pesquisa, análise e monitorização. O Cloud Logging recolhe automaticamente registos de Google Cloud recursos. Também pode recolher registos das suas aplicações, recursos no local e recursos de outros fornecedores de nuvem.

Principais diferenças

A tabela seguinte abrange as diferenças no registo entre os runtimes de primeira e segunda geração:

	Tempos de execução de primeira geração	Tempos de execução de segunda geração
Registos de pedidos e apps (também denominados registos de aplicações)	O App Engine incorpora todos os registos de apps no registo de pedidos. O início de sessão nos tempos de execução de primeira geração usa o campo protoPayload.line.logMessage do registo de pedidos para incorporar registos da app.	O App Engine não incorpora registos de apps no registo de pedidos associado. O App Engine omite o atributo protoPayload.line no registo de pedidos. Os registos de apps são encaminhados com base no seu método de registo: stdout e stderr: registos de rotas, como print() para logs/stdout ou logs/stderr. O módulo de registo Python após a configuração do cliente do Cloud Logging: encaminha todos os registos escritos pelo módulo de registo raiz do Python, como logging.info() e logging.error(), para logs/python. Se a biblioteca cliente do Cloud Logging para Python não estiver configurada para correlação, o módulo de registo raiz do Python é encaminhado para logs/stderr por predefinição.
Ver registos no Explorador de registos	Os tempos de execução de primeira geração só contêm um tipo de registo, appengine.googleapis.com/request_log. Quando expande um registo de pedidos, pode ver os registos de apps aninhados abaixo.	Os tempos de execução de segunda geração incluem registos de vários tipos de registos, como: registos de pedidos em appengine.googleapis.com/request_log, stdout, stderr, logs/python e muitos mais, consoante a forma como a sua app emite registos. Os registos internos da Google também estão disponíveis em /var/log/google_init.log. Uma vez que os registos de apps não são correlacionados automaticamente com os registos de pedidos, são necessários passos adicionais para apresentar a vista aninhada dos registos de pedidos e de apps no Explorador de registos. Para mais informações, consulte os artigos Correlacione registos de pedidos com registos de apps e Veja registos correlacionados no Explorador de registos.
Integração do Cloud Trace	Integrado automaticamente com o Cloud Trace para a recolha de dados de latência.	Tem de integrar manualmente a sua app com o Cloud Trace para recolher dados de latência do App Engine. Para mais informações, consulte o artigo Instrumente para o Cloud Trace.
Correlação do nível de erro	Regista o erro gerado nos registos de pedidos do App Engine com um nível de gravidade ERROR. O Error Reporting correlaciona automaticamente estes detalhes no painel de controlo do Error Reporting.	Por predefinição, o App Engine não integra o Error Reporting nos runtimes de segunda geração. Para configurar a integração do registo com o Relatório de erros, consulte o artigo Instrumente apps através de bibliotecas de cliente .
Nível de gravidade	O Explorador de registos atribui um nível de gravidade aos registos de pedidos e o nível de gravidade reflete a gravidade mais elevada de qualquer entrada de registo da app que esteja correlacionada com a entrada de registo de pedidos. Por exemplo, se um pedido resultar na emissão de uma entrada de registo de aviso pela sua app, o Explorador de registos apresenta um ícone de aviso junto à entrada de registo do pedido. Quando expande a entrada do pedido, vê a entrada do registo de aviso aninhada na entrada do pedido.	Por predefinição, todos os registos de pedidos têm uma gravidade de DEFAULT ou INFO. Mesmo que os registos de pedidos estejam correlacionados com os registos da app e o Explorador de registos esteja configurado para ver registos correlacionados, os registos de pedidos não refletem a gravidade dos registos da app associados.
API Logservice	A API Logservice faz parte do SDK de serviços incluídos.	A API Logservice foi removida do SDK de serviços incluídos. Para mais informações, consulte a lista de APIs disponíveis.

Antes de começar a migrar

1. Ative a API Cloud Logging no projeto que contém a sua app.

   Ative a API

2. Certifique-se de que a sua app tem autorização para escrever registos.

   Por predefinição, a conta de serviço predefinida da sua app tem autorização para escrever registos.

   Se a sua app usar uma conta de serviço diferente, ou se tiver alterado as autorizações da conta de serviço predefinida, certifique-se de que a conta que usa tem a autorização logging.logEntries.create para escrever registos.

3. Familiarize-se com os diferentes tipos de registos no App Engine.

Vista geral do processo de migração

Para migrar a sua app para usar o Cloud Logging:

1. Instale as bibliotecas cliente do Google Cloud para o Cloud Logging
2. Escreva registos com o Cloud Logging
3. Correlacione os registos de pedidos com os registos da app
4. Ver registos
5. Teste a sua app

Instalar as bibliotecas de cliente do Google Cloud para o Cloud Logging

Para instalar e atualizar os ficheiros de configuração, adicione as bibliotecas de cliente da nuvem para o Cloud Logging à sua lista de dependências no ficheiro requirements.txt, da seguinte forma:

google-cloud-logging

Escreva registos com o módulo de registo padrão do Python

Em cada ficheiro que escreve entradas de registo:

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 respetivo ouvinte predefinido como o controlador de registo para o registador de 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 de o controlador ser anexado, todos os registos ao nível INFO ou superior emitidos na sua aplicação são enviados para o registo por predefiniçã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)

Correlacione os registos de pedidos com os registos de apps

Algumas funcionalidades disponíveis nos runtimes de primeira geração, como a correlação automática dos registos de pedidos com os registos da app, não estão disponíveis nos runtimes de segunda geração.

As apps que usam runtimes de segunda geração podem alcançar um comportamento de registo aninhado semelhante ao dos runtimes de primeira geração através de uma das seguintes opções:

• Configurar o cliente do Cloud Logging na sua aplicação e correlacionar registos.
• Usar um identificador trace com stdout e stderr.

O comportamento de registo nos runtimes de primeira geração e de segunda geração difere das seguintes formas:

• Nos tempos de execução de primeira geração, o App Engine incorpora todos os registos de apps emitidos durante o processamento de um pedido no campo protoPayload.line.logMessage do registo de pedidos. Estes registos estão visíveis no Explorador de registos através de appengine.googleapis.com/request_log.

  A imagem seguinte mostra os registos de pedidos e de apps correlacionados nos runtimes de primeira geração:

  

• Nos runtimes de segunda geração, o App Engine omite o atributo protoPayload.line no registo de pedidos. O conteúdo dos registos da app não está presente nos registos de pedidos JSON no Explorador de registos. Cada registo da app aparece separadamente pelo respetivo nome de registo no Explorador de registos.

  A imagem seguinte mostra registos de pedidos e de apps separados nos runtimes de segunda geração:

  

As secções seguintes abordam como usar o cliente do Cloud Logging ou o registo estruturado com stdout e stderr para correlacionar registos.

Use o módulo de registo do Python

Para adicionar a correlação de pedidos aos registos de apps registados pelo módulo de registo Python, configure a biblioteca cliente do Cloud Logging.

Quando executa o método client.setup_logging() no arranque da aplicação, este método adiciona o campo trace e os detalhes do pedido HTTP aos registos da app escritos pelo módulo logging do Python, como logging.info() e logging.error(). Estes registos são encaminhados para logs/python.

O App Engine também adiciona este campo trace ao registo de pedidos associado, o que permite ver entradas de registo correlacionadas no Explorador de registos.

Use stdout e stderr

Se usar stdout e stderr para escrever entradas de registo, estas entradas aparecem no Explorador de registos. No entanto, para ativar a filtragem e a correlação com os registos de pedidos, tem de formatar as entradas como um objeto JSON e fornecer metadados específicos. Para mais informações sobre esta abordagem, consulte o artigo Escreva registos estruturados para stdout e stderr. Esta abordagem adiciona o identificador de rastreio do pedido nos registos da aplicação através do seguinte:

1. Extraindo o identificador de rastreio do cabeçalho do pedido X-Cloud-Trace-Context.
2. Escrever o ID num campo denominado logging.googleapis.com/trace na entrada do registo estruturado. Para mais informações sobre o cabeçalho X-Cloud-Trace-Context, consulte o artigo Forçar o rastreio de um pedido.

Ver registos

Pode ver os registos de apps e os registos de pedidos de várias formas:

• Use o Explorador de registos do Cloud Logging na Google Cloud consola.
• Use a CLI gcloud para ver registos através do gcloud.
• Leia registos de forma programática através de vários métodos.

Use o Explorador de registos

Pode ver os registos da sua app e de pedidos através do Explorador de registos:

1. Aceda ao Explorador de registos na Google Cloud consola:

   Aceda ao Explorador de registos

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

3. Em Tipo de recurso, selecione Aplicação GAE.

Pode filtrar o Explorador de registos por serviço, versão e outros critérios do App Engine. Também pode pesquisar entradas específicas nos registos. Consulte o artigo Usar o Explorador de registos para ver detalhes.

Se enviar entradas de texto simples para a saída padrão, não pode usar o visualizador de registos para filtrar entradas de apps por gravidade, nem ver a que pedidos específicos correspondem os registos de apps. Pode continuar a usar outros tipos de filtragem no Logs Explorer, como texto e data/hora.

Veja entradas de registo correlacionadas no Explorador de registos

No Explorador de registos, para ver as entradas de registo secundárias correlacionadas com uma entrada de registo principal, expanda a entrada de registo.

Por exemplo, para apresentar a entrada do registo de pedidos do App Engine e as entradas do registo de aplicações, faça o seguinte:

1. No painel de navegação da Google Cloud consola, selecione Registo e, de seguida, Explorador de registos:

   Aceda ao Explorador de registos

2. Em Tipo de recurso, selecione Aplicação GAE.

3. Para ver e correlacionar registos de pedidos, em Nome do registo, selecione request_log. Em alternativa, para estabelecer a correlação por registos de pedidos, clique em Estabelecer correlação por e selecione request_log.

   

4. No painel Resultados da consulta, para expandir uma entrada do registo, clique em Expandir. Quando expandido, cada registo de pedidos mostra os registos da app associados.

Depois de criar um filtro para os registos, cada registo de pedidos mostra os registos de apps correspondentes como registos secundários. O Logs Explorer consegue isto correlacionando o campo trace nos registos da app e um determinado registo de pedido, partindo do princípio de que a aplicação usa a biblioteca google-cloud-logging.

A imagem seguinte mostra os registos de apps agrupados pelo campo trace:

Use a Google Cloud CLI

Para ver os registos do App Engine a partir da linha de comandos, use o seguinte comando:

gcloud app logs tail

Para mais informações, consulte gcloud app logs tail.

Ler registos de forma programática

Se quiser ler os registos de forma programática, pode usar um destes métodos:

• Use um destinatário de registos para o Pub/Sub e um script para extrair do Pub/Sub.
• Chame a API Cloud Logging através da biblioteca cliente para a sua linguagem de programação.
• Chamar os endpoints REST da Cloud Logging API diretamente.

Teste a sua app

A migração é bem-sucedida se conseguir implementar a sua app sem erros. Para verificar se o Cloud Logging está a funcionar, siga estes passos:

1. Aceda ao Explorador de registos e expanda uma entrada do registo de pedidos.

   Aceda ao Explorador de registos

2. Certifique-se de que os registos da app gerados pela sua app quando processa um pedido, estão aninhados no registo de pedidos.

3. Se todos os seus pontos finais da app funcionarem como esperado, use a divisão de tráfego para aumentar gradualmente o tráfego para a app atualizada. Monitorize atentamente a app para detetar problemas antes de encaminhar mais tráfego para a app atualizada.