In diesem Dokument wird beschrieben, wie Sie benutzerdefinierte Statusereignisse konfigurieren, die die Runnables eines Jobs beschreiben, wenn Sie einen Batch-Job erstellen und ausführen. Weitere Informationen zu Statusereignissen finden Sie unter Jobverlauf über Statusereignisse ansehen.
Mit benutzerdefinierten Statusereignissen können Sie dem Aufgabenverlauf zusätzliche Details zum Fortschritt der Runnables hinzufügen. Das kann die Analyse und Fehlerbehebung eines Jobs erleichtern. Sie können beispielsweise benutzerdefinierte Statusereignisse konfigurieren, die beschreiben, wann ein Runnable beginnt, wann es endet, wann ein Barrier-Runnable erreicht wird oder wann während des Fortschritts Ihres Codes ein wichtiges Ereignis eintritt.
Hinweise
- 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.
-
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen eines Jobs benötigen:
-
Batch-Job-Editor (
roles/batch.jobsEditor
) für das Projekt -
Dienstkontonutzer (
roles/iam.serviceAccountUser
) für das Dienstkonto des Jobs, das standardmäßig das Compute Engine-Standarddienstkonto ist
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.
-
Batch-Job-Editor (
Benutzerdefinierte Statusereignisse konfigurieren
Sie können benutzerdefinierte Statusereignisse konfigurieren, indem Sie beim Erstellen eines Jobs eine oder mehrere der folgenden Optionen verwenden:
Status eines ausführbaren Programms beschreiben: Definieren Sie den Anzeigenamen. Sie können dies tun, wenn Sie einen Job mit der gcloud CLI oder der Batch API erstellen.
Wichtige Laufzeitereignisse angeben, indem Sie für jedes Ereignis ein strukturiertes Aufgabenlog mit dem Feld
batch/custom/event
schreiben. Das ist bei jeder Methode zum Erstellen eines Jobs im Rahmen der Definitionen von ausführbaren Skripts und Containern möglich.
Status eines ausführbaren Programms beschreiben
Sie können benutzerdefinierte Statusereignisse konfigurieren, die den Status eines Runnable beschreiben, indem Sie den Anzeigenamen eines Runnable definieren (Feld displayName
).
Die resultierenden benutzerdefinierten Statusereignisse variieren je nach Art der ausführbaren Datei:
Wenn Sie einen Anzeigenamen für ein Container-Runnable oder Script-Runnable definieren, fügt Batch automatisch zwei Arten von benutzerdefinierten Statusereignissen hinzu. Das erste benutzerdefinierte Statusereignis gibt an, wann eine Aufgabe diesen Runnable startet. Das zweite benutzerdefinierte Statusereignis gibt an, wann eine Aufgabe in diesem Runnable abgeschlossen wird, und den entsprechenden Beendigungscode.
Wenn Sie einen Anzeigenamen für eine BarrierRunnable definieren, fügt Batch automatisch ein benutzerdefiniertes Statusereignis hinzu, das angibt, wann eine Aufgabe diese Barriere erreicht.
Wenn Sie einen Job mit benutzerdefinierten Statusereignissen erstellen und ausführen möchten, die den Status eines ausführbaren Elements beschreiben, definieren Sie das Feld displayName
für ein oder mehrere ausführbare Elemente mit der gcloud CLI, der Batch API oder der Bibliothek.
gcloud
Verwenden Sie die Google Cloud CLI, um einen Job zu erstellen, der das Feld displayName
in einer oder mehreren runnables
-Definitionen in der JSON-Datei enthält:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
Ein Job mit benutzerdefinierten Statusereignissen, der den Status jedes ausführbaren Elements beschreibt, kann beispielsweise eine JSON-Konfigurationsdatei haben, die der folgenden ähnelt:
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"displayName":"DISPLAY_NAME1",
"script": {
"text": "echo Hello world from script 1 for task ${BATCH_TASK_INDEX}"
}
},
{
"displayName":"DISPLAY_NAME2",
"barrier": {}
},
{
"displayName":"DISPLAY_NAME3",
"script": {
"text": "echo Hello world from script 2 for task ${BATCH_TASK_INDEX}"
}
}
]
},
"taskCount": 3
}
],
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
}
Ersetzen Sie DISPLAY_NAME1
, DISPLAY_NAME2
und DISPLAY_NAME3
durch den Namen des ausführbaren Programms, der innerhalb des Jobs eindeutig sein muss, z. B. script 1
, barrier 1
und script 2
.
API
Verwenden Sie die REST API, um einen Job zu erstellen, der das Feld displayName
in einer oder mehreren runnables
-Definitionen in der JSON-Datei enthält:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
Ein Job mit benutzerdefinierten Statusereignissen, der den Status jedes ausführbaren Elements beschreibt, kann beispielsweise eine JSON-Konfigurationsdatei haben, die der folgenden ähnelt:
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"displayName":"DISPLAY_NAME1",
"script": {
"text": "echo Hello world from script 1 for task ${BATCH_TASK_INDEX}"
}
},
{
"displayName":"DISPLAY_NAME2",
"barrier": {}
},
{
"displayName":"DISPLAY_NAME3",
"script": {
"text": "echo Hello world from script 2 for task ${BATCH_TASK_INDEX}"
}
}
]
},
"taskCount": 3
}
],
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
}
Ersetzen Sie DISPLAY_NAME1
, DISPLAY_NAME2
und DISPLAY_NAME3
durch den Namen des ausführbaren Programms, der innerhalb des Jobs eindeutig sein muss, z. B. script 1
, barrier 1
und script 2
.
Go
Java
Node.js
Python
Nachdem der Beispieljob ausgeführt wurde, sehen die resultierenden benutzerdefinierten Statusereignisse für die einzelnen Aufgaben in etwa so aus:
statusEvents:
...
- description: 'script at index #0 with display name [DISPLAY_NAME1] started.'
eventTime: '...'
type: RUNNABLE_EVENT
- description: 'script at index #0 with display name [DISPLAY_NAME1] finished with exit
code 0.'
eventTime: '...'
type: RUNNABLE_EVENT
- description: 'barrier at index #2 with display name [DISPLAY_NAME2] reached.'
eventTime: '...'
type: BARRIER_REACHED_EVENT
- description: 'script at index #2 with display name [DISPLAY_NAME3] started.'
eventTime: '...'
type: RUNNABLE_EVENT
- description: 'script at index #2 with display name [DISPLAY_NAME3] finished with exit
code 0.'
eventTime: '...'
type: RUNNABLE_EVENT
...
Wichtige Laufzeitereignisse angeben
Sie können benutzerdefinierte Statusereignisse konfigurieren, die angeben, wann ein wichtiges Ereignis eintritt, während ein Runnable ausgeführt wird. Dazu konfigurieren Sie das Runnable so, dass ein strukturiertes Aufgabenlog geschrieben wird, in dem ein String für das Feld „Benutzerdefiniertes Batch-Statusereignis“ (batch/custom/event
) definiert wird.
Wenn ein Container- oder Skript-Runnable ein strukturiertes Aufgabenlog schreibt, in dem das JSON-Feld batch/custom/event
definiert ist, wird zu diesem Zeitpunkt ein benutzerdefiniertes Statusereignis generiert. Sie können zwar das strukturierte Aufgabenprotokoll so konfigurieren, dass es zusätzliche Felder enthält, das benutzerdefinierte Statusereignis enthält jedoch nur den String für das Feld batch/custom/event
.
Wenn Sie einen Job mit benutzerdefinierten Statusereignissen erstellen und ausführen möchten, die angeben, wann ein wichtiges Ereignis eintritt, konfigurieren Sie ein oder mehrere Runnables so, dass ein strukturiertes Log durch Ausgeben von JSON geschrieben wird, und definieren Sie das Feld batch/custom/event
als Teil des Logs.
...
"runnables": [
{
...
"echo '{\"batch/custom/event\":\"EVENT_DESCRIPTION\"}'"
...
}
]
...
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
...
Ein Job mit benutzerdefinierten Statusereignissen, die angeben, wann ein wichtiges Ereignis eintritt, kann beispielsweise eine JSON-Konfigurationsdatei haben, die der folgenden ähnelt:
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"script": {
"text": "sleep 30; echo '{\"batch/custom/event\": \"EVENT_DESCRIPTION\"}'; sleep 30"
}
}
]
},
"taskCount": 3
}
],
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
}
Ersetzen Sie EVENT_DESCRIPTION
durch eine Beschreibung für das benutzerdefinierte Statusereignis, z. B. halfway done
.
Nachdem der Beispieljob ausgeführt wurde, sieht das resultierende benutzerdefinierte Statusereignis für jede Aufgabe in etwa so aus:
statusEvents:
...
- description: EVENT_DESCRIPTION
eventTime: '...'
type: RUNNABLE_CUSTOM_EVENT
...
Nächste Schritte
- Wenn Probleme beim Erstellen oder Ausführen eines Jobs auftreten, finden Sie weitere Informationen unter Fehlerbehebung.
- Informationen zum Aufrufen von Statusereignissen
- Aufgabenprotokolle schreiben
- Weitere Optionen zum Erstellen von Jobs