Logging

Bei der Entwicklung von Apps ist es oft sinnvoll, Informationen zu protokollieren, um Fehler während der Entwicklung zu diagnostizieren, Kundenprobleme zu identifizieren und zu diagnostizieren und für andere Zwecke.

Apps Script bietet drei verschiedene Mechanismen für das Logging:

• Das integrierte Apps Script-Ausführungsprotokoll. Dieses Log ist klein und wird in Echtzeit gestreamt, ist aber nur für kurze Zeit verfügbar.

• Die Cloud Logging-Schnittstelle in der Entwicklerkonsole, die Logs bereitstellt, die viele Tage nach ihrer Erstellung bestehen bleiben.

• Die Error Reporting-Benutzeroberfläche in der Developer Console, in der Fehler erfasst und aufgezeichnet werden, die während der Ausführung Ihres Skripts auftreten.

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

Apps Script-Ausführungsprotokoll verwenden

Ein einfacher Ansatz für das Logging in Apps Script ist die Verwendung des integrierten Ausführungsprotokolls. Klicken Sie oben im Editor auf Ausführungslog, um diese Logs aufzurufen. Wenn Sie eine Funktion ausführen oder den Debugger verwenden, werden die Logs in Echtzeit gestreamt.

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

Diese Logs sind für einfache Prüfungen während der Entwicklung und des Debuggings vorgesehen und werden nicht sehr lange gespeichert.

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 Skript mit den Eingaben „2“ und „[e-mail]“ ausgeführt wird, werden die folgenden Protokolle geschrieben:

[16-09-12 13:50:42:193 PDT] Emailing data row 2 to [e-mail]
[16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

Cloud Logging

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

Wenn Sie mehr Kontingent für das Logging benötigen, können Sie eine Google Cloud Platform-Kontingentanfrage senden. Dazu benötigen Sie Zugriff auf das Cloud Platform-Projekt, das von Ihrem Skript verwendet wird.

Hinweis :Cloud Logging bietet neben dem Speichern von Logs auch eine Reihe weiterer Dienste wie Benachrichtigungen und Messwerte. Derzeit sind diese Dienste nicht über Apps Script verfügbar.

Cloud Logging verwenden

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

Wenn Sie Cloud Logging und seine Funktionen in vollem Umfang nutzen möchten, verwenden Sie ein Standard-Google Cloud-Projekt für Ihr 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 in Cloud Logging nicht unterstützt. Verwenden Sie stattdessen den console-Dienst.

Beim Logging sollten Sie keine personenbezogenen Daten des Nutzers wie E-Mail-Adressen aufzeichnen. Cloud-Logs werden automatisch mit Schlüsseln für aktive Nutzer gekennzeichnet, mit denen Sie bei Bedarf die Log-Nachrichten eines bestimmten Nutzers 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 den console-Dienst verwenden, um Informationen in Cloud Operations zu 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.
}

Aktive Nutzertasten

Mit temporären aktiven Nutzerschlüsseln lassen sich eindeutige Nutzer in Cloud-Logeinträgen auf einfache Weise erkennen, ohne die Identitäten dieser Nutzer preiszugeben. Schlüssel sind pro Skript und ändern sich etwa einmal im Monat, um zusätzliche Sicherheit zu bieten, falls ein Nutzer seine Identität gegenüber einem Entwickler offenbart, z. B. beim Melden eines Problems.

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

• Sie müssen nichts in Ihre Protokollierung aufnehmen, da sie bereits vorhanden sind.
• Sie erfordern keine Nutzerautorisierung.
• Sie schützen die Privatsphäre der Nutzer.

Wenn Sie temporäre aktive Nutzersicherheitsschlüssel in Ihren Cloud-Logeinträgen finden möchten, sehen Sie sich Ihre Cloud-Logs in der Google Cloud Console an. Das ist nur möglich, wenn in Ihrem Skriptprojekt ein standardmäßiges Google Cloud-Projekt verwendet wird, auf das Sie Zugriff haben. Nachdem Sie das Google Cloud-Projekt in der Console geöffnet haben, wählen Sie einen relevanten Logeintrag aus und maximieren Sie ihn, um metadata > labels > script.googleapis.com/user_key aufzurufen.

Sie können den temporären Schlüssel für aktive Nutzer auch abrufen, indem Sie Session.getTemporaryActiveUserKey() in Ihrem Script aufrufen. Eine Möglichkeit, diese Methode zu verwenden, besteht darin, dem Nutzer den Schlüssel anzuzeigen, während er Ihr Skript ausführt. Nutzer können dann ihre Schlüssel angeben, wenn sie Probleme melden, damit Sie die relevanten Logs leichter finden.

Ausnahme-Logging

Beim Protokollieren von Ausnahmen werden nicht behandelte Ausnahmen in Ihrem Skriptprojektcode zusammen mit einem Stacktrace an Cloud Logging gesendet.

So rufen Sie Ausnahme-Logs 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. Markieren Sie die Kästchen Fehlgeschlagen und Zeitüberschreitung.

Sie können protokollierte Ausnahmen auch in der GCP Console ansehen, wenn in Ihrem Skriptprojekt ein Standard-Google Cloud-Projekt verwendet wird, auf das Sie Zugriff haben.

Ausnahme-Logging aktivieren

Das Ausnahme-Logging ist für neue Projekte standardmäßig aktiviert. So aktivieren Sie die Ausnahme-Protokollierung 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 Ausnahme-Protokollierung wird automatisch in Cloud Error Reporting eingebunden. Dieser Dienst fasst die in Ihrem Skript generierten Fehler zusammen und zeigt sie an. Sie können Ihre Cloud-Fehlerberichte in der Google Cloud Console ansehen. Wenn Sie aufgefordert werden, die Fehlerberichterstattung einzurichten, liegt das daran, dass in Ihrem Skript noch keine Ausnahmen protokolliert wurden. Außer der Aktivierung des Ausnahme-Loggings ist keine Einrichtung erforderlich.

Anforderungen an die Protokollierung

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

Eine vereinfachte Version der Cloud-Logs finden Sie im Apps Script-Dashboard. Um Cloud Logging und die Fehlerberichterstattung optimal nutzen zu können, benötigen Sie jedoch Zugriff auf das GCP-Projekt des Skripts. Dies ist nur möglich, wenn in Ihrem Skriptprojekt ein standardmäßiges Google Cloud-Projekt verwendet wird.