Como gravar e ver registros

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

O App Engine coleta dois tipos de registro:

  • Registro de solicitações: um registro das solicitações enviadas para seu aplicativo. O App Engine cria entradas automaticamente no registro de solicitações.

  • Registro de aplicativos: as entradas de registro gravadas em um framework ou arquivo compatível, conforme descrito nesta página.

O App Engine envia esses registros automaticamente para o agente do Cloud Logging. É possível vê-los no Visualizador de registros, na linha de comando ou de maneira programática.

Como gravar registros de apps

Para gravar entradas de registro, recomendamos que você integre os plug-ins Bunyan ou Winston ao Cloud Logging. Essa abordagem ativa todos os recursos do Cloud Logging e requer apenas algumas linhas de código específico do Google Cloud.

Para instruções e amostras de código, consulte Como configurar o Cloud Logging para Node.js.

Alternativa: como gravar registros estruturados em stdout e stderr

Em vez da abordagem recomendada, é possível enviar strings de texto simples para stdout e stderr. 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.

Se você quiser filtrar essas strings no Explorador de registros por nível de gravidade, será necessário formatá-las como dados estruturados. Saiba mais em Como gerar registros estruturados.

Se quiser correlacionar entradas no registro do aplicativo com o registro de solicitação, as entradas de registro do aplicativo estruturado precisarão conter o identificador de trace da solicitação. É possível extrair o identificador de trace do cabeçalho de solicitação X-Cloud-Trace-Context. 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.

Veja um exemplo de gravação de entradas de registro estruturadas com um ID de trace na documentação do Cloud Run. É possível usar a mesma técnica nos aplicativos do App Engine.

Como ver 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:

    Acesse o Explorador de registros

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

  3. Nos menus suspensos, selecione o Aplicativo do GAE como o tipo de recurso.

  4. Para ver quais entradas de registro do aplicativo estão relacionadas a entradas de registro de solicitação:

    1. Selecione o registro httpRequest.requestUrl nos menus do filtro.

    2. Expanda uma entrada de registro de solicitação. Os registros de aplicativos relacionados a essa solicitação aparecem aninhados na entrada de registro da solicitação.

    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.

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.

Como ver registros usando a linha de comando

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:

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

À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.