Escreva e veja registos

Esta página descreve os registos disponíveis para as apps do App Engine e como escrever, correlacionar e ver entradas de registo.

O App Engine recolhe dois tipos de registos:

  • Registo de pedidos: registos de pedidos enviados para a sua app. Por predefinição, o App Engine emite automaticamente uma entrada de registo para cada pedido HTTP que uma app recebe.

  • Registo da app: entradas de registo emitidas por uma app do App Engine com base nas entradas de registo que escreve num framework ou num ficheiro suportado.

O App Engine envia automaticamente os registos de pedidos e os registos de apps para o agente do Cloud Logging.

Escrever registos de apps

O App Engine emite automaticamente registos para pedidos enviados para a sua app, pelo que não é necessário escrever registos de pedidos. Esta secção aborda como escrever registos de apps.

Quando escreve registos de apps a partir da sua app do App Engine, os registos são recolhidos automaticamente pelo Cloud Logging, desde que sejam escritos através dos seguintes métodos:

Faça a integração com o Cloud Logging

Pode integrar a sua app do App Engine com o Cloud Logging. Esta abordagem permite-lhe usar todas as funcionalidades oferecidas pelo Cloud Logging e requer apenas algumas linhas de código específico da Google.

Escreva registos estruturados em stdout e stderr

Por predefinição, o App Engine usa a biblioteca cliente do Cloud Logging para enviar registos. No entanto, este método não suporta o registo estruturado. Só pode escrever registos estruturados através da função stdout/stderr. Além disso, também pode enviar strings de texto para stdout e stderr. Por predefinição, a carga útil do registo é uma string de texto armazenada no campo textPayload da entrada do registo. As strings aparecem como mensagens no Explorador de registos, na linha de comandos e na API Cloud Logging, e estão associadas ao serviço e à versão do App Engine que as emitiu.

Para obter mais valor dos registos, pode filtrar estas strings no Explorador de registos por nível de gravidade. Para filtrar estas strings, tem de formatá-las como dados estruturados. Para o fazer, escreve registos sob a forma de uma única linha de JSON serializado. O App Engine recolhe e analisa esta linha JSON serializada e coloca-a no campo jsonPayload da entrada do registo em vez de textPayload.

Os registos stdout e stderr do ambiente flexível são enviados para o Cloud Logging através do agente de registo antigo em execução nas instâncias de máquinas virtuais. O agente de registo é executado com recursos limitados e os registos escritos são rodados após excederem um limite de 10 MB. Se a taxa à qual os registos são escritos em stdout e stderr for superior à taxa à qual os registos são lidos pelo agente de registo, os registos podem ser rodados antes de serem enviados para o Cloud Logging. Se não quiser perder registos, use o Cloud Logging.

Campos JSON especiais em mensagens

Quando fornece um registo estruturado como um dicionário JSON, alguns campos especiais são removidos do jsonPayload e são escritos no campo correspondente no LogEntry gerado, conforme descrito na documentação para campos especiais.

Por exemplo, se o seu JSON incluir uma propriedade severity, esta é removida de jsonPayload e aparece como severity da entrada do registo. A propriedade message é usada como o texto de apresentação principal da entrada do registo, se estiver presente.

Correlacione os registos de pedidos com os registos de apps

Depois de formatar as entradas como um objeto JSON e fornecer metadados específicos, pode ativar a filtragem e a correlação com os registos de pedidos. Para correlacionar as entradas do registo de pedidos com as entradas do registo de apps, precisa do identificador de rastreio do pedido. Siga as instruções para correlacionar mensagens de registo:

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

Para ver registos correlacionados, consulte o artigo Veja entradas de registos correlacionados no Explorador de registos.

Ver registos

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

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.

    Correlacionar registos

  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:

As entradas do registo da app estão aninhadas na entrada do registo do pedido.

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:

Política de retenção de preços, quotas e registos

Para ver informações sobre os preços aplicáveis aos registos de pedidos e de apps, consulte o artigo Preços do Cloud Logging.

Para ver a política de retenção de registos e o tamanho máximo das entradas de registo, consulte o artigo Quotas e limites. Se quiser armazenar os seus registos durante um período mais longo, pode exportá-los para o Cloud Storage. Também pode exportar os seus registos para o BigQuery e o Pub/Sub para processamento adicional.

Gerir a utilização de recursos de registo

Pode controlar a quantidade de atividade de registo dos registos da sua app escrevendo mais ou menos entradas a partir do código da app. Os registos de pedidos são criados automaticamente. Por isso, para gerir o número de entradas de registos de pedidos associadas à sua app, use a funcionalidade de exclusão de registos do Cloud Logging.

Problemas conhecidos

Seguem-se alguns problemas de registo nos runtimes de segunda geração:

  • Por vezes, as entradas do registo da app não estão correlacionadas com o registo de pedidos. Isto acontece na primeira vez que a sua app recebe um pedido e em qualquer outra altura em que o App Engine escreve mensagens de estado no registo da sua app. Para mais informações, consulte https://issuetracker.google.com/issues/138365527.

  • Quando encaminha registos da entrada de registos para o Cloud Storage, o destino do Cloud Storage contém apenas registos de pedidos. O App Engine escreve os registos de apps em pastas diferentes.

  • O BigQuery não consegue carregar registos devido ao campo @type nos registos de pedidos. Isto interrompe a deteção automática de esquemas, uma vez que o BigQuery não permite @type em nomes de campos. Para resolver este problema, tem de definir manualmente o esquema e remover o campo @type dos registos de pedidos.

  • Se usar as APIs REST de registo, um processo em segundo plano escreve registos no Cloud Logging. Se a thread principal não estiver ativa, a instância não recebe tempo de CPU, o que faz com que a thread de fundo pare. O tempo de processamento dos registos está atrasado. Em algum momento, a instância é removida e todos os registos não enviados são perdidos. Para evitar perder registos, use uma das seguintes opções:

    • Configure o SDK Cloud Logging para usar o gRPC. Com o gRPC, os registos são enviados imediatamente para o Cloud Logging. No entanto, isto pode aumentar os limites da CPU necessários.
    • Envie mensagens de registo para o Cloud Logging através do stdout/stderr. Esta conduta está fora da instância do App Engine e não é limitada.

O que se segue?