Geração de registros

Ao desenvolver qualquer tipo de aplicativo, muitas vezes é necessário registrar informações para ajudar a diagnosticar falhas durante o desenvolvimento, identificar e diagnosticar problemas de clientes e para outras finalidades.

O Apps Script oferece três mecanismos diferentes de registro:

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

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

  • Interface do Error Reporting no Play Console, que coleta e registra erros que ocorrem enquanto o script está em execução.

Eles são descritos nas seções a seguir. Além desses mecanismos, também é possível criar seu próprio código 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 a geração de registros no Apps Script é usar o registro de execução integrado. Para ver esses registros, clique em Execution log na parte superior do editor. Quando você executa uma função ou usa o depurador, os registros são transmitidos em tempo real.

É possível usar 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 simples 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);
  try {
    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);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

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

[16-09-12 13:50:42:193 PDT] Enviar por e-mail a linha de dados 2 para john@example.com
[16-09-12 13:50:42:271 PDT] Dados da linha 2: custo 103,24

Cloud Logging

O Apps Script também fornece acesso parcial ao serviço Cloud Logging do Google Cloud Platform (GCP). Quando você precisa de geração de registros que persiste por vários dias ou precisa de uma solução de geração de registros mais complexa para um ambiente de produção multiusuário, o Cloud Logging é a escolha de preferência. Consulte Cotas e limites do Cloud Logging para retenção de dados e outros detalhes de cotas.

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

Como usar o Cloud Logging

Os registros do Cloud são anexados ao projeto do Google Cloud associado ao seu Apps Script. Acesse uma versão simplificada desses registros no painel do Apps Script.

Para aproveitar ao máximo o Cloud Logging e os recursos dele, use um projeto padrão do Google Cloud com seu projeto de script. Assim, é possível acessar os registros do Cloud diretamente no Console do GCP e ter mais opções de visualização e filtragem.

Durante a geração de registros, é uma boa prática de privacidade evitar registrar 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 que podem ser usadas para localizar mensagens de registro de um usuário específico quando necessário.

É possível registrar 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 serviço console para registrar informações nas Operações do Cloud.

utils/logging.gs
/**
 * 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 são uma maneira conveniente de identificar usuários únicos nas entradas do Cloud Log sem revelar as identidades deles. As chaves são por script e mudam aproximadamente uma vez por mês para aumentar a 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 é preciso adicionar nada ao registro, porque eles já estão lá.
  • Eles não exigem autorização do usuário.
  • Eles protegem a privacidade do usuário.

Para encontrar chaves de usuário ativas temporárias nas entradas do Cloud Log, veja os registros do Cloud no console do Google Cloud. Só é possível fazer isso se o projeto de script usar um projeto padrão do Google Cloud a que você tem acesso. Depois de abrir o projeto do Google Cloud no console, selecione uma entrada de registro de interesse e expanda-a para exibir metadata >labels > script.googleapis.com/user_key.

Você também pode receber a chave de usuário ativa temporária chamando Session.getTemporaryActiveUserKey() no seu script. Uma maneira de usar esse método é exibir a chave para o usuário enquanto ele executa o script. Em seguida, os usuários podem incluir as chaves ao relatar problemas para identificar os registros relevantes.

Geração de registros de exceções

O registro de exceções envia exceções não processadas no código do projeto de script para o Cloud Logging, com um stack trace.

Para ver os registros de exceção, siga as etapas abaixo:

  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 Com falha e Tempo limite atingido.

Também é possível ver exceções registradas no Console do GCP se o projeto de script estiver usando um projeto padrão do Google Cloud a que você tenha acesso.

Ativar registro de exceções

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

  1. Abra o projeto de script.
  2. À esquerda, clique em Configurações do projeto .
  3. Marque a caixa de seleção Registrar exceções não capturadas para as operações do Cloud.

Error Reporting

A geração de registros de exceções se integra automaticamente ao Cloud Error Reporting, um serviço que agrega e exibe erros produzidos no script. É possível ver os relatórios de erros do Cloud no console do Google Cloud. Se a mensagem "Configurar o Error Reporting" aparecer, isso significa que seu script ainda não registrou exceções. Nenhuma configuração é necessária além de ativar a geração de registros de exceções.

Requisitos do Logging

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

Veja uma versão simplificada dos registros do Cloud no painel do Apps Script. No entanto, para aproveitar ao máximo o Cloud Logging e os relatórios de erros, você precisa ter acesso ao projeto do GCP do script. Isso só é possível se o projeto de script estiver usando um projeto padrão do Google Cloud.