Logging

Ao desenvolver qualquer tipo de app, registre informações para ajudar a diagnosticar falhas durante o desenvolvimento, identificar e diagnosticar problemas do cliente e para outras finalidades.

O Google Apps Script oferece três mecanismos diferentes para geração de registros:

  • O registro de execução integrado do Apps Script. Esse registro é leve e transmite em tempo real, mas persiste apenas por um curto período.

  • A interface do Cloud Logging no Developer Console, que fornece registros que persistem por muitos dias após a criação.

  • A interface do Error Reporting no Developer Console, que coleta e registra erros que ocorrem durante a execução do script.

Eles são descritos nas seções a seguir. Além desses mecanismos, crie seu próprio código de logger que, por exemplo, grava informações em uma planilha de geração de registros ou em um banco de dados JDBC.

Usar o registro de execução do Apps Script

Uma abordagem básica para geração de registros no Apps Script é usar o registro de execução integrado. Para visualizar esses registros, na parte de cima do editor, clique em Registro de execução. Quando você executa uma função ou usa o depurador, os registros são transmitidos em tempo real.

Use os serviços de geração de registros Logger ou console no registro de execução integrado.

Esses registros são destinados a verificações durante o desenvolvimento e a depuração e não persistem por muito tempo.

Por exemplo, considere esta função:

utils/logging.gs
/**
 * Logs Google Sheet information.
 * @param {number} rowNumber The spreadsheet row number.
 * @param {string} email The email to send with the row data.
 */
function emailDataRow(rowNumber, email) {
  console.log(`Emailing data row ${rowNumber} to ${email}`);
  const sheet = SpreadsheetApp.getActiveSheet();
  const data = sheet.getDataRange().getValues();
  const rowData = data[rowNumber - 1].join(" ");
  console.log(`Row ${rowNumber} data: ${rowData}`);
  MailApp.sendEmail(email, `Data in row ${rowNumber}`, rowData);
}

Quando esse script é executado com as entradas "2" e "john@example.com", os registros a seguir são gravados:

> [16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
> [16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

Cloud Logging

O Apps Script também oferece acesso parcial ao serviço do Google Cloud Cloud Logging. Quando você precisa de registros que persistem por vários dias ou de uma solução de geração de registros mais complexa para um ambiente de produção multiusuário, o Cloud Logging é a opção preferencial. Consulte as cotas e os limites do Cloud Logging para retenção de dados e outros detalhes de cota.

Para solicitar mais cota de geração de registros, envie uma solicitação de cota do Google Cloud. Isso exige que você tenha acesso ao projeto do Cloud Platform usado pelo seu script.

O Cloud Logging oferece vários serviços além do armazenamento de registros, como alertas e métricas. Esses serviços não estão disponíveis no Apps Script.

Usar o Cloud Logging

Os registros do Cloud são anexados ao projeto do Google Cloud associado ao Apps Script. Confira uma versão simplificada de esses registros no painel do Apps Script.

Para aproveitar ao máximo o Cloud Logging e os recursos dele, use um projeto na nuvem padrão do Google com o projeto de script. Isso permite acessar os registros do Cloud diretamente no console do Google Cloud e oferece mais opções de visualização e filtragem.

Se você usar o ambiente de execução do Rhino, o Cloud Logging não vai oferecer suporte ao serviço do Apps Script Logger. Em vez disso, use o console serviço.

Ao gerar registros, é uma boa prática de privacidade evitar o registro de informações pessoais sobre o usuário, como endereços de e-mail. Os registros do Cloud são rotulados automaticamente com chaves de usuário ativas para localizar as mensagens de registro de um usuário específico quando necessário.

Registre strings, strings formatadas e até mesmo objetos JSON usando as funções fornecidas pelo serviço console do Apps Script.

O exemplo a seguir mostra como usar o console serviço para registrar informações no Cloud Operations.

utils/logging.gs
/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * Logs the time taken to execute 'myFunction'.
 */
function measuringExecutionTime() {
  // A simple INFO log message, using sprintf() formatting.
  console.info("Timing the %s function (%d arguments)", "myFunction", 1);

  // Log a JSON object at a DEBUG level. The log is labeled
  // with the message string in the log viewer, and the JSON content
  // is displayed in the expanded log structure under "jsonPayload".
  const parameters = {
    isValid: true,
    content: "some string",
    timestamp: new Date(),
  };
  console.log({ message: "Function Input", initialData: parameters });
  const label = "myFunction() time"; // Labels the timing log entry.
  console.time(label); // Starts the timer.
  try {
    myFunction(parameters); // Function to time.
  } catch (e) {
    // Logs an ERROR message.
    console.error(`myFunction() yielded an error: ${e}`);
  }
  console.timeEnd(label); // Stops the timer, logs execution duration.
}

Chaves de usuário ativas

As chaves de usuário ativas temporárias oferecem uma maneira conveniente de identificar usuários exclusivos nas entradas de registro do Cloud sem revelar as identidades deles. As chaves são por script e mudam aproximadamente uma vez por mês para oferecer mais segurança caso um usuário revele a identidade a um desenvolvedor, por exemplo, ao informar um problema.

As chaves de usuário ativas temporárias são superiores aos identificadores de registro, como endereços de e-mail, porque:

  • Não é necessário adicionar nada à geração de registros. Elas já estão lá.
  • Não exigem autorização do usuário.
  • Protegem a privacidade do usuário.

Para encontrar chaves de usuário ativas temporárias nas entradas de registro do Cloud, consulte os registros do Cloud no console do Google Cloud. Faça isso apenas se o projeto de script estiver usando um projeto padrão do Google Cloud ao qual você tem acesso. Depois de abrir o projeto na nuvem do Google Cloud no console, selecione uma entrada de registro de interesse e expanda-a para visualizar metadados > rótulos > script.googleapis.com/user_key.

Para receber a chave de usuário ativa temporária, chame Session.getTemporaryActiveUserKey no script. Uma maneira de usar esse método é mostrar a chave ao usuário enquanto ele executa o script. Em seguida, os usuários podem incluir as chaves ao informar problemas para ajudar a identificar os registros relevantes.

Geração de registros de exceção

A geração de registros de exceção envia exceções não tratadas no código do projeto de script para o Cloud Logging, juntamente com um stack trace.

Para visualizar os registros de exceção, siga estas etapas:

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Execuções .
  3. Na parte de cima, clique em Adicionar um filtro > Status.
  4. Marque as caixas de seleção Falha e Tempo limite excedido.

Visualize as exceções registradas no console do Google Cloud se o projeto de script estiver usando um projeto padrão do Google Cloud ao qual você tem acesso.

Ativar a geração de registros de exceção

A geração de registros de exceção é ativada por padrão para novos projetos. Para ativar a geração de registros de exceção para projetos mais antigos, siga estas etapas:

  1. Abra o projeto de script.
  2. À esquerda, clique em Configurações do projeto .
  3. Marque a caixa de seleção Incluir exceções não detectadas no Cloud Operations.

Error Reporting

A geração de registros de exceção é integrada automaticamente ao Cloud Error Reporting, um serviço que agrega e mostra erros produzidos no script. Consulte os relatórios de erros do Cloud no console do Google Cloud. Não é necessário configurar manualmente o Error Reporting nem criar entradas de trace. O Apps Script preenche automaticamente os campos obrigatórios quando uma exceção é gerada ou quando você usa console.error com um objeto Error. Se você receber a mensagem "Configurar o Error Reporting", é porque o script ainda não registrou nenhuma exceção. Nenhuma configuração é necessária além da ativação da geração de registros de exceção.

Requisitos de geração de registros

Não há requisitos para usar o registro de execução integrado.

Confira uma versão simplificada dos registros do Cloud no painel do Apps Script. No entanto, para aproveitar ao máximo o Cloud Logging e o Error Reporting, é necessário ter acesso ao projeto na nuvem do Google Cloud do script. Isso só é possível se o projeto de script estiver usando um projeto padrão do Google Cloud.