Gravar e ver registros

O Logging é uma ferramenta importante para depurar e monitorar códigos. O Cloud Functions oferece a opção de usar o SDK do logger, o Google Cloud Logging personalizado ou o padrão de objeto console para fins de desenvolvimento para a Web.

Como gravar registros

Embora o SDK do logger do Cloud Functions seja recomendado para a maioria das situações, é possível escolher uma das outras opções por estes motivos:

  • Você já tem uma base de código e prefere não realizar a refatoração de console.log.
  • Você conhece bem o Cloud Logging (antigo Stackdriver Logging) e prefere usá-lo para a geração de registros personalizados.

Como usar o SDK do logger do Cloud Functions

O SDK do logger do Cloud Functions fornece uma interface padrão com uma API semelhante às instruções console.log e é compatível com outros níveis de registro. Você pode usar esse SDK para registrar eventos com dados estruturados, facilitando a análise e o monitoramento.

O SDK do logger é compatível com entradas de registro como parte de uma importação de caracteres curinga. Exemplo:

  const functions = require("firebase-functions");

  functions.logger.log("Hello from info. Here's an object:", someObj);

Como alternativa, você pode usar exportações individuais. Veja neste exemplo dados estruturados anexados ao registro como o último argumento:

const { warn } = require("firebase-functions/lib/logger");

// Attach structured data to the log as the last argument.
warn("This is a 'WARNING' severity message with some metadata.", {
  key1: 'val1',
  key2: 'val2'
});
  • Os comandos logger.log() têm o nível de registro INFO.
  • Os comandos logger.info() têm o nível de registro INFO.
  • Os comandos logger.warn() têm o nível de registro ERROR.
  • Os comandos logger.error() têm o nível de registro ERROR.
  • As mensagens internas do sistema têm o nível de registro DEBUG.

Com logger.write(), é possível gravar entradas e níveis de gravidade de registros de CRITICAL, ALERT e EMERGENCY. Consulte LogSeverity.

Registros personalizados do Cloud Logging

Os registros do Cloud Functions com o SDK do logger são respaldados pelo Cloud Logging. Use a biblioteca do Cloud Logging para Node.js para registrar eventos com dados estruturados, facilitando a análise e o monitoramento.

const { Logging } = require('@google-cloud/logging');

// ...

// Instantiate the logging SDK. The project ID will
// be automatically inferred from the Cloud Functions environment.
const logging = new Logging();
const log = logging.log('my-custom-log-name');

// This metadata is attached to each log entry. This specifies a fake
// Cloud Function called 'Custom Metrics' in order to make your custom
// log entries appear in the Cloud Functions logs viewer.
const METADATA = {
  resource: {
    type: 'cloud_function',
    labels: {
      function_name: 'CustomMetrics',
      region: 'us-central1'
    }
  }
};

// ...

// Data to write to the log. This can be a JSON object with any properties
// of the event you want to record.
const data = {
  event: 'my-event',
  value: 'foo-bar-baz',

  // Optional 'message' property will show up in the Firebase
  // console and other human-readable logging surfaces
  message: 'my-event: foo-bar-baz'
};

// Write to the log. The log.write() call returns a Promise if you want to
// make sure that the log was written successfully.
const entry = log.entry(METADATA, data);
log.write(entry);

Como usar o console.log

A solução recomendada para a geração de registros de uma função é usar o SDK do logger. Em vez disso, é possível usar chamadas de geração de registros padrão em JavaScript, como console.log e console.error, mas primeiro é necessário exigir um módulo especial para corrigir os métodos padrão para funcionar corretamente:

require("firebase-functions/lib/logger/compat");

Depois de exigir o módulo de compatibilidade do logger, é possível usar os métodos console.log() normalmente no seu código:

exports.helloError = functions.https.onRequest((request, response) => {
  console.log('I am a log entry!');
  response.send('Hello World...');
});
  • Os comandos console.log() têm o nível de registro INFO.
  • Os comandos console.info() têm o nível de registro INFO.
  • Os comandos console.warn() têm o nível de registro ERROR.
  • Os comandos console.error() têm o nível de registro ERROR.
  • As mensagens internas do sistema têm o nível de registro DEBUG.

Como ver registros

Os registros para o Cloud Functions podem ser visualizados no Console do Google Cloud, na IU do Cloud Logging ou na ferramenta de linha de comando firebase.

Pela CLI do Firebase

Para ver registros com a ferramenta firebase, use o comando functions:log:

firebase functions:log

Para ver registros de uma função específica, forneça o nome da função como um argumento:

firebase functions:log --only <FUNCTION_NAME>

Para ver todas as opções de visualização de registros, confira a ajuda sobre functions:log:

firebase help functions:log

Pelo Console do Google Cloud

É possível ver registros das funções no Console do Google Cloud.

Pela IU do Cloud Logging

É possível ver os registros do Cloud Functions na IU do Cloud Logging.

Como analisar registros

O Cloud Logging oferece um conjunto de ferramentas eficientes para análise de registros que podem ser usadas para monitorar o Cloud Functions. Essas ferramentas são particularmente eficientes quando combinadas com a geração de registros personalizados.

Métricas com base em registros

Na IU do Cloud Logging, use o campo "filtro avançado" para restringir o escopo do registro para a função que você quer analisar e depois clique em Enviar filtro para filtrar os registros. Por exemplo, é possível analisar apenas os registros de uma única função:

resource.type="cloud_function"
resource.labels.function_name="myCloudFunction"
resource.labels.region="us-central1"

Se você registrou eventos com payloads JSON personalizados, poderá filtrar usando as chaves e os valores fornecidos:

resource.type="cloud_function"
resource.labels.function_name="CustomMetrics"
jsonPayload.event="my-event"

Depois de filtrar os registros, é possível analisá-los usando métricas com base em registros. Clique no botão Criar métrica para abrir o editor e selecione um tipo de métrica:

  • Métricas de contagem: contam o número de entradas de registro que correspondem a um filtro. Por exemplo, é possível contar o número de vezes que um determinado evento ocorre.
  • Métricas de distribuição: acumulam dados numéricos de entradas de registro que correspondam a um filtro. Por exemplo, é possível rastrear as latências de certas operações dentro de suas funções.

Para registros com base em texto, como aqueles resultantes de console.log() nas suas funções, é possível extrair valores e rótulos do campo textPayload usando expressões regulares. Para registros personalizados com dados estruturados, os dados podem ser acessados diretamente no campo jsonPayload.

Gráficos e alertas

Depois de ter criado métricas baseadas em registros para monitorar suas funções, você pode criar gráficos e alertas com base nessas métricas. Por exemplo, é possível criar um gráfico para visualizar a latência ao longo do tempo ou criar um alerta para saber se um determinado erro ocorre com muita frequência.

Consulte Criar gráficos e alertas para ver informações detalhadas sobre como usar métricas com base em registros nos gráficos e políticas de alerta.