Logging

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

O Google 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 apenas por um curto período.

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

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

Elas são descritas 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 ou 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 ver 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.

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 seguintes registros 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 Cloud Logging do Google Cloud. 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 melhor opção. Consulte Cotas e limites do Cloud Logging para detalhes sobre retenção de dados e outras cotas.

Para solicitar mais cota de geração de registros, envie uma solicitação de cota do Google Cloud. Para isso, você precisa ter acesso ao projeto do Cloud Platform usado pelo 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 seu Apps Script. Confira uma versão simplificada desses registros no painel do Apps Script.

Para aproveitar ao máximo o Cloud Logging e seus recursos, use um projeto na nuvem padrão do Google com seu 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 Logger do Apps Script. Em vez disso, use o serviço console.

Ao fazer o registro, é uma boa prática de privacidade evitar gravar 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é 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
/**
 * 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 ativo temporárias são uma maneira conveniente de identificar usuários únicos em 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 ativo temporárias são melhores que os identificadores de registro, como endereços de e-mail, porque:

  • Não é preciso adicionar nada ao seu registro. Eles já estão lá.
  • Elas não exigem autorização do usuário.
  • Elas protegem a privacidade do usuário.

Para encontrar chaves de usuário ativo temporárias nas entradas do Cloud Logging, 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 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 ver metadados > rótulos > script.googleapis.com/user_key.

Para receber a chave de usuário ativo temporário, chame Session.getTemporaryActiveUserKey no seu 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 você a 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, junto com um rastreamento de pilha.

Para ver 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.

Confira as exceções registradas no console do Google Cloud 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 em 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

O registro de exceções se integra automaticamente ao Cloud Error Reporting, um serviço que agrega e mostra erros produzidos no seu script. Confira 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 rastreamento. 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 solicitação "Configurar relatórios de erros", isso significa que 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.

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.