Logging

Bei der Entwicklung von Apps jeglicher Art sollten Sie Log-Informationen verwenden, um Fehler während der Entwicklung zu diagnostizieren, Kundenprobleme zu identifizieren und zu diagnostizieren und für andere Zwecke.

Google 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 Developer Console, die Logs bereitstellt, die viele Tage nach ihrer Erstellung bestehen bleiben.
Die Error Reporting-Oberflä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 eigenen Logger-Code erstellen, mit dem beispielsweise Informationen in eine Tabelle oder JDBC-Datenbank geschrieben werden.

Apps Script-Ausführungsprotokoll verwenden

Ein grundlegender Ansatz zum 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.

Verwenden Sie entweder die Logging-Dienste Logger oder console im integrierten Ausführungsprotokoll.

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

Betrachten Sie beispielsweise die folgende 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}`);
  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);
}

Wenn dieses Skript mit den Eingaben „2“ und „john@example.com“ ausgeführt wird, werden die folgenden Logs geschrieben:

> [16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
> [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-Dienst Cloud Logging. Wenn Sie Protokollierung benötigen, die mehrere Tage lang bestehen bleibt, oder eine komplexere Protokollierungslösung für eine Produktionsumgebung mit mehreren Nutzern, ist Cloud Logging die bevorzugte Wahl. Weitere Informationen zur Datenaufbewahrung und zu anderen Kontingentdetails finden Sie unter Cloud Logging-Kontingente und -Limits.

Wenn Sie ein höheres Kontingent für das Logging anfordern möchten, reichen Sie einen Google Cloud-Kontingentantrag ein. Dazu benötigen Sie Zugriff auf das Cloud Platform-Projekt, das von Ihrem Skript verwendet wird.

Cloud Logging bietet neben der Speicherung von Logs auch eine Reihe weiterer Dienste, z. B. Benachrichtigungen und Messwerte. Diese Dienste sind 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 vollständig nutzen möchten, verwenden Sie ein standardmäßiges Google Cloud-Projekt mit Ihrem Script-Projekt. So können Sie direkt in der Google Cloud Console auf Cloud-Logs zugreifen und haben mehr Anzeige- und Filteroptionen.

Wenn Sie die Rhino-Laufzeit verwenden, wird der Apps Script-Dienst Logger nicht von Cloud Logging 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, um bei Bedarf die Log-Nachrichten eines bestimmten Nutzers zu finden.

Mit den Funktionen des Apps Script-Dienstes console können Sie Log-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

/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * 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 Nutzerschlüssel

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 Script 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 – die Informationen sind bereits vorhanden.
Sie erfordern keine Nutzerautorisierung.
Sie schützen die Privatsphäre der Nutzer.

Wenn Sie temporäre aktive Nutzerschlüssel in Ihren Cloud-Logeinträgen finden möchten, sehen Sie sich Ihre Cloud-Logs in der Google Cloud Console an. Führen Sie diesen Schritt nur aus, wenn in Ihrem Skriptprojekt 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 relevanten Logeintrag aus und maximieren Sie ihn, um metadata > labels > script.googleapis.com/user_key aufzurufen.

Rufen Sie Session.getTemporaryActiveUserKey in Ihrem Skript auf, um den temporären Schlüssel für aktive Nutzer zu erhalten. Eine Möglichkeit, diese Methode zu verwenden, besteht darin, den Schlüssel dem Nutzer 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 Exception-Logging werden nicht behandelte Ausnahmen in Ihrem Skriptprojektcode zusammen mit einem Stacktrace an Cloud Logging gesendet.

So rufen Sie Ausnahme-Logs auf:

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

Wenn Ihr Skriptprojekt ein Standard-Google Cloud-Projekt verwendet, auf das Sie Zugriff haben, können Sie protokollierte Ausnahmen in der Google Cloud Console ansehen.

Ausnahme-Logging aktivieren

Das Ausnahme-Logging ist für neue Projekte standardmäßig aktiviert. So aktivieren Sie die Ausnahme-Protokollierung für ältere Projekte:

Öffnen Sie das Skriptprojekt.
Klicken Sie links auf Projekteinstellungen .
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 Fehler, die in Ihrem Skript auftreten, zusammen und zeigt sie an. Sie können Ihre Cloud-Fehlerberichte in der Google Cloud Console ansehen. Sie müssen Error Reporting nicht manuell konfigurieren oder Trace-Einträge erstellen. Apps Script füllt die erforderlichen Felder automatisch aus, wenn eine Ausnahme ausgelöst wird oder wenn Sie console.error mit einem Error-Objekt verwenden. 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 Google Cloud-Projekt des Skripts. Das ist nur möglich, wenn in Ihrem Scriptprojekt ein Google Cloud-Standardprojekt verwendet wird.

Logging Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.