Logging

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

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

• o registro de execução do Apps Script integrado. Esse registro é leve e transmite em tempo real, mas persiste apenas por pouco tempo.

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

• A interface do Error Reporting no Developer Console, que coleta e registra erros que ocorrem enquanto seu 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 geração de registros 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 a geração de registros no Apps Script é usar o registro de execução integrado. Para vê-los, clique em Registro de execução 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

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

[16-09-12 13:50:42:193 PDT] Como enviar um e-mail com a 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 fornece acesso parcial ao serviço Cloud Logging do Google Cloud Platform (GCP). O Cloud Logging é a melhor opção quando você precisa de registros que permaneçam por vários dias ou de uma solução de geração de registros mais complexa para um ambiente de produção multiusuário. Consulte Cotas e limites do Cloud Logging para mais informações sobre retenção de dados e outros detalhes da cota.

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

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

Como usar o Cloud Logging

Os registros do Cloud estão anexados ao projeto do Google Cloud associado ao Apps Script. É possível visualizar 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 será compatível com o serviço Logger do Apps Script. Em vez disso, use o serviço console.

Ao fazer login, é recomendável evitar a gravação 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 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é 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 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 do usuário ativo

As chaves de usuário ativas temporárias oferecem uma maneira conveniente de identificar usuários únicos nas entradas do Cloud Log sem revelar as identidades desses usuários. 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, enquanto relata um problema.

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

• Você não precisa adicionar nada ao seu registro. Eles já estão lá.
• Eles não precisam de autorização do usuário.
• Eles protegem a privacidade do usuário.

Para encontrar chaves de usuário ativas temporárias nas suas entradas de registro do Cloud, visualize os registros do Cloud no Console do Google Cloud. Só é possível fazer isso se o projeto de script estiver usando 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 a expanda para visualizar metadata > labels > script.googleapis.com/user_key.

Também é possível receber a chave de usuário ativa temporária chamando Session.getTemporaryActiveUserKey() no 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 optar por incluir as chaves deles ao relatar problemas para ajudar a identificar os registros relevantes.

Registro 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, junto com um rastreamento de pilha.

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 superior, 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 ao qual você tem acesso.

Ativar 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 identificadas nas Operações do Cloud.

Error Reporting

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

Requisitos de registro

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

É possível ver 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.