Logging

Ao desenvolver qualquer tipo de aplicativo, é comum que você queira registrar informações para ajudar diagnosticar falhas durante o desenvolvimento, para identificar e diagnosticar problemas do cliente, e para outros fins.

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

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

• A interface do Cloud Logging na o console do desenvolvedor, que fornece registros que são mantidos por muitos dias criação.

• Interface do Error Reporting no Play Console, que coleta e registra erros ocorridos 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 logger que, por exemplo, grava informações a uma planilha de geração de registros ou banco de dados JDBC.

Usar o registro de execução do Apps Script

Uma abordagem básica para o login no Apps Script é usar o de execução. Para exibir esses registros, na parte superior do editor, clique em Registro de execução. Quando você executa uma função ou usa o de depuração, o stream de registros é feito em tempo real.

É possível usar as opções Logger ou Serviços de geração de registros do console no e um registro de execução integrado.

Esses registros são feitos para 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 "[e-mail]" as os seguintes registros são gravados:

[16-09-12 13:50:42:193 PDT] Enviando por e-mail a linha 2 de dados 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 Google Cloud Platform (GCP) serviço Cloud Logging. Quando você exigir registros que persistem por vários dias ou de uma geração de registros para um ambiente de produção multiusuário, o Cloud Logging é a uma melhor opção. Consulte Cotas e limites do Cloud Logging para retenção de dados e outros detalhes de cota.

Se você precisar de mais cota de geração de registros, enviar uma solicitação de cota do Google Cloud Platform. Para isso, você precisa ter acesso Projeto do Cloud Platform que seu script usa.

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

Uso do Cloud Logging

Os registros do Google Cloud estão anexados ao projeto do Google Cloud. associadas ao seu Apps Script. Confira uma versão simplificada no painel do Apps Script.

Para aproveitar ao máximo o Cloud Logging e seus recursos, utilize uma projeto padrão do Google Cloud com seu projeto de script. Isso permite que você acesse os registros do Cloud diretamente 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 aos apps Roteiro Logger serviço. Em vez disso, use console. serviço.

Ao fazer login, é recomendável evitar a gravação de dados informações sobre o usuário, como endereços de e-mail. registros do Google Cloud são rotulados automaticamente com chaves de usuário ativas você pode usar 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 o fornecidas pelo Apps Script serviço console.

O exemplo abaixo mostra como usar o console para registrar informações nas Operações do Cloud.

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 são uma maneira conveniente de identificar usuários únicos em Entradas de registros do Cloud sem revelar a identidade desses usuários. Chaves são por script e mudam aproximadamente uma vez por mês para fornecer segurança adicional um usuário deve revelar sua identidade a um desenvolvedor, por exemplo, ao denunciar um problema.

As chaves de usuário ativas temporárias são superiores aos identificadores de geração de registros, como e-mail porque:

• Não é preciso adicionar nada à geração de registros. 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, ver os registros do Cloud no console do Google Cloud. Só é possível fazer isso se seu projeto de script estiver usando uma projeto padrão do Google Cloud aos quais 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 metadados > rótulos > script.googleapis.com/user_key.

Também é possível receber a chave de usuário ativo temporária chamando Session.getTemporaryActiveUserKey() no seu script. Uma maneira de usar esse método é exibir a chave para o usuário enquanto executam seu script. Em seguida, os usuários podem optar por incluir as chaves ao relatar problemas para identificar os registros relevantes.

Geração de registros de exceções

A geração de registros de exceções envia exceções não processadas no código do projeto de script ao Cloud Logging e um stack trace.

Para visualizar 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 as exceções registradas no Console do GCP. se seu projeto de script estiver usando uma projeto padrão do Google Cloud que você pode acessar.

Ativar registro de exceções

A geração de registros de exceções é ativada por padrão para novos projetos. Para ativar a exceção 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 nas Operações do Cloud.

Error Reporting

A geração de registros de exceções se integra automaticamente Cloud Error Reporting, um serviço que agrega e exibe erros produzidos no seu script. Você pode acessar seus relatórios de erros do Cloud no console do Google Cloud. Se você for solicitado a "Configurar o Error Reporting" isso ocorre porque seu script ainda não registrou exceções. Nenhuma configuração é necessária após Ativar a geração de registros de exceções.

Requisitos do Logging

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

Uma versão simplificada dos registros do Cloud está disponível na Painel do Apps Script. No entanto, a aproveitar ao máximo o Cloud Logging e o Error Reporting, você precisa ter acesso ao projeto do GCP do script. Isso só é possível se o projeto de script está usando um projeto padrão do Google Cloud.