Logging

Quando sviluppi qualsiasi tipo di app, registra le informazioni per facilitare la diagnosi dei guasti durante lo sviluppo, per identificare e diagnosticare i problemi dei clienti e per altri scopi.

Google Apps Script fornisce tre diversi meccanismi per la registrazione:

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

  • L'interfaccia Cloud Logging in Play Console, che fornisce log che vengono conservati per molti giorni dopo la loro creazione.

  • L'interfaccia Error Reporting nella console per gli sviluppatori, che raccoglie e registra gli errori che si verificano durante l'esecuzione dello script.

Questi sono descritti nelle sezioni seguenti. Oltre a questi meccanismi, crea il tuo codice logger che, ad esempio, scrive informazioni in un foglio di lavoro o in un database JDBC.

Utilizzare il log di esecuzione di Apps Script

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

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

Questi log sono destinati ai controlli durante lo sviluppo e il debug e non vengono conservati 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}`);
  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 questo script viene eseguito con gli input "2" e "john@example.com", vengono scritti i seguenti log:

> [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

Apps Script fornisce anche l'accesso parziale al servizio Cloud Logging di Google Cloud. Quando hai bisogno di un logging che persista per diversi giorni o 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 informazioni sulla conservazione dei dati e altri dettagli sulle quote.

Per richiedere una quota di logging maggiore, invia una richiesta di quota Google Cloud. Per farlo, devi avere accesso al progetto Cloud Platform utilizzato dallo script.

Cloud Logging offre una serie di servizi oltre all'archiviazione dei log, come avvisi e metriche. Questi servizi non sono disponibili da Apps Script.

Utilizzare Cloud Logging

I log di Cloud sono collegati al progetto Google Cloud associato al tuo Apps Script. Visualizza una versione semplificata di questi log nella dashboard Apps Script.

Per utilizzare appieno Cloud Logging e le sue funzionalità, utilizza un progetto Google Cloud standard con il tuo progetto di script. In questo modo puoi accedere ai log di Cloud direttamente nella console Google Cloud e hai a disposizione più opzioni di visualizzazione e filtro.

Se utilizzi il runtime Rhino, Cloud Logging non supporta il servizio Apps Script Logger. Utilizza invece il servizio console.

Quando registri, è buona norma per la privacy evitare di registrare informazioni personali sull'utente, come gli indirizzi email. I log cloud vengono etichettati automaticamente con chiavi utente attive per individuare i messaggi di log di un utente specifico, se necessario.

Stringhe di log, stringhe formattate e persino oggetti JSON utilizzando le funzioni fornite dal servizio console di Apps Script.

L'esempio seguente mostra come utilizzare il servizio console per registrare informazioni in 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.
}

Chiavi utente attive

Le chiavi utente attive temporanee forniscono un modo pratico per individuare gli utenti unici nelle voci di Cloud Log senza rivelarne l'identità. Le chiavi sono per script e cambiano circa una volta al mese per fornire ulteriore sicurezza nel caso in cui un utente riveli la propria identità a uno sviluppatore, ad esempio durante la segnalazione di un problema.

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

  • Non devi aggiungere nulla ai log, sono già presenti.
  • Non richiedono l'autorizzazione dell'utente.
  • Proteggono la privacy degli utenti.

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

Per ottenere la chiave utente attivo temporanea, chiama Session.getTemporaryActiveUserKey nello script. Un modo per utilizzare questo metodo è mostrare la chiave all'utente mentre esegue lo script. Gli utenti possono quindi scegliere di includere le proprie chiavi quando segnalano problemi per aiutarti a identificare i log pertinenti.

Registrazione delle eccezioni

La registrazione delle eccezioni invia le eccezioni non gestite nel codice del progetto script a Cloud Logging, insieme a una traccia 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.

Visualizza le eccezioni registrate nella console Google Cloud se il tuo progetto script utilizza un progetto Google Cloud standard a cui hai accesso.

Abilita il logging delle eccezioni

La registrazione delle eccezioni è attivata per impostazione predefinita per i nuovi progetti. Per abilitare la registrazione delle eccezioni per i progetti precedenti, segui questi passaggi:

  1. Apri il progetto di script.
  2. A sinistra, fai clic su Impostazioni progetto .
  3. Seleziona la casella di controllo Registra eccezioni non rilevate in Cloud Operations.

Error Reporting

La registrazione delle eccezioni si integra automaticamente con Cloud Error Reporting, un servizio che aggrega e mostra gli errori prodotti nello script. Visualizza i report sugli errori di Cloud nella console Google Cloud. Non è necessario configurare manualmente Error Reporting o creare voci di traccia. Apps Script compila automaticamente i campi obbligatori quando viene generata un'eccezione o quando utilizzi console.error con un oggetto Error. Se ti viene chiesto di "Configurare la segnalazione errori", è perché lo script non ha ancora registrato eccezioni. Non è richiesta alcuna configurazione oltre all'abilitazione della registrazione delle eccezioni.

Requisiti di registrazione

Non esistono requisiti per l'utilizzo del log di esecuzione integrato.

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