Aufgabenlogs schreiben

In diesem Dokument wird beschrieben, wie Sie Aufgabenlogs schreiben und einen Batchjob mit Aufgabenlogs erstellen und ausführen.

Wenn die Protokollierung für einen Job aktiviert ist, werden Aufgabenlogs aus Nachrichten generiert, die die Runnables des Jobs während der Laufzeit ausgeben. Wenn Sie Ihre Runnables so konfigurieren, dass sie Aufgabenlogs schreiben, können Sie benutzerdefinierte Informationen in Cloud Logging anzeigen lassen. Das kann die Analyse und Fehlerbehebung Ihrer Jobs erleichtern. Weitere Informationen zu Logs finden Sie unter Job mithilfe von Logs analysieren.

Hinweise

  1. Wenn Sie Batch noch nicht verwendet haben, lesen Sie den Abschnitt Erste Schritte mit Batch und aktivieren Sie Batch, indem Sie die Voraussetzungen für Projekte und Nutzer erfüllen.

  2. Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Jobs benötigen, mit dem Protokolle geschrieben werden:

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Job mit Aufgabenlogs erstellen und ausführen

Wenn Sie einen Job erstellen und ausführen möchten, für den Sie Aufgabenlogs benötigen, gehen Sie beim Erstellen des Jobs so vor:

  1. Aktivieren Sie Logs für den Job. Dadurch können alle für den Job geschriebenen Logs generiert werden.

  2. Fügen Sie für jedes Aufgabenlog, das der Job haben soll, einen Befehl hinzu, der ein Aufgabenlog in ein ausführbares Element schreibt. Wenn der Job ausgeführt wird, wird ein Aufgabenlog generiert, sobald ein Befehl zum Schreiben eines Aufgabenlogs ausgeführt wird.

    Informationen zum Schreiben von Aufgabenlogs finden Sie in diesem Dokument unter Aufgabenlogs schreiben.

Aufgabenlogs schreiben

Für alle Inhalte, die von den Runnables eines Jobs während der Laufzeit in den Standardausgabe- (stdout) oder Standardfehlerstream (stderr) geschrieben werden, wird ein Aufgabenlog erstellt. Sie können beispielsweise Aufgabenlogs mit dem Befehl echo schreiben. Die Struktur des resultierenden Aufgabenprotokolls hängt davon ab, wie Sie die gedruckten Inhalte formatiert haben. Sie haben folgende Möglichkeiten, um die einzelnen Aufgabenlogs zu schreiben:

Unstrukturiertes Log durch Ausgeben eines Strings schreiben

Bei unstrukturierten Logs können Sie eine Nachricht definieren. Das ist ein String, der im Feld textPayload des Logs angezeigt wird.

Wenn Sie ein unstrukturiertes Log schreiben möchten, geben Sie einen unformatierten String aus, wie in den folgenden Abschnitten gezeigt.

Beispiel für ein unstrukturiertes Log

Angenommen, Sie möchten ein Aufgabenlog, das den folgenden String enthält:

MESSAGE

Wenn Sie diesen Beispielstring ausgeben, erhalten Sie ein Aufgabenlog, das dem folgenden ähnelt:

insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...

Ersetzen Sie Folgendes:

  • MESSAGE: Die Nachricht, die ein String ist, der den Zweck des Aufgabenlogs zusammenfasst, z. B. The summary for a task log..
  • PROJECT_ID: die Projekt-ID Ihres Projekts.

Sie können einen String mit verschiedenen Methoden ausgeben, z. B. indem Sie den folgenden echo-Befehl in ein Runnable einfügen:

echo MESSAGE

Umfassende Beispiele für Jobs, in denen mit dem Befehl echo unstrukturierte Aufgabenlogs geschrieben werden, finden Sie unter Einfachen Job erstellen und ausführen.

Strukturierte Logs schreiben, indem Sie ein JSON-Objekt ausgeben

Mit strukturierten Logs können Sie Folgendes definieren:

Wenn Sie ein strukturiertes Log schreiben möchten, geben Sie ein JSON-Objekt aus. In den folgenden Abschnitten wird gezeigt, wie ein Log mit einigen Standardfeldern und benutzerdefinierten Feldern definiert wird. Informationen zum Definieren eines Logs mit benutzerdefinierten Statusereignissen finden Sie auch unter Benutzerdefinierte Statusereignisse konfigurieren.

Beispiel für ein strukturiertes Log

Angenommen, Sie möchten ein Aufgabenlog, das die Informationen im folgenden JSON-Objekt enthält. Dieses definiert eine Nachricht, eine Wichtigkeitsstufe und zwei benutzerdefinierte Felder.

{
  "message": "MESSAGE"
  "severity": "SEVERITY"
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
}

Wenn Sie dieses JSON-Objekt ausgeben, erhalten Sie ein Aufgabenlog, das dem folgenden ähnelt:

insertId: ...
jsonPayload:
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
  message: MESSAGE
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: SEVERITY
timestamp: ...

Ersetzen Sie Folgendes:

  • MESSAGE: Die Nachricht, die ein String ist, der den Zweck des Aufgabenlogs zusammenfasst, z. B. The summary for a task log..
  • SEVERITY: Der Schweregrad des Logs, den Sie als Filter verwenden können, wenn Sie Logs für einen Job aufrufen. Der Schweregrad muss einer der LogSeverity-Enums entsprechen, die in einen String mit nur dem ersten Buchstaben in Großbuchstaben konvertiert werden. Geben Sie beispielsweise für die ERROR-Enumeration Error an.
  • CUSTOM_FIELD_1 und CUSTOM_FIELD_2: die Namen der benutzerdefinierten Felder für das Aufgabenlogbuch, z. B. custom_field_1 und custom_field_2.
  • CUSTOM_VALUE_1 und CUSTOM_VALUE_2: Die Werte der benutzerdefinierten Felder für das Aufgabenprotokoll. Sie können verschiedene Datentypen haben und möglicherweise Anführungszeichen erfordern, z. B. "the first custom field" und 2.
  • PROJECT_ID: die Projekt-ID Ihres Projekts.

Sie können dieses Beispiel-JSON-Objekt mit verschiedenen Methoden ausgeben. In den folgenden Beispielen werden einige der möglichen Methoden zum Ausgeben des Beispiel-JSON-Objekts gezeigt:

  • Geben Sie mit dem Befehl echo einen entsprechenden String aus.

  • Geben Sie ein entsprechendes Wörterbuch mit Python aus.

echo-Befehl

Wenn Sie das Beispiel-JSON-Objekt mit dem Befehl echo und einem entsprechenden String ausgeben möchten, fügen Sie den folgenden Befehl in einen ausführbaren Code ein:

echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'

Angenommen, Sie erstellen und führen einen Job mit dem folgenden ausführbaren Code aus:

"script": {
  "text": "echo '{\"message\":\"The message for a structured log.\", \"severity\":\"Error\", \"custom_field_1\":\"the first custom field\", \"custom_field_2\":2}'"
}

Das resultierende Aufgabenlog sieht dann in etwa so aus:

insertId: ...
jsonPayload:
  custom_field_1: the first custom field
  custom_field_2: 2
  message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...

Python

Wenn Sie das Beispiel-JSON-Objekt mit Python und einem entsprechenden Dictionary ausgeben möchten, fügen Sie das folgende Beispiel in ein ausführbares Programm ein:

#!/usr/bin/env python3

import json

entry = dict(
    severity="SEVERITY",
    message="MESSAGE",
    CUSTOM_FIELD_1=CUSTOM_VALUE_1,
    CUSTOM_FIELD_2=CUSTOM_VALUE_2,
)
print(json.dumps(entry))

Angenommen, Sie erstellen und führen einen Job mit dem folgenden ausführbaren Code aus:

"script": {
  "text": "#!/usr/bin/env python3\n\nimport json\n\nentry = dict(\nseverity=\"Error\",\nmessage=\"The summary for a structured task log with error severity.\",\ncustom_field_1=\"the first custom field\",\ncustom_field_2=2,\n)\nprint(json.dumps(entry))"
}

Das resultierende Aufgabenlog sieht dann in etwa so aus:

insertId: ...
jsonPayload:
  custom_field_1: the first custom field
  custom_field_2: 2
  message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...

Nächste Schritte