Aufgabenlogs schreiben

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

Wenn das Logging für einen Job aktiviert ist, werden Aufgabenlogs aus Nachrichten generiert, die von den ausführbaren Einheiten des Jobs während der Laufzeit ausgegeben werden. Wenn Sie Ihre ausführbaren Einheiten so konfigurieren, dass sie Aufgabenlogs schreiben, können Sie benutzerdefinierte Informationen in Cloud Logging anzeigen lassen. So lassen sich Ihre Jobs einfacher analysieren und Fehler beheben. Weitere Informationen zu Logs finden Sie unter Jobs mit Logs analysieren.

Hinweis

  1. Wenn Sie Batch noch nicht verwendet haben, lesen Sie den Artikel Erste Schritte mit Batch und aktivieren Sie Batch, indem Sie die Voraussetzungen für Projekte und Nutzererfü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 Logs 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 Aufgabenlogs erstellen und ausführen

Wenn Sie einen Job mit Aufgabenlogs erstellen und ausführen möchten, gehen Sie so vor, wenn Sie den Job erstellen:

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

  2. Fügen Sie für jedes Aufgabenlog, das der Job haben soll, einer ausführbaren Einheit einen Befehl hinzu, der ein Aufgabenlog schreibt. Wenn der Job ausgeführt wird, wird immer dann ein Aufgabenlog generiert, wenn ein Befehl zum Schreiben eines Aufgabenlogs ausgeführt wird.

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

Aufgabenlogs schreiben

Ein Aufgabenlog wird für alle Inhalte geschrieben, die von den ausführbaren Einheiten eines Jobs während der Laufzeit in den Standardausgabestream (stdout) oder den Standardfehlerstream (stderr) ausgegeben werden. Sie können Aufgabenlogs beispielsweise mit dem echo Befehl schreiben. Die Struktur des resultierenden Aufgabenlogs variiert je nachdem, wie Sie den ausgegebenen Inhalt formatiert haben. Sie können jedes Aufgabenlog mit einer der folgenden Optionen schreiben:

Unstrukturiertes Log schreiben, indem Sie einen String ausgeben

Mit 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, 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 ausgeben, z. B. indem Sie den folgenden echo-Befehl in eine ausführbare Einheit einfügen:

echo MESSAGE

Umfassende Beispiele für Jobs, die den echo Befehl verwenden, um unstrukturierte Aufgabenlogs zu schreiben, finden Sie unter Einfachen Job erstellen und ausführen.

Strukturiertes Log 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 Sie ein Log mit einigen Standardfeldern und benutzerdefinierten Feldern definieren. Informationen zum Definieren eines Logs mit benutzerdefinierten Statusereignissen finden Sie 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, einen Schweregrad 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, ein String, 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 ansehen. Der Schweregrad muss einer der LogSeverity Enums sein, die in einen String konvertiert wurden, wobei nur der erste Buchstabe großgeschrieben wird. Geben Sie beispielsweise für die ERROR-Enum Error an.
  • CUSTOM_FIELD_1 und CUSTOM_FIELD_2: die Namen der benutzerdefinierten Felder für das Aufgabenlog, z. B. custom_field_1 und custom_field_2.
  • CUSTOM_VALUE_1 und CUSTOM_VALUE_2: die Werte der benutzerdefinierten Felder für das Aufgabenlog. Das können verschiedene Datentypen sein und möglicherweise sind Anführungszeichen erforderlich, 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. Die folgenden Beispiele zeigen einige der möglichen Methoden zum Ausgeben des Beispiel-JSON-Objekts:

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

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

Befehl „echo“

Wenn Sie das Beispiel-JSON-Objekt mit dem Befehl echo und einem entsprechenden String ausgeben möchten, fügen Sie den folgenden Befehl in eine ausführbare Einheit 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 der folgenden ausführbaren Einheit aus:

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

Dann sieht das resultierende Aufgabenlog 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 Wörterbuch ausgeben möchten, fügen Sie das folgende Beispiel in eine ausführbare Einheit 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 der folgenden ausführbaren Einheit 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))"
}

Dann sieht das resultierende Aufgabenlog 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