Logging

Bei der Entwicklung von Apps jeglicher Art sollten Sie häufig Informationen erfassen, um Fehler während der Entwicklung zu diagnostizieren, Kundenprobleme zu erkennen und zu diagnostizieren und für andere Zwecke.

Apps Script bietet drei verschiedene Logging-Mechanismen:

• Das integrierte Apps Script-Ausführungsprotokoll Dieses Protokoll ist speichersparend und wird in Echtzeit gestreamt, bleibt aber nur für kurze Zeit erhalten.

• Die Cloud Logging-Benutzeroberfläche in der Entwicklerkonsole, die Protokolle bereitstellt, die nach ihrer Erstellung noch viele Tage lang vorhanden sind.

• Die Fehlerberichte in der Entwicklerkonsole, in denen Fehler erfasst werden, die während der Ausführung des Scripts auftreten.

Diese werden in den folgenden Abschnitten beschrieben. Zusätzlich zu diesen Mechanismen können Sie auch eigenen Logging-Code erstellen, der beispielsweise Informationen in eine Logging-Tabelle oder JDBC-Datenbank schreibt.

Apps Script-Ausführungsprotokoll verwenden

Eine grundlegende Möglichkeit zum Logging in Apps Script ist die Verwendung des integrierten Ausführungslogs. Wenn Sie diese Protokolle aufrufen möchten, klicken Sie oben im Editor auf Ausführungsprotokoll. Wenn Sie eine Funktion ausführen oder den Debugger verwenden, werden die Protokolle in Echtzeit gestreamt.

Sie können entweder die Logging-Dienste Logger oder console im integrierten Ausführungsprotokoll verwenden.

Diese Protokolle sind für einfache Prüfungen während der Entwicklung und Fehlerbehebung gedacht und werden nicht lange aufbewahrt.

Betrachten Sie beispielsweise diese Funktion:

utils/logging.gs

Auf GitHub ansehen

/**
 * 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);
  }
}

Wenn dieses Script mit den Eingaben „2“ und „[e-mail]“ ausgeführt wird, werden die folgenden Protokolle geschrieben:

[16-09-12 13:50:42:193 PDT] E-Mail-Adresse für Zeile 2 an [e-mail] senden
[16-09-12 13:50:42:271 PDT] Daten in Zeile 2: Kosten 103,24

Cloud Logging

Apps Script bietet auch teilweisen Zugriff auf den Cloud Logging-Dienst der Google Cloud Platform (GCP). Wenn Sie Logging benötigen, das mehrere Tage lang gespeichert bleibt, oder eine komplexere Logging-Lösung für eine Produktionsumgebung mit mehreren Nutzern, ist Cloud Logging die bevorzugte Lösung. Informationen zur Datenaufbewahrung und zu anderen Kontingentdetails finden Sie unter Kontingente und Limits für Cloud Logging.

Wenn Sie ein größeres Logging-Kontingent benötigen, können Sie eine Google Cloud Platform-Kontingentanfrage stellen. Dazu benötigen Sie Zugriff auf das Cloud Platform-Projekt, das Ihr Script verwendet.

Hinweis: Cloud Logging bietet neben dem Speichern von Protokollen noch weitere Dienste, z. B. Benachrichtigungen und Messwerte. Diese Dienste sind derzeit nicht über Apps Script verfügbar.

Cloud Logging verwenden

Cloud-Logs sind mit dem Google Cloud-Projekt verknüpft, das mit Ihrem Apps Script verknüpft ist. Eine vereinfachte Version dieser Protokolle finden Sie im Apps Script-Dashboard.

Wenn Sie Cloud Logging und seine Funktionen optimal nutzen möchten, verwenden Sie ein Google Cloud-Standardprojekt mit Ihrem Scriptprojekt. So können Sie direkt in der GCP Console auf Cloud-Logs zugreifen und haben mehr Anzeige- und Filteroptionen.

Hinweis :Wenn Sie die Rhino-Laufzeit verwenden, wird der Apps Script-Dienst Logger von Cloud Logging nicht unterstützt. Verwenden Sie stattdessen den Dienst console.

Aus Datenschutzgründen sollten Sie bei der Protokollierung keine personenbezogenen Daten wie E-Mail-Adressen speichern. Cloud-Logs werden automatisch mit Schlüsseln für aktive Nutzer gekennzeichnet. Anhand dieser Schlüssel können Sie bei Bedarf die Protokollmeldungen eines bestimmten Nutzers finden.

Mit den Funktionen des Apps Script-Dienstes console können Sie Strings, formatierte Strings und sogar JSON-Objekte protokollieren.

Im folgenden Beispiel wird gezeigt, wie Sie mit dem Dienst console Informationen in Cloud Operations protokollieren.

utils/logging.gs

Auf GitHub ansehen

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

Schlüssel aktiver Nutzer

Mit temporären Schlüsseln für aktive Nutzer können Sie einzelne Nutzer in Cloud-Logeinträgen leicht erkennen, ohne dass die Identitäten dieser Nutzer offengelegt werden. Die Schlüssel sind pro Script und werden etwa einmal im Monat geändert, um zusätzliche Sicherheit zu bieten, falls ein Nutzer seine Identität gegenüber einem Entwickler preisgibt, z. B. beim Melden eines Problems.

Temporäre Schlüssel für aktive Nutzer sind Logging-IDs wie E-Mail-Adressen überlegen, weil:

• Sie müssen Ihrem Logging nichts hinzufügen, da die Daten bereits vorhanden sind.
• Sie erfordern keine Nutzerautorisierung.
• Sie schützen die Privatsphäre der Nutzer.

Wenn Sie vorübergehend aktive Nutzerschlüssel in Ihren Cloud Logging-Einträgen finden möchten, rufen Sie Ihre Cloud Logs in der Google Cloud Console auf. Das ist nur möglich, wenn in Ihrem Script-Projekt ein Google Cloud-Standardprojekt verwendet wird, auf das Sie Zugriff haben. Nachdem Sie das Google Cloud-Projekt in der Console geöffnet haben, wählen Sie einen interessanten Logeintrag aus und maximieren Sie ihn, um metadata > labels > script.googleapis.com/user_key zu sehen.

Du kannst den Schlüssel für den vorübergehend aktiven Nutzer auch abrufen, indem du in deinem Script Session.getTemporaryActiveUserKey() aufrufst. Eine Möglichkeit, diese Methode zu verwenden, besteht darin, den Schlüssel dem Nutzer anzuzeigen, während er Ihr Script ausführt. Nutzer können dann beim Melden von Problemen ihre Schlüssel angeben, damit Sie die relevanten Protokolle leichter finden.

Logging von Ausnahmen

Beim Auslösen von Ausnahmen werden nicht behandelte Ausnahmen im Code Ihres Scriptprojekts zusammen mit einem Stack-Trace an Cloud Logging gesendet.

So rufen Sie Ausnahmeprotokolle auf:

1. Öffnen Sie das Apps Script-Projekt.
2. Klicken Sie links auf Ausführungen .
3. Klicken Sie oben auf Filter hinzufügen > Status.
4. Klicken Sie die Kästchen Fehlgeschlagen und Zeitüberschreitung an.

Sie können sich auch geloggte Ausnahmen in der GCP Console ansehen, wenn in Ihrem Scriptprojekt ein Google Cloud-Standardprojekt verwendet wird, auf das Sie Zugriff haben.

Ausnahmeprotokollierung aktivieren

Das Ausschlags-Logging ist für neue Projekte standardmäßig aktiviert. So aktivieren Sie das Ausschlagsprotokoll für ältere Projekte:

1. Öffnen Sie das Script-Projekt.
2. Klicken Sie links auf Projekteinstellungen .
3. Klicken Sie das Kästchen Nicht erkannte Ausnahmen in Cloud Operations protokollieren an.

Error Reporting

Die Ausnahmeprotokollierung wird automatisch in Cloud Error Reporting eingebunden, einem Dienst, der Fehler in Ihrem Script zusammenfasst und anzeigt. Sie können sich Ihre Cloud-Fehlerberichte in der Google Cloud Console ansehen. Wenn Sie aufgefordert werden, „Fehlerberichte einzurichten“, wurden in Ihrem Script noch keine Ausnahmen protokolliert. Neben der Aktivierung des Ausnahme-Loggings ist keine Einrichtung erforderlich.

Anforderungen an die Protokollierung

Für die Verwendung des integrierten Ausführungslogs gelten keine Anforderungen.

Eine vereinfachte Version von Cloud-Logs finden Sie im Apps Script-Dashboard. Wenn Sie Cloud Logging und Fehlerberichte jedoch optimal nutzen möchten, benötigen Sie Zugriff auf das GCP-Projekt des Scripts. Dies ist nur möglich, wenn in Ihrem Script-Projekt ein Google Cloud-Standardprojekt verwendet wird.