Gravar e consultar registros

Nesta página, descrevemos os registros disponíveis para aplicativos do App Engine e como gravar, correlacionar e visualizar entradas de registro.

O App Engine coleta três tipos de registro:

  • Registro de solicitações: registros das solicitações enviadas ao aplicativo. Por padrão, o App Engine emite automaticamente uma entrada de registro para cada solicitação HTTP recebida por um app.

  • Registro do aplicativo: entradas de registro emitidas por um aplicativo do App Engine com base nas entradas de registro gravadas em um framework ou arquivo compatível.

  • Registro do sistema: registros gerados pela plataforma que contêm informações sobre o app. Esses registros são gravados em varlog/system.

O App Engine envia automaticamente os registros de solicitação e de aplicativos para o agente do Cloud Logging.

Gravar registros de apps

O App Engine emite registros automaticamente para solicitações enviadas ao aplicativo. Portanto, não é necessário gravar registros de solicitação. Esta seção aborda como gravar registros de apps.

Quando você grava registros de aplicativos no aplicativo do App Engine, eles são coletados automaticamente pelo Cloud Logging, desde que sejam gravados usando os seguintes métodos:

Integrar com o Cloud Logging

Você pode integrar o aplicativo do App Engine ao Cloud Logging. Essa abordagem permite usar todos os recursos oferecidos pelo Cloud Logging e requer apenas algumas linhas de código específico do Google.

Gravar registros estruturados em stdout e stderr

Por padrão, o App Engine usa a biblioteca de cliente do Cloud Logging para enviar registros. No entanto, esse método não oferece suporte à geração de registros estruturados. Só é possível gravar registros estruturados usando stdout/stderr. Além disso, você também pode enviar strings de texto para stdout e stderr. Por padrão, o payload do registro é uma string de texto armazenada no campo textPayload da entrada de registro. As strings aparecerão como mensagens no Explorador de registros, na linha de comando e na API Cloud Logging e serão associadas ao serviço e à versão do App Engine que as emitiu.

Para extrair mais valor dos registros, filtre essas strings na Análise de registros por nível de gravidade. Para filtrar essas strings, é necessário formatá-las como dados estruturados. Para isso, grave os registros em uma única linha de JSON serializado. O App Engine seleciona e analisa essa linha JSON serializada e a coloca no campo jsonPayload da entrada de registro em vez de textPayload.

No ambiente padrão do App Engine, gravar registros estruturados em stdout e stderr não é contabilizado na cota de solicitações de ingestão por minuto da API Cloud Logging.

Campos JSON especiais nas mensagens

Quando você fornece um registro estruturado como um dicionário JSON, alguns campos especiais são retirados do jsonPayload e gravados no campo correspondente no LogEntry gerado, conforme descrito na documentação sobre campos especiais.

Por exemplo, se o JSON incluir uma propriedade severity, ela será removida do jsonPayload e aparecerá como severity da entrada de registro. A propriedade message é usada como o texto de exibição principal da entrada de registro, se houver.

Correlacionar registros de solicitação com registros de apps

Depois de formatar as entradas como um objeto JSON e fornecer metadados específicos, será possível ativar a filtragem e a correlação com os registros de solicitação. Para correlacionar as entradas de registro de solicitação com as entradas de registro do aplicativo, você precisa do identificador de trace da solicitação. Siga as instruções para correlacionar mensagens de registro:

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

Para conferir registros correlacionados, consulte Ver entradas de registro correlacionadas na Análise de registros.

Ver registros

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

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.

    Como correlacionar registros

  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:

As entradas de registro de apps são aninhadas na entrada de registro de solicitações.

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:

Entender os registros de escalonamento de instância

Quando novas instâncias são iniciadas para seu app, o Cloud Logging inclui entradas de registro no nome de registro varlog/system para refletir por que cada instância foi criada. A entrada de registro segue este formato:

Starting new instance. Reason: REASON - DESCRIPTION

A tabela a seguir mostra um detalhamento das descrições de instâncias:

Motivo Descrição
CUSTOMER_MIN_INSTANCE Instância mínima configurada pelo cliente para o app.
SCHEDULED A instância foi iniciada devido a fatores de escalonamento configurados (por exemplo, utilização da CPU, taxa de transferência de solicitações etc.) e aos respectivos destinos.
OVERFLOW A instância foi iniciada porque não foi encontrada capacidade para o tráfego atual.

Política de retenção de registros, preços e cotas

Saiba mais sobre os preços aplicáveis aos registros de solicitações e de aplicativos em preços do Cloud Logging.

Veja a política de retenção de registros e o tamanho máximo das entradas de registro em Cotas e limites. É possível exportar os registros para o Cloud Storage se você quiser armazená-los por mais tempo. Além disso, é possível exportá-los para o BigQuery e Pub/Sub se quiser processamento adicional.

Como gerenciar o uso de recursos de registro

É possível controlar a quantidade de atividade de geração de registros no aplicativo escrevendo mais ou menos entradas no código do aplicativo. Os registros de solicitação são criados automaticamente. Portanto, para gerenciar o número de entradas de registro de solicitação associadas ao aplicativo, use o recurso de exclusão de registros do Cloud Logging.

Problemas conhecidos

Confira a seguir alguns problemas de geração de registros nos ambientes de execução de segunda geração:

  • Às vezes, as entradas de registro do aplicativo não estão relacionadas ao registro de solicitação. Isso acontece na primeira vez que o aplicativo recebe uma solicitação e qualquer outra vez que o App Engine grava mensagens de status no registro do aplicativo. Saiba mais em https://issuetracker.google.com/issues/138365527.

  • Quando você encaminha registros do coletor de registros para o Cloud Storage, o destino do Cloud Storage contém apenas registros de solicitação. O App Engine grava os registros de aplicativos em pastas diferentes.

  • O BigQuery não consegue ingerir registros devido ao campo @type nos registros de solicitação. Isso interrompe a detecção automática do esquema, já que o BigQuery não permite @type em nomes de campo. Para resolver isso, você precisa definir manualmente o esquema e remover o campo @type dos registros de solicitação.

  • Se você usa as APIs REST de geração de registros, uma linha de execução em segundo plano grava os registros no Cloud Logging. Se a linha de execução principal não estiver ativa, a instância não receberá tempo de CPU, o que fará com que a linha de execução em segundo plano seja interrompida. O tempo de processamento de registros é atrasado. Em algum momento, a instância é removida e todos os registros não enviados são perdidos. Para evitar a perda de registros, use uma das seguintes opções:

    • Configure o SDK do Cloud Logging para usar o gRPC. Com o gRPC, os registros são enviados ao Cloud Logging imediatamente. No entanto, isso pode aumentar os limites de CPU necessários.
    • Envie mensagens de registro para o Cloud Logging usando stdout/stderr. Esse pipeline está fora da instância do App Engine e não é limitado.

A seguir

  • Consulte Monitorar e alertar latência para saber como usar o Cloud Logging para visualizar registros de depuração de erros e como usar o Cloud Trace para entender a latência do app.