Logging

Quando sviluppi un'app, spesso vuoi registrare informazioni utili per diagnosticare gli errori durante lo sviluppo, identificare e diagnosticare i problemi dei clienti e per altri scopi.

Apps Script fornisce tre diversi meccanismi per il logging:

  • Il log di esecuzione Apps Script integrato. Questo log è leggero e viene trasmesso in tempo reale, ma persiste solo per un breve periodo di tempo.

  • Interfaccia di Cloud Logging nella console per sviluppatori, che fornisce i log che rimangono per molti giorni dopo la loro creazione.

  • Interfaccia di Error Reporting nella Console per gli sviluppatori, che raccoglie e registra gli errori che si verificano durante l'esecuzione dello script.

che vengono descritti nelle sezioni seguenti. Oltre a questi meccanismi, puoi anche creare il tuo codice logger, ad esempio che scrive le informazioni in un foglio di lavoro o nel database JDBC di logging.

Utilizzare il log di esecuzione di Apps Script

Un approccio di base al logging in Apps Script consiste nell'utilizzare il log di esecuzione integrato. Per visualizzare questi log, fai clic su Execution log (Log Esecuzione) nella parte superiore dell'editor. Quando esegui una funzione o utilizzi il debugger, i log vengono trasmessi in tempo reale.

Puoi utilizzare i servizi di logging di Logger o console nel log di esecuzione integrato.

Questi log sono destinati a semplici controlli durante lo sviluppo e il debug e non durano molto a lungo.

Ad esempio, considera questa funzione:

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);
  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 questo script viene eseguito con gli input "2" e "john@example.com"i log seguenti vengono scritti:

[16-09-12 13:50:42:193 PDT] Invio via email della riga 2 a john@example.com
[16-09-12 13:50:42:271 PDT] Dati della riga 2: costo 103,24

Cloud Logging

Apps Script fornisce anche accesso parziale al servizio Cloud Logging di Google Cloud Platform (GCP). Quando richiedi un logging che dura per diversi giorni o hai bisogno di una soluzione di logging più complessa per un ambiente di produzione multiutente, Cloud Logging è la scelta preferita. Consulta Quote e limiti di Cloud Logging per la conservazione dei dati e altri dettagli delle quote.

Se hai bisogno di una quota di log più elevata, puoi inviare una richiesta di quota di Google Cloud Platform. Ciò richiede l'accesso al progetto Cloud Platform che il tuo script utilizza.

Utilizzo di Cloud Logging

I log di Cloud sono associati al progetto GCP associato al tuo Apps Script. Puoi visualizzare una versione semplificata di questi log nella dashboard di Apps Script.

Per sfruttare al meglio Cloud Logging e le sue funzionalità, utilizza un progetto GCP standard con il progetto di script. In questo modo puoi accedere ai log di Cloud direttamente nella console di GCP e usufruire di più opzioni di visualizzazione e filtro.

Quando si registra, è buona norma evitare di registrare informazioni personali dell'utente, come gli indirizzi email. I log cloud vengono etichettati automaticamente con chiavi utente attive che puoi utilizzare per individuare i messaggi di log di un utente specifico, se necessario.

Puoi registrare stringhe, stringhe formattate e anche oggetti JSON utilizzando le funzioni fornite dal servizio Apps Script console.

L'esempio seguente mostra come utilizzare il servizio console per registrare informazioni nella suite operativa di Google Cloud.

utils/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.
}

Chiavi utente attive

Le chiavi utente attive temporanee forniscono un modo pratico per individuare utenti unici nelle voci di Cloud Log senza rivelare la loro identità. Le chiavi sono basate su script e vengono modificate circa una volta al mese per fornire ulteriore sicurezza se un utente deve rivelare la propria identità a uno sviluppatore, ad esempio per segnalare un problema.

Le chiavi utente attive temporanee sono superiori agli identificatori di logging come gli indirizzi email perché:

  • Non devi aggiungere nulla alla tua registrazione; sono già lì!
  • Non richiedono l'autorizzazione dell'utente.
  • Proteggono la privacy degli utenti.

Per trovare le chiavi utente attive temporanee nelle voci di Cloud Log, visualizza i log di Cloud nella console di GCP. Puoi eseguire questa operazione solo se il tuo progetto di script utilizza un progetto GCP standard a cui hai accesso. Una volta aperto il progetto GCP nella console, seleziona una voce di log di interesse ed espandila per visualizzare metadata > labels > script.googleapis.com/user_key.

Puoi anche recuperare la chiave utente attiva temporanea chiamando Session.getTemporaryActiveUserKey() nel tuo script. Un modo per utilizzare questo metodo è mostrare la chiave all'utente mentre esegue lo script. Quindi gli utenti possono scegliere di includere le proprie chiavi quando segnalano i problemi per aiutarti a identificare i log pertinenti.

Logging delle eccezioni

Il logging delle eccezioni invia a Cloud Logging eccezioni non gestite nel codice del progetto di script, insieme a un'analisi dello stack.

Per visualizzare i log delle eccezioni:

  1. Apri il progetto Apps Script.
  2. A sinistra, fai clic su Esecuzioni .
  3. In alto, fai clic su Aggiungi un filtro > Stato.
  4. Seleziona le caselle di controllo Non riuscito e Timeout.

Puoi anche visualizzare le eccezioni registrate nella console di GCP se il tuo progetto di script utilizza un progetto GCP standard a cui hai accesso.

Abilita il logging delle eccezioni

Il logging delle eccezioni è abilitato per impostazione predefinita per i nuovi progetti. Per abilitare la registrazione delle eccezioni per progetti meno recenti:

  1. Apri il progetto dello script.
  2. A sinistra, fai clic su Impostazioni progetto .
  3. Seleziona la casella di controllo Registra eccezioni non rilevate nella Suite operativa di Google Cloud.

Error Reporting

Il logging delle eccezioni si integra automaticamente con Cloud Error Reporting, un servizio che aggrega e mostra gli errori prodotti nel tuo script. Puoi visualizzare i report sugli errori Cloud nella console di GCP. Se ti viene chiesto "Configura Error Reporting", questo perché il tuo script non ha ancora registrato eccezioni. Non è richiesta alcuna configurazione oltre all'attivazione del logging delle eccezioni.

Requisiti di logging

Non sono previsti requisiti per l'utilizzo del log Execution (Esecuzione) integrato.

Puoi visualizzare una versione semplificata dei log di Cloud nella dashboard di Apps Script. Tuttavia, per sfruttare al meglio Cloud Logging e la segnalazione degli errori, devi avere accesso al progetto GCP dello script. Ciò è possibile solo se il progetto di script utilizza un progetto GCP standard.