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 zum Beispiel 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 anhält, 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. Dafür benötigen Sie Zugriff auf das Cloud Platform-Projekt, das Ihr Skript verwendet.

Hinweis: Cloud Logging bietet neben dem Speichern von Logs eine Reihe weiterer 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. Dadurch 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 aktiven Nutzerschlüsseln gekennzeichnet, mit denen Sie die Lognachrichten eines bestimmten Nutzers bei Bedarf finden können.

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

Mithilfe von 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. Schlüssel werden pro Skript erstellt und ändern sich etwa einmal pro Monat. So wird die Sicherheit erhöht, wenn ein Nutzer seine Identität 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.
• Es ist keine Nutzerautorisierung erforderlich.
• Sie schützen die Privatsphäre der Nutzer.

Wenn Sie vorübergehend aktive Nutzerschlüssel in Ihren Cloud-Logeinträ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.

Sie können den temporären aktiven Nutzerschlüssel auch durch Aufrufen von Session.getTemporaryActiveUserKey() in Ihrem Skript abrufen. 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 Skriptprojekt.
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 das Logging

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

Eine vereinfachte Version von Cloud-Logs finden Sie im Apps Script-Dashboard. Damit Sie Cloud Logging und die Fehlerberichte optimal nutzen können, müssen Sie jedoch Zugriff auf das GCP-Projekt des Skripts haben. Dies ist nur möglich, wenn in Ihrem Script-Projekt ein Google Cloud-Standardprojekt verwendet wird.