Logging

Ao desenvolver qualquer tipo de app, muitas vezes você quer registrar informações para ajudar a diagnosticar falhas durante o desenvolvimento, identificar e diagnosticar problemas do cliente e para outros fins.

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

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

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

• A interface Error Reporting no console do desenvolvedor, 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, você também pode criar seu próprio código de registro que, por exemplo, grava informações em uma planilha ou em um banco de dados JDBC.

Usar o registro de execução do Apps Script

Uma abordagem básica para fazer login no Apps Script é usar o registro de execução integrado. Para conferir esses registros, clique em Registro de execução na parte de cima 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 registro 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

Ver no GitHub

/**
 * 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 esse script é executado com as entradas "2" e "joã[e-mail]", os seguintes registros são gravados:

[16-09-12 13:50:42:193 PDT] Envio de e-mail da linha de dados 2 para [e-mail]
[16-09-12 13:50:42:271 PDT] Dados da linha 2: custo 103,24

Cloud Logging

O Apps Script também oferece acesso parcial ao serviço Cloud Logging do Google Cloud Platform (GCP). Quando você precisa de registros que persistem 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 melhor opção. Consulte Cotas e limites do Cloud Logging para saber mais sobre retenção de dados e outras informações de cota.

Se você precisar de mais cota de registro, envie uma solicitação de cota do Google Cloud Platform. Para isso, é necessário ter acesso ao projeto do Cloud Platform usado pelo script.

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

Uso do Cloud Logging

Os registros do Cloud são anexados ao projeto do Google Cloud associado ao Apps Script. É possível conferir 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. Isso permite acessar os registros do Cloud diretamente no Console do GCP e oferece mais opções de visualização e filtragem.

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

Ao fazer o registro, é 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 marcados automaticamente com chaves de usuário ativo que podem ser usadas para localizar as mensagens de registro de um usuário específico quando necessário.

É possível registrar strings, strings formatadas e até 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 no Cloud Operations.

utils/logging.gs

Ver no GitHub

/**
 * 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 Logging 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 para um desenvolvedor, por exemplo, ao relatar 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 à sua geração de registros. Eles já estão lá.
• Elas não exigem autorização do usuário.
• Eles protegem a privacidade do usuário.

Para encontrar chaves de usuário temporárias ativas nas entradas do Cloud Logging, consulte seus registros do Cloud no console do Google Cloud. Isso só é possível se o projeto de script usar um projeto padrão do Google Cloud a que você tenha acesso. Depois de abrir o projeto do Google Cloud no console, selecione uma entrada de registro de interesse e abra para conferir metadata > labels > script.googleapis.com/user_key.

Também é possível acessar a chave de usuário ativo temporário chamando Session.getTemporaryActiveUserKey() no script. Uma maneira de usar esse método é mostrar a chave para o usuário enquanto ele executa o script. Em seguida, os usuários podem incluir as chaves ao relatar problemas para ajudar a identificar os registros relevantes.

Geração de registros de exceção

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

Para conferir 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 Failed e Timed out.

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

Ativar o registro de exceções

O registro de exceções é ativado por padrão para novos projetos. Para ativar o registro de exceções para 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 detectadas no Cloud Operations.

Error Reporting

O registro de exceções é integrado automaticamente ao Error Reporting do Cloud, um serviço que agrega e exibe erros produzidos no script. É possível acessar seus relatórios de erros do Cloud no console do Google Cloud. 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 do registro de exceções.

Requisitos de registro

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

É possível conferir 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 do GCP do script. Isso só é possível se o projeto de script usar um projeto padrão do Google Cloud.