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 ficheiro suportado.

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

Escreva 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íficas da Google.

Pode integrar o appender Logback ou o java.util.logging com o Cloud Logging. Com o appender Logback, pode usar o Cloud Logging com a fachada de registo SLF4J.

Para mais informações sobre a utilização do Cloud Logging a partir de aplicações Java com o Logback appender ou o controlador java.util.logging, ou para integrar diretamente a biblioteca Cloud Logging para Java, consulte o artigo Configurar o Cloud Logging para Java.

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 fragmentos seguintes demonstram a escrita de registos estruturados.

Ative o registo JSON com o Logback e o SLF4J ativando o Logstash JSON Encoder na sua configuração logback.xml.

// Build structured log messages as an object.
Object globalLogFields = null;

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// TODO(developer): delete this code if you're creating a Cloud
//                  Function and it is *NOT* triggered by HTTP.
String traceHeader = req.headers("x-cloud-trace-context");
if (traceHeader != null && project != null) {
  String trace = traceHeader.split("/")[0];
  globalLogFields =
      kv(
          "logging.googleapis.com/trace",
          String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using key value pairs.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
logger.error(
    "This is the default display field.",
    kv("component", "arbitrary-property"),
    kv("severity", "NOTICE"),
    globalLogFields);

Personalize os nomes dos campos padrão para excluir conteúdo indesejável da ingestão no payload dos registos. Para ver uma lista dos nomes dos campos e dos formatos de dados esperados, consulte o artigo Use o agente de registo.

<configuration>
  <appender name="jsonConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
      <!-- Ignore default logging fields -->
      <fieldNames>
        <timestamp>[ignore]</timestamp>
        <version>[ignore]</version>
        <logger>[ignore]</logger>
        <thread>[ignore]</thread>
        <level>[ignore]</level>
        <levelValue>[ignore]</levelValue>
      </fieldNames>
    </encoder>
  </appender>
  <root level="INFO">
    <appender-ref ref="jsonConsoleAppender"/>
  </root>
</configuration>

No ambiente padrão do App Engine, a escrita de registos estruturados em stdout e stderr não conta para a quota de pedidos de carregamento de registos por minuto na API 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 visualizaçã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 da app, 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 que registos de apps correspondem a pedidos específicos. Pode continuar a usar outros tipos de filtragem no Explorador de registos, 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, selecione 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 da app 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 os registos não enviados são perdidos. Para evitar perder registos, use uma das seguintes opções:

    • Configure o SDK do 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 da API stdout/stderr. Esta conduta está fora da instância do App Engine e não é limitada.

O que se segue?