Questa pagina è stata tradotta dall'API Cloud Translation.

Logging

Durante lo sviluppo di qualsiasi tipo di app, potresti voler registrare informazioni per diagnosticare gli errori durante lo sviluppo, identificare e diagnosticare i problemi dei clienti e per altri scopi.

Apps Script offre tre diversi meccanismi per il logging:

Il log integrato di esecuzione di Apps Script. Questo log è leggero e trasmette in flussi in tempo reale, ma persiste solo per un breve periodo di tempo.
L'interfaccia di Cloud Logging nella Developer Console, che fornisce i log che rimangono memorizzati per molti giorni dopo la loro creazione.
L'interfaccia Error Reporting della Developer Console, che raccoglie e registra gli errori che si verificano durante l'esecuzione dello script.

Queste informazioni sono descritte nelle sezioni seguenti. Oltre a questi meccanismi, puoi anche creare un codice logger personale che, ad esempio, scrive informazioni in un foglio di lavoro o in un database JDBC di logging.

Utilizza 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 Log esecuzione nella parte superiore dell'editor. Quando esegui una funzione o utilizzi il debugger, il flusso di log dei log 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 vengono mantenuti 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 "john@example.com", vengono scritti i seguenti log:

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

Cloud Logging

Apps Script fornisce inoltre accesso parziale al servizio Cloud Logging di Google Cloud Platform (Google Cloud). Se hai bisogno di una soluzione di logging che persiste 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 la conservazione dei dati e altri dettagli sulle quote.

Se hai bisogno di un aumento della quota di logging, puoi inviare una richiesta di quota della piattaforma Google Cloud. Ciò richiede che tu abbia accesso al progetto Cloud Platform utilizzato dal tuo script.

Utilizzo di Cloud Logging

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

Per sfruttare appieno Cloud Logging e le sue funzionalità, usa 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 usufruire di più opzioni di visualizzazione e filtro.

Durante il logging, è buona norma evitare di registrare informazioni personali relative all'utente, ad esempio gli indirizzi email. I log di Cloud vengono etichettati automaticamente con chiavi utente attive che puoi utilizzare per individuare i messaggi di log di un utente specifico quando 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 nella Suite operativa di Google Cloud.

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 conveniente per individuare gli utenti unici nelle voci di Cloud Log senza rivelare le identità di questi utenti. Le chiavi sono per script e vengono modificate 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 al tuo logging: sono già lì.
Non richiedono l'autorizzazione dell'utente.
Tutelano la privacy degli utenti.

Per trovare le chiavi utente attive temporanee nelle voci di Cloud Log, visualizza i log di Cloud nella console Google Cloud. Puoi farlo solo se il progetto di script utilizza un progetto Google Cloud standard a cui hai accesso. Una volta aperto il progetto Google Cloud nella console, seleziona una voce di log che ti interessa ed espandila per visualizzare metadati > etichette > script.googleapis.com/user_key.

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

Logging delle eccezioni

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

Per visualizzare i log delle eccezioni:

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

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

Abilita il logging delle eccezioni

La registrazione delle eccezioni è abilitata per impostazione predefinita per i nuovi progetti. Per abilitare il logging delle eccezioni per i progetti meno recenti, procedi come segue:

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

Error Reporting

Il logging delle eccezioni si integra automaticamente con Cloud Error Reporting, un servizio che aggrega e visualizza gli errori prodotti 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 è necessaria alcuna configurazione oltre ad attivare il logging delle eccezioni.

Requisiti di logging

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 Error Reporting, devi avere accesso al progetto Google Cloud dello script. Ciò è possibile solo se il progetto di script utilizza un progetto Google Cloud standard.