Como ler e gravar registros de aplicativos

Visão geral

Quando uma solicitação é enviada para seu aplicativo, um registro de solicitação é gravado automaticamente pelo App Engine. Durante o tratamento da solicitação, seu app também pode gravar registros de aplicativos. Nesta página, você aprenderá a gravar registros do aplicativo, como visualizar registros no console do Google Cloud e como entender os dados de registro de solicitação que o App Engine grava durante a solicitação.

Para informações sobre como fazer o download de dados de registro, consulte Visão geral das exportações de registros.

Importante: lembre-se de que, por padrão, os registros não são mantidos quando você usa o servidor de aplicativos de desenvolvimento. Para informações sobre como tornar os registros permanentes, consulte O servidor de desenvolvimento e a API Logs.

Comparação entre registros de solicitação e de aplicativo

Há duas categorias de dados de registros: de solicitação e de aplicativos. Os registros de solicitação são gravados automaticamente pelo App Engine para cada solicitação processada pelo seu aplicativo e contêm informações como código do projeto, versão HTTP etc. Para ver a lista completa das propriedades disponíveis para registros de solicitação, consulte RequestLog. Consulte também a tabela de registros de solicitação para ver as descrições dos campos desses registros.

Cada registro de solicitação contém uma lista de registros de aplicativos (AppLog) associados à solicitação, retornada na propriedade RequestLog.app_logs. Cada registro de aplicativo apresenta a hora em que o registro foi gravado, a mensagem e o nível do registro.

Observação: um registro de solicitação pode conter somente 1.000 registros de aplicativos. Se você adicionar mais de 1.000, os registros mais antigos não serão mantidos.

Como gravar registros de aplicativos

Importante: as entradas individuais de registro de um aplicativo têm um limite de 16 KB. Nada além desse limite será gravado no registro do aplicativo.

Convém ler a documentação do módulo padrão de geração de registros do Python em Python.org.

O módulo de geração de registros do Python permite que um desenvolvedor registre cinco níveis de gravidade:

• Depuração
• Informações
• Aviso
• Erro
• Crítico

O exemplo a seguir mostra como usar os diferentes níveis de registro:

import logging

import webapp2


class MainPage(webapp2.RequestHandler):
    def get(self):
        logging.debug('This is a debug message')
        logging.info('This is an info message')
        logging.warning('This is a warning message')
        logging.error('This is an error message')
        logging.critical('This is a critical message')

        try:
            raise ValueError('This is a sample value error.')
        except ValueError:
            logging.exception('A example exception log.')

        self.response.out.write('Logging example.')


app = webapp2.WSGIApplication([
    ('/', MainPage)
], debug=True)

Formato do URL de registro no console do Google Cloud

Veja a seguir um exemplo do formato do URL de registro no Console do Google Cloud:

https://console.cloud.google.com/logs?filters=request_id:000000db00ff00ff827e493472570001737e73686966746361727331000168656164000100

Observação: o URL não inclui mais filter_type.

Como ler registros no Console

Observação: os registros descritos aqui são mostrados como visíveis no Visualizador de registros.

Para exibir registros gravados por aplicativos executados no ambiente padrão, use o Explorador de registros.

Um registro comum do App Engine contém dados no formato de registro combinado Apache, além de alguns campos especiais do App Engine, como mostra o registro de exemplo a seguir:

192.0.2.0 - test [27/Jun/2014:09:11:47 -0700] "GET / HTTP/1.1" 200 414
"http://www.example.com/index.html"
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36"
"1-dot-calm-sylph-602.appspot.com" ms=195 cpu_ms=42 cpm_usd=0.000046
loading_request=1 instance=00c61b117cfeb66f973d7df1b7f4ae1f064d app_engine_release=

Como entender os campos de registros de solicitação

A tabela abaixo lista os campos em ordem de ocorrência e uma descrição:

Ordem do campo	Nome do campo	Sempre presente?	Descrição
1	Endereço do cliente	Sim	Endereço IP do cliente. Exemplo: 192.0.2.0
2	Identidade RFC 1413	Não	Identidade RFC 1413 do cliente. Quase sempre é o caractere -.
3	Usuário	Não	Presente somente se o aplicativo usar a API Users e o usuário tiver feito login. Esse valor é a parte "apelido" da Conta do Google, por exemplo, se a Conta do Google for [e-mail], o apelido registrado nesse campo será test.
4	Carimbo de data/hora	Sim	Carimbo de data/hora da solicitação. Exemplo: [27/Jun/2014:09:11:47 -0700]
5	String de consulta de solicitação	Sim	Primeira linha da solicitação, contendo método, caminho e versão HTTP. Exemplo: GET / HTTP/1.1
6	Código de status HTTP	Sim	Código de status de HTTP retornado. Exemplo: 200
7	Tamanho da resposta	Sim	Tamanho da resposta em bytes. Exemplo: 414
8	Caminho de indicação	Não	Se não houver indicação, o registro não terá caminho, somente -. Caminho do referenciador de exemplo: "http://www.example.com/index.html".
9	User-agent	Sim	Identifica o navegador e o sistema operacional para o servidor da Web. Exemplo: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36
10	Nome do host	Sim	O nome do host usado pelo cliente para conectar-se ao aplicativo App Engine. Exemplo : (1-dot-calm-sylph-602.appspot.com)
11	Tempo	Sim	Tempo total em milissegundos gasto pelo App Engine na solicitação. Esta duração não inclui o tempo gasto entre o cliente e o servidor que executa a instância do seu aplicativo. Exemplo: ms=195.
12	Milissegundos de CPU	Sim	Milissegundos de CPU necessários para cumprir a solicitação. Esta é a quantidade de milissegundos gasta pela CPU que de fato executa o código do seu aplicativo, usando como valor de referência um Intel x86 de 1,2 GHz. Se a CPU realmente utilizada for mais rápida do que o valor de referência, poderá haver mais milissegundos do que o tempo real definido acima. Exemplo: cpu_ms=42
13	Código de saída	Não	Presente somente se a instância for desligada depois de receber a solicitação. No formato exit_code=XXX, em que XXX é um número de três dígitos correspondente ao motivo pelo qual a instância foi desligada. Os códigos de saída não são documentados, já que se destinam a ajudar o Google a detectar e corrigir problemas.
14	Custo estimado	Sim	OBSOLETO. Custo estimado de 1.000 solicitações como esta, em dólares americanos. Exemplo: cpm_usd=0.000046
15	Nome da fila	Não	O nome da fila de tarefas usada. Presente apenas se o pedido usar uma fila de tarefas. Exemplo: queue_name=default
16	Nome da tarefa	Não	O nome da tarefa executada na fila de tarefas desta solicitação. Presente somente se a solicitação resultou na fila de uma tarefa. Exemplo: task_name=7287390692361099748
17	Fila pendente	Não	Presente somente se uma solicitação demorar algum tempo em uma fila pendente. Se tiver vários desses nos seus registros ou se os valores forem altos, pode ser uma indicação de que você precisa de mais instâncias para atender seu tráfego. Exemplo: pending_ms=195
18	Solicitação de carregamento	Não	Presente somente se a solicitação for de carregamento. Isso significa que uma instância precisou ser iniciada. De preferência, suas instâncias devem estar ativas e íntegras durante o máximo de tempo possível, atendendo a um grande número de solicitações antes de serem recicladas e precisarem ser iniciadas outra vez. Isso significa que você não deve ver muitos desses nos seus registros. Exemplo: loading_request=1.
19	Instância	Sim	Identificador exclusivo da instância que gerencia a solicitação. Exemplo: instance=00c61b117cfeb66f973d7df1b7f4ae1f064d
20	Versão	Sim	A versão de lançamento atual do App Engine usada no App Engine de produção:

Cotas e limites

Seu aplicativo é afetado pelas cotas relacionadas a registros abaixo:

• Dados de registros recuperados pela API Logs.
• Cota e retenção de ingestão de registros.

Cota para dados recuperados

Os primeiros 100 megabytes de dados de registros recuperados pelas chamadas da API Logs ao dia são gratuitos. Dados com mais de 100 megabytes resultam em cobranças de US$ 0,12/GB.

Cota de ingestão de registros

A geração de registros para aplicativos do App Engine é fornecida pela Observabilidade do Google Cloud. Consulte os Preços de observabilidade do Google Cloud para mais informações sobre custos e limites de geração de registros. Para armazenamento de longo prazo, é possível exportar registros da observabilidade do Google Cloud para o Cloud Storage, o BigQuery e o Pub/Sub.

O servidor de desenvolvimento e a API Logs

Importante:

• Antes de executar o servidor de desenvolvimento local, siga as instruções de configuração. Independentemente da versão do ambiente de execução ou da linguagem do aplicativo, é necessário executar dev_appserver.py com o Python 3 e definir a variável de ambiente CLOUDSDK_DEVAPPSERVER_PYTHON no shell como o caminho do interpretador do Python 2.
• A ferramenta dev_appserver não é compatível com o desenvolvimento de aplicativos Python 3 no Windows.

Por padrão, os registros são armazenados na memória apenas no servidor de desenvolvimento e são acessíveis se você quiser testar o recurso da API Logs. Se quiser manter os registros do servidor de desenvolvimento no disco em um local de sua escolha, forneça o caminho e o nome de arquivo pretendidos à opção de linha de comando --logs_path da seguinte maneira:

   python2 [DEVAPPSERVER_ROOT]/google_appengine/dev_appserver.py --logs_path=your-path/your-logfile-name your-app-directory