Logging

Quando sviluppi qualsiasi tipo di app, spesso vuoi registrare informazioni per contribuire a diagnosticare i guasti durante lo sviluppo, identificare e diagnosticare i problemi dei clienti e per altri scopi.

Apps Script fornisce tre diversi meccanismi per la registrazione:

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

• L'interfaccia di Cloud Logging in Developer Console, che fornisce log che rimangono attivi 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, puoi anche creare il tuo codice di logger che, ad esempio, scrive informazioni in un foglio di lavoro o in un database JDBC per la registrazione.

Utilizzare il log di esecuzione di Apps Script

Un approccio di base per il logging in Apps Script è 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 visualizzati in tempo reale.

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

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

Ad esempio, considera questa funzione:

utils/logging.gs

Visualizza su 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 questo script viene eseguito con gli input "2" e "[e-mail]", vengono scritti i seguenti log:

[16-09-12 13:50:42:193 PDT] Invio via email della riga 2 dei dati a [e-mail]
[16-09-12 13:50:42:271 PDT] Dati della riga 2: costo 103,24

Cloud Logging

Apps Script fornisce inoltre l'accesso parziale al servizio Cloud Logging della piattaforma Google Cloud (GCP). Quando hai bisogno di log permanenti per diversi giorni o di una soluzione di logging più complessa per un ambiente di produzione multiutente, Cloud Logging è la scelta migliore. Consulta Quote e limiti di Cloud Logging per informazioni sulla conservazione dei dati e su altre quote.

Se hai bisogno di un aumento della quota di logging, puoi inviare una richiesta di quota della piattaforma Google Cloud. Per farlo, devi avere accesso al progetto Cloud Platform utilizzato dallo script.

Nota: Cloud Logging fornisce una serie di servizi oltre allo stoccaggio dei log, ad esempio avvisi e metriche. Al momento questi servizi non sono disponibili da Apps Script.

Utilizzo di Cloud Logging

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

Per utilizzare al meglio 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 di Google Cloud e hai a disposizione più opzioni di visualizzazione e filtro.

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

Quando esegui il logging, è buona norma per la privacy evitare di registrare informazioni personali sull'utente, ad esempio indirizzi email. I log di Cloud vengono contrassegnati automaticamente con le chiavi utente attive che puoi utilizzare per individuare i messaggi di log di un utente specifico, se necessario.

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

L'esempio seguente mostra come utilizzare il servizio console per registrare le informazioni in Cloud Operations.

utils/logging.gs

Visualizza su 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.
}

Chiavi utente attive

Le chiavi utente attive temporanee offrono un modo pratico per rilevare gli utenti unici nelle voci del log Cloud senza rivelare le loro identità. Le chiavi sono per script e cambiano circa una volta al mese per fornire ulteriore sicurezza se un utente rivela la propria identità a uno sviluppatore, ad esempio durante la segnalazione di un problema.

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

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

Per trovare le chiavi utente attive temporanee nelle voci del log Cloud, visualizza i log Cloud nella console Google Cloud. Puoi farlo 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 tuo interesse ed espandila per visualizzare metadata > labels > script.googleapis.com/user_key.

Puoi anche ottenere 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. Gli utenti possono scegliere di includere le proprie chiavi quando segnalano i problemi per aiutarti a identificare i log pertinenti.

Logging delle eccezioni

La registrazione delle eccezioni invia le eccezioni non gestite nel codice del progetto dello 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 È scaduto il tempo.

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

Attivare la registrazione delle eccezioni

La registrazione delle eccezioni è attiva per impostazione predefinita per i nuovi progetti. Per attivare il logging delle eccezioni per i progetti precedenti:

1. Apri il progetto di script.
2. A sinistra, fai clic su Impostazioni progetto .
3. Seleziona la casella di controllo Registra le 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 generati nello script. Puoi visualizzare i report sugli errori di Cloud nella console Google Cloud. Se ti viene chiesto di configurare Error Reporting, significa che lo script non ha ancora registrato eccezioni. Non è richiesta alcuna configurazione oltre all'attivazione del logging delle eccezioni.

Requisiti per la registrazione

Non sono previsti requisiti per l'utilizzo del log di 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 generazione di report sugli errori, devi avere accesso al progetto Google Cloud dello script. Questo è possibile solo se il progetto di script utilizza un progetto Google Cloud standard.