Aufgabenlogs schreiben

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

Wenn die Protokollierung für einen Job aktiviert ist, werden Aufgabenprotokolle aus Nachrichten generiert, die die ausführbaren Elemente des Jobs während der Laufzeit drucken. Wenn Sie Ihre ausführbaren Dateien so konfigurieren, dass Aufgabenprotokolle geschrieben werden, können Sie benutzerdefinierte Informationen in Cloud Logging aufrufen. Das erleichtert die Analyse und Fehlerbehebung von Jobs. Weitere Informationen zu Protokollen finden Sie unter Jobs anhand von Protokollen analysieren.

Hinweise

  1. Wenn Sie Batch noch nicht verwendet haben, lesen Sie den Hilfeartikel Batch-Dateien erstellen und ausführen 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, der Protokolle schreibt:

    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 Aufgabenprotokollen erstellen und ausführen

Wenn Sie einen Job erstellen und ausführen möchten, für den Aufgabenprotokolle erstellt werden sollen, gehen Sie beim Erstellen des Jobs so vor:

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

  2. Fügen Sie für jedes Aufgabenprotokoll, das der Job haben soll, einen Befehl hinzu, mit dem ein Aufgabenprotokoll in ein ausführbares Programm geschrieben wird. Wenn der Job ausgeführt wird, wird jedes Mal, wenn ein Befehl zum Schreiben eines Aufgabenlogs ausgeführt wird, ein Aufgabenprotokoll generiert.

    Informationen zum Erstellen von Aufgabenprotokollen finden Sie in diesem Dokument unter Aufgabenprotokolle erstellen.

Aufgabenlogs schreiben

Ein Aufgabenprotokoll wird für alle Inhalte geschrieben, die während der Ausführung von einem Job in den Standardausgabestream (stdout) oder Standardfehlerstream (stderr) gedruckt werden. Mit dem Befehl echo können Sie beispielsweise Aufgabenprotokolle schreiben. Die Struktur des resultierenden Aufgabenlogs hängt davon ab, wie Sie die gedruckten Inhalte formatiert haben. Sie haben folgende Möglichkeiten, um jedes Aufgabenprotokoll zu erstellen:

Unstrukturiertes Protokoll schreiben, indem ein String ausgegeben wird

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

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

Beispiel für ein unstrukturiertes Protokoll

Angenommen, Sie möchten ein Aufgabenprotokoll mit dem folgenden String erstellen:

MESSAGE

Wenn Sie diesen Beispielstring drucken, wird ein Aufgabenprotokoll ausgegeben, das in etwa so aussieht:

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

Ersetzen Sie Folgendes:

  • MESSAGE: Die Nachricht, ein String, 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 drucken, z. B. indem Sie den folgenden echo-Befehl in ein ausführbares Programm einfügen:

echo MESSAGE

Ausführliche Beispiele für Jobs, bei denen mit dem Befehl echo unstrukturierte Aufgabenprotokolle geschrieben werden, finden Sie unter Einen einfachen Job erstellen und ausführen.

Strukturiertes Protokoll schreiben, indem ein JSON-Objekt ausgegeben wird

Mit strukturierten Protokollen können Sie Folgendes definieren:

Um ein strukturiertes Protokoll zu erstellen, drucken Sie ein JSON-Objekt. In den folgenden Abschnitten wird gezeigt, wie Sie ein Protokoll mit einigen Standard- und benutzerdefinierten Feldern definieren. Informationen zum Definieren eines Protokolls mit benutzerdefinierten Statusereignissen finden Sie unter Benutzerdefinierte Statusereignisse konfigurieren.

Beispiel für ein strukturiertes Protokoll

Angenommen, Sie möchten ein Aufgabenprotokoll mit den Informationen im folgenden JSON-Objekt, das eine Nachricht, eine Wichtigkeitsstufe und zwei benutzerdefinierte Felder definiert.

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

Wenn Sie dieses JSON-Objekt drucken, erhalten Sie ein Aufgabenprotokoll, das in etwa so aussieht:

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, ein String, der den Zweck des Aufgabenlogs zusammenfasst, z. B. The summary for a task log..
  • SEVERITY: die Wichtigkeitsstufe des Logs, die Sie als Filter verwenden können, wenn Sie sich Logs für einen Job ansehen. Die Schwere muss eine der LogSeverity-Enum-Werte sein, die in einen String umgewandelt wird, bei dem nur der erste Buchstabe großgeschrieben wird. Geben Sie beispielsweise für das ERROR-Enum Error an.
  • CUSTOM_FIELD_1 und CUSTOM_FIELD_2: Namen von benutzerdefinierten Feldern für das Aufgabenprotokoll, z. B. custom_field_1 und custom_field_2.
  • CUSTOM_VALUE_1 und CUSTOM_VALUE_2: Die Werte benutzerdefinierter 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.

Dieses Beispiel-JSON-Objekt lässt sich mit verschiedenen Methoden ausdrucken. In den folgenden Beispielen werden einige der möglichen Methoden zum Drucken des Beispiel-JSON-Objekts veranschaulicht:

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

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

echo-Befehl

Wenn Sie das Beispiel-JSON-Objekt mit dem Befehl echo und einem entsprechenden String drucken möchten, fügen Sie den folgenden Befehl in ein ausführbares Programm 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 Element 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 Aufgabenprotokoll 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 ausdrucken 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 Element 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 Aufgabenprotokoll 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