Logging

Bei der Entwicklung von Anwendungen sollten Sie oft Informationen protokollieren, um Fehler während der Entwicklung zu erkennen, Kundenprobleme zu identifizieren und zu diagnostizieren, sowie für andere Zwecke.

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

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

• Die Schnittstelle Cloud Logging in der Developer Console. Diese bietet Logs, die viele Tage nach der Erstellung beibehalten werden.

• Die Schnittstelle Error Reporting 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 auch eigenen Logger-Code erstellen, der beispielsweise Informationen in eine Logging-Tabelle oder eine JDBC-Datenbank schreibt.

Apps Script-Ausführungsprotokoll verwenden

Ein grundlegender Ansatz für die Anmeldung in Apps Script ist die Verwendung des integrierten Ausführungslogs. Klicken Sie oben im Editor auf Ausführungslog, um diese Logs aufzurufen. Wenn Sie eine Funktion ausführen oder den Debugger verwenden, wird der Logstream in Echtzeit gestreamt.

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

Diese Logs sind für einfache Prüfungen während der Entwicklung und der Fehlerbehebung vorgesehen und bleiben nicht sehr lang.

Hier ein Beispiel:

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 an [e-mail] senden
[16-09-12 13:50:42:271 PDT] 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 das Logging mehrere Tage benötigen oder eine komplexere Logging-Lösung für eine Produktionsumgebung mit mehreren Nutzern benötigen, ist Cloud Logging die bevorzugte Wahl. Informationen zur Datenaufbewahrung und zu anderen Kontingentdetails finden Sie unter Cloud Logging-Kontingente und -Limits.

Wenn Sie ein größeres Logging-Kontingent benötigen, können Sie eine Google Cloud Platform-Kontingentanfrage einreichen. Dazu benötigen Sie Zugriff auf das Cloud Platform-Projekt, das von Ihrem Skript verwendet wird.

Hinweis: Cloud Logging bietet eine Reihe von Diensten, die über das Speichern von Logs hinausgehen, z. B. Benachrichtigungen und Messwerte. Derzeit sind diese Dienste nicht in Apps Script verfügbar.

Cloud Logging verwenden

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

Um die Vorteile von Cloud Logging und seinen Funktionen voll auszuschöpfen, verwenden Sie für Ihr Skriptprojekt ein Google Cloud-Standardprojekt. So können Sie direkt in der GCP Console auf Cloud-Logs zugreifen und haben mehr Optionen zum Ansehen und Filtern.

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

Bei der Protokollierung ist es ratsam, keine personenbezogenen Daten wie E-Mail-Adressen zu erfassen. Cloud-Logs werden automatisch mit aktiven Nutzerschlüsseln gekennzeichnet, anhand derer Sie bei Bedarf die Lognachrichten eines bestimmten Nutzers suchen können.

Mit den Funktionen des Apps Script-Diensts 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 Log-Einträgen zu erkennen, ohne die Identität dieser Nutzer offenzulegen. Schlüssel gelten pro Skript und ändern sich etwa einmal im Monat, um die Sicherheit zu erhöhen, wenn ein Nutzer seine Identität beispielsweise einem Entwickler preisgibt.

Temporäre aktive Nutzerschlüssel sind den Logging-IDs wie E-Mail-Adressen überlegen, weil:

• Sie müssen Ihrem Logging nichts hinzufügen. Die Elemente sind bereits vorhanden.
• Es ist keine Nutzerautorisierung erforderlich.
• Sie schützen die Privatsphäre der Nutzer.

Informationen dazu, wie Sie vorübergehend aktive Nutzerschlüssel in Ihren Cloud Log-Einträgen finden, finden Sie in der Google Cloud Console. Dies ist nur möglich, wenn Ihr Skriptprojekt ein Google Cloud-Standardprojekt verwendet, auf das Sie Zugriff haben. Öffnen Sie das Google Cloud-Projekt in der Console und wählen Sie den gewünschten Logeintrag aus und maximieren Sie ihn, um Metadaten > Labels > Script.googleapis.com/user_key aufzurufen.

Sie können den temporären aktiven Nutzerschlüssel auch abrufen, indem Sie in Ihrem Skript Session.getTemporaryActiveUserKey() aufrufen. Bei dieser Methode kann dem Nutzer während der Ausführung des Skripts der Schlüssel angezeigt werden. Dann können Nutzer ihre Schlüssel beim Melden von Problemen angeben, um die entsprechenden Logs leichter identifizieren zu können.

Ausnahme-Logging

Es werden unbearbeitete Ausnahmen in Ihrem Skriptprojektcode zusammen mit einem Stacktrace an Cloud Logging gesendet.

So rufen Sie Ausnahmelogs 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 logierte Ausnahmen auch in der GCP Console ansehen, wenn Ihr Skriptprojekt ein Google Cloud-Standardprojekt verwendet, auf das Sie Zugriff haben.

Ausnahme-Logging aktivieren

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

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

Error Reporting

Ausnahme-Logging wird automatisch in Cloud Error Reporting eingebunden, einen Dienst, der die in Ihrem Skript generierten Fehler aggregiert und anzeigt. Sie können Ihre Cloud-Fehlerberichte in der Google Cloud Console ansehen. Wenn Sie aufgefordert werden, Error Reporting einzurichten, liegt das daran, dass Ihr Skript noch keine Ausnahmen protokolliert hat. Nach dem Aktivieren des Ausnahme-Loggings ist keine Einrichtung erforderlich.

Logging-Anforderungen

Sie müssen nicht das integrierte Ausführungsprotokoll verwenden.

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