Logging

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Ao desenvolver qualquer tipo de app, é recomendável 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 é transmitido em tempo real, mas persiste apenas por um curto período.

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

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

Isso é descrito nas seções a seguir. Além desses mecanismos, também é possível criar seu próprio código de gerador, 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

Novo editor

Uma abordagem básica para a geração de registros no Apps Script é usar o registro de execução integrado. Para ver esses registros, na parte superior 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.

É 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 depuração e não permanecem muito longos.

Editor legado

Uma abordagem básica para a geração de registros no Apps Script é usar o logger integrado. Para visualizar os registros criados dessa maneira, selecione View > Logs no editor de scripts. Esses registros são destinados a verificações simples durante o desenvolvimento e a depuração e não permanecem muito longos.

Por exemplo, considere esta função:

util./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
    Logger.log('Failed with error %s', err.message);
  }
}

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

[16-09-12 13:50:42:193 PDT] Data 2 para enviar um e-mail 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 registro mais complexa para um ambiente de produção multiusuário, o Cloud Logging é a escolha preferida. Consulte Cotas e limites do Cloud Logging para ver a retenção de dados e outros detalhes da cota.

Se você precisar aumentar a cota de geração de registros, envie uma solicitação de cota do Google Cloud Platform. Você precisa ter acesso ao projeto do Cloud Platform que seu script usa.

Como usar o Cloud Logging

Os registros do Cloud são anexados ao projeto do GCP associado ao Apps Script. Você pode ver 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 GCP com seu projeto de script. Isso permite que você acesse os registros do Cloud diretamente no Console do GCP e fornece mais opções de visualização e filtragem.

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 mensagens de registro de um usuário específico quando necessário.

Você pode 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 em Operações do Cloud.

util./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 do usuário ativas

As chaves de usuário ativas temporárias fornecem uma maneira conveniente de identificar usuários únicos nas entradas do Cloud Logging sem revelar as identidades desses usuários. As chaves são por script e mudam aproximadamente uma vez por mês para oferecer mais segurança se um usuário revelar a identidade dele a um desenvolvedor, por exemplo, enquanto informa um problema.

As chaves de usuário ativas temporárias são melhores do que registrar identificadores, como endereços de e-mail, porque:

  • Você não precisa adicionar nada ao seu registro, eles já estão disponíveis.
  • 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 suas entradas de registro do Cloud, consulte os registros do Cloud no Console do GCP. Só faça isso se o projeto de script estiver usando um projeto padrão do GCP a que você tem acesso. Depois de abrir o projeto do GCP no console, selecione uma entrada de registro de interesse e expanda-a para ver metadata > labels > script.googleapis.com/user_key.

Também é possível 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 estiver executando o script. Os usuários podem optar por incluir as chaves deles ao informar problemas para ajudar a identificar os registros relevantes.

Registro de exceção

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

Novo editor

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.

Editor legado

Para visualizar essas exceções no painel do Apps Script, veja os detalhes do projeto e selecione > Execution Executions.

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 GCP a que você tem acesso.

Ativar o registro de exceções

O registro de exceções está ativado por padrão para novos projetos. Para ativar o registro de exceções para projetos mais antigos, siga as etapas abaixo:

Novo editor

  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 nas operações do Cloud.

Editor legado

  1. Abra o projeto de script no editor de script.
  2. Na parte superior, clique em File > Project Properties > Info > Log exception.

Error Reporting

O registro de exceções é integrado 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 GCP. Se você receber uma solicitação para "Configurar o Error Reporting" é porque seu script ainda não registrou nenhuma exceção. Nenhuma configuração é necessária além de ativar o registro de exceções.

Requisitos de geração de registros

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

Você pode 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 GCP.