Logging

Bei der Entwicklung von Anwendungen möchten Sie häufig Informationen protokollieren, um Fehler während der Entwicklung zu diagnostizieren, um Kundenprobleme zu identifizieren und zu diagnostizieren und für andere Zwecke.

Apps Script bietet drei verschiedene Mechanismen für die Protokollierung:

• Integriertes Apps Script-Ausführungsprotokoll Dieses Log ist schlank und streamt in Echtzeit, bleibt aber nur für kurze Zeit bestehen.

• Die Cloud Logging-Schnittstelle in der Developer Console, die Logs enthält, die nach ihrer Erstellung viele Tage lang bestehen bleiben.

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

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

Apps Script-Ausführungsprotokoll verwenden

Ein grundlegender Ansatz für die Protokollierung in Apps Script ist die Verwendung des integrierten Ausführungslogs. Klicken Sie zum Aufrufen dieser Logs oben im Editor auf Ausführungslog. Wenn Sie eine Funktion ausführen oder den Debugger verwenden, werden die Logs in Echtzeit gestreamt.

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

Diese Logs sind für einfache Prüfungen während der Entwicklung und Fehlerbehebung gedacht und werden nicht 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 Logs geschrieben:

[16-09-12 13:50:42:193 PDT] Datenzeile 2 wird per E-Mail an [e-mail] gesendet
[16-09-12 13:50:42:271 PDT] Daten aus Zeile 2: Kosten 103,24

Cloud Logging

Apps Script bietet auch teilweisen Zugriff auf den Dienst Cloud Logging der Google Cloud Platform (GCP). Wenn Sie ein Logging benötigen, das mehrere Tage lang bestehen bleibt, oder eine komplexere Logging-Lösung für eine Produktionsumgebung mit mehreren Nutzern benötigen, ist Cloud Logging die bevorzugte Wahl. Weitere Informationen zur Datenaufbewahrung und andere 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 Skript verwendet.

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

Cloud Logging verwenden

Cloud-Logs werden an das Google Cloud-Projekt angehängt, das Ihrem Apps Script zugeordnet ist. Eine vereinfachte Version dieser Logs finden Sie im Apps Script-Dashboard.

Verwenden Sie ein Google Cloud-Standardprojekt mit Ihrem Skriptprojekt, um Cloud Logging und dessen Funktionen optimal zu nutzen. So können Sie direkt in der GCP Console auf Cloud-Logs zugreifen und erhalten mehr Anzeige- und Filteroptionen.

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

Beim Logging sollten keine personenbezogenen Daten wie E-Mail-Adressen über den Nutzer aufgezeichnet werden. Cloud-Logs werden automatisch mit aktiven Nutzerschlüsseln beschriftet, mit denen Sie bei Bedarf die Lognachrichten eines bestimmten Nutzers suchen können.

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

Das folgende Beispiel zeigt, 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.
}

Aktive Nutzerschlüssel

Temporäre aktive Nutzerschlüssel bieten eine bequeme Möglichkeit, einzelne Nutzer in Cloud-Logeinträgen zu erkennen, ohne die Identität dieser Nutzer offenzulegen. Schlüssel werden pro Skript erstellt und ändern sich etwa einmal im Monat, um für zusätzliche Sicherheit zu sorgen, wenn ein Nutzer seine Identität gegenüber einem Entwickler preisgibt, z. B. beim Melden eines Problems.

Temporäre aktive Nutzerschlüssel sind Logging-IDs wie E-Mail-Adressen aus folgenden Gründen überlegen:

• Sie müssen nichts zu Ihrem Protokoll hinzufügen, sie 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, rufen Sie Ihre Cloud-Logs in der Google Cloud Console auf. Dies ist nur möglich, wenn Ihr Skriptprojekt ein Google Cloud-Standardprojekt verwendet, auf das Sie Zugriff haben. Wählen Sie nach dem Öffnen des Google Cloud-Projekts in der Console einen relevanten Logeintrag aus und maximieren Sie ihn. Dann sehen Sie metadata > Labels > script.googleapis.com/user_key.

Sie können den temporären aktiven Nutzerschlüssel auch abrufen, indem Sie in Ihrem Skript Session.getTemporaryActiveUserKey() aufrufen. Eine Möglichkeit, diese Methode zu verwenden, besteht darin, dem Nutzer den Schlüssel anzuzeigen, während er Ihr Skript ausführt. Die Nutzer können dann ihre Schlüssel in das Melden von Problemen aufnehmen, um Ihnen die Identifizierung der relevanten Logs zu erleichtern.

Ausnahmeprotokollierung

Beim Ausnahme-Logging werden unbehandelte Ausnahmen in Ihrem Skriptprojektcode zusammen mit einem Stacktrace 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 die geloggten Ausnahmen auch in der GCP Console ansehen, wenn Ihr Skriptprojekt ein Google Cloud-Standardprojekt verwendet, auf das Sie Zugriff haben.

Ausnahme-Logging aktivieren

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

1. Öffnen Sie das Skriptprojekt.
2. Klicken Sie links auf Projekteinstellungen .
3. Klicken Sie das Kästchen Nicht erfasste Ausnahmen in Cloud-Vorgänge protokollieren an.

Fehlerberichte

Das Ausnahme-Logging ist automatisch in Cloud Error Reporting eingebunden. Cloud Error Reporting ist ein Dienst, mit dem die im Script generierten Fehler zusammengefasst und angezeigt werden. Sie können Ihre Cloud-Fehlerberichte in der Google Cloud Console ansehen. Wenn Sie aufgefordert werden, Error Reporting einzurichten, liegt dies daran, dass von Ihrem Skript noch keine Ausnahmen protokolliert wurden. Außer dem Aktivieren des Ausnahme-Loggings ist keine weitere Einrichtung erforderlich.

Logging-Anforderungen

Für die Verwendung des integrierten Ausführungslogs sind keine Anforderungen zu erfüllen.

Eine vereinfachte Version von Cloud-Logs finden Sie im Apps Script-Dashboard. Damit Sie Cloud Logging und Error Reporting optimal nutzen können, benötigen Sie jedoch Zugriff auf das GCP-Projekt des Skripts. Dies ist nur möglich, wenn Ihr Skriptprojekt ein Google Cloud-Standardprojekt verwendet.