Logging

Bei der Entwicklung von Apps werden Loginformationen verwendet, 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 Protokoll ist ressourcenschonend und wird in Echtzeit gestreamt, bleibt aber nur kurze Zeit erhalten.
Die Cloud Logging-Oberfläche in der Developer Console, die Protokolle bereitstellt, die viele Tage nach ihrer Erstellung gespeichert bleiben.
Die Error Reporting-Oberfläche in der Developer Console, die Fehler erfasst und aufzeichnet, die während der Ausführung des 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 ein Logging Tabellenblatt oder eine JDBC-Datenbank geschrieben werden.

Apps Script-Ausführungsprotokoll verwenden

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

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

Diese Protokolle sind für Prüfungen während der Entwicklung und des Debuggings vorgesehen und bleiben nicht sehr lange erhalten.

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}`);
  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 Protokolle 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 Cloud Logging-Dienst. Wenn Sie Protokolle benötigen, die mehrere Tage lang gespeichert bleiben, oder eine komplexere Logging-Lösung für eine Produktionsumgebung mit mehreren Nutzern benötigen, ist Cloud Logging die bessere Wahl. Unter Kontingente und Limits für Cloud Logging finden Sie Informationen zur Datenaufbewahrung und weitere Details zu Kontingenten.

Wenn Sie ein höheres Logging-Kontingent anfordern möchten, senden Sie eine Google Cloud-Kontingentanfrage. Dazu benötigen Sie Zugriff auf das Cloud Platform-Projekt, das von Ihrem Skript verwendet wird.

Cloud Logging bietet neben dem Speichern von Protokollen eine Reihe weiterer Dienste wie Benachrichtigungen und Messwerte. Diese Dienste sind in Apps Script nicht verfügbar.

Cloud Logging verwenden

Cloud-Protokolle werden dem Google Cloud-Projekt zugeordnet, das mit Ihrem Apps Script verknüpft ist. Eine vereinfachte Version von diesen Protokollen finden Sie im Apps Script-Dashboard.

Wenn Sie Cloud Logging und seine Funktionen vollständig nutzen möchten, verwenden Sie ein Standard-Google Cloud-Projekt mit Ihrem Skriptprojekt. So können Sie direkt in der Google Cloud Console auf Cloud-Protokolle zugreifen und haben mehr Optionen zum Anzeigen und Filtern.

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

Beim Logging sollten Sie keine personenbezogenen Daten des Nutzers wie E-Mail-Adressen aufzeichnen. Cloud-Protokolle werden automatisch mit aktiven Nutzersschlüsseln gekennzeichnet, um bei Bedarf die Protokollnachrichten eines bestimmten Nutzers zu finden.

Protokollieren Sie Strings, formatierte Strings und sogar JSON-Objekte mit den Funktionen des Apps Script console Dienstes.

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 Nutzersschlüssel

Temporäre aktive Nutzersschlüssel bieten eine praktische Möglichkeit, eindeutige Nutzer in Cloud-Logeinträgen zu 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 einem Entwickler preisgibt, z. B. beim Melden eines Problems.

Temporäre aktive Nutzersschlüssel sind besser als Logging-IDs wie E-Mail-Adressen, weil:

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

Temporäre aktive Nutzersschlüssel in Ihren Cloud-Logeinträgen finden Sie in der Google Cloud Console. Tun Sie dies nur, wenn Ihr Skriptprojekt ein Standard-Google Cloud-Projekt verwendet, 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 Metadaten > Labels > script.googleapis.com/user_key aufzurufen.

Rufen Sie Session.getTemporaryActiveUserKey in Ihrem Skript auf, um den temporären aktiven Nutzersschlüssel 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 Protokolle leichter finden.

Ausnahme-Logging

Beim Ausnahme-Logging werden nicht behandelte Ausnahmen im Code Ihres Skriptprojekts 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 Fehler und Zeitüberschreitung an.

Protokollierte Ausnahmen können Sie in der Google Cloud Console aufrufen, wenn Ihr Skriptprojekt ein Standard Google Cloud-Projekt verwendet, auf das Sie Zugriff haben.

Ausnahme-Logging aktivieren

Das Ausnahme-Logging ist für neue Projekte standardmäßig aktiviert. So aktivieren Sie das Ausnahme-Logging 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

Das Ausnahme-Logging wird automatisch in Cloud Error Reporting integriert, einem Dienst, der Fehler in Ihrem Skript zusammenfasst und anzeigt. Sie können Ihre Cloud-Fehlerberichte in der Google Cloud Console aufrufen. 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, Error Reporting einzurichten, wurden in Ihrem Skript 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ührungsprotokolls gelten keine Anforderungen.

Eine vereinfachte Version der Cloud-Protokolle finden Sie im Apps Script-Dashboard. Wenn Sie Cloud Logging und Error Reporting optimal nutzen möchten, benötigen Sie jedoch Zugriff auf das Google Cloud-Projekt des Skripts. Das ist nur möglich, wenn Ihr Skript projekt ein Standard-Google Cloud-Projekt verwendet.

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