Benutzerdefinierte Statusereignisse zum Beschreiben von Runnables konfigurieren

In diesem Dokument wird erläutert, wie Sie beim Erstellen und Ausführen eines Batchjobs benutzerdefinierte Statusereignisse konfigurieren, die die Runnables eines Jobs beschreiben. Weitere Informationen zu Statusereignissen finden Sie unter Jobverlauf über Statusereignisse ansehen.

Mit benutzerdefinierten Statusereignissen können Sie im Verlauf einer Aufgabe zusätzliche Details über den Fortschritt der Runnables angeben, um die Analyse und Fehlerbehebung eines Jobs zu erleichtern. Sie können beispielsweise benutzerdefinierte Statusereignisse konfigurieren, die beschreiben, wann ein ausführbares Element beginnt, wann ein ausführbares Element endet, eine ausführbare Barriere erreicht wird oder ein wichtiges Ereignis während der Ausführung Ihres Codes auftritt.

Hinweise

Benutzerdefinierte Statusereignisse konfigurieren

Konfigurieren Sie benutzerdefinierte Statusereignisse mit einer oder mehreren der folgenden Optionen beim Erstellen eines Jobs:

  • Beschreiben Sie den Status eines Runnables, indem Sie seinen Anzeigenamen definieren. Sie können dies tun, wenn Sie einen Job mit der gcloud CLI oder Batch API erstellen.

  • Wichtige Laufzeitereignisse kennzeichnen, indem Sie für jedes Ereignis ein strukturiertes Aufgabenlog mit dem Feld batch/custom/event schreiben. Das ist möglich, wenn Sie eine beliebige Methode zum Erstellen eines Jobs als Teil der Definitionen von Script- und Container-Runnables verwenden.

Status eines Runnables beschreiben

Sie können benutzerdefinierte Statusereignisse konfigurieren, die den Status eines Runnables beschreiben. Dazu definieren Sie den Anzeigenamen eines Runnables (Feld displayName). Die resultierenden benutzerdefinierten Statusereignisse variieren für verschiedene Arten von Runnables geringfügig:

  • Wenn Sie einen Anzeigenamen für einen ausführbaren Container oder ein ausführbares Script definieren, fügt Batch automatisch zwei Arten von benutzerdefinierten Statusereignissen hinzu. Das erste benutzerdefinierte Statusereignis gibt an, wann eine Aufgabe diese ausführbare Datei startet. Das zweite benutzerdefinierte Statusereignis gibt an, wann eine Aufgabe dieses ausführbare Element und den entsprechenden Exit-Code beendet.

  • Wenn Sie einen Anzeigenamen für ein ausführbares Barrier-Objekt definieren, fügt Batch automatisch ein benutzerdefiniertes Statusereignis hinzu, das anzeigt, wenn eine Aufgabe diese Barriere erreicht.

Definieren Sie das Feld displayName für ein oder mehrere Runnables mithilfe der gcloud CLI oder Batch API, um einen Job mit benutzerdefinierten Statusereignissen, die den Status eines Runnables beschreiben, zu erstellen und auszuführen.

...
"runnables": [
  {
    "displayName":DISPLAY_NAME,
    ...
  }
]
...

Beispielsweise kann ein Job mit benutzerdefinierten Statusereignissen, die den Status jedes Runnables beschreiben, eine JSON-Konfigurationsdatei ähnlich der folgenden haben:

{
  "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 Runnables, der innerhalb des Jobs eindeutig sein darf, z. B. script 1, barrier 1 und script 2.

Nachdem der Beispieljob ausgeführt wurde, sehen die resultierenden benutzerdefinierten Statusereignisse für jede Aufgabe 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 anzeigen

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, das einen String für das benutzerdefinierte Batch-Statusereignisfeld (batch/custom/event) definiert.

Wenn ein ausführbares Container- oder Script 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 das strukturierte Aufgabenlog zwar so konfigurieren, dass zusätzliche Felder enthalten sind, das benutzerdefinierte Statusereignis enthält jedoch nur den String für das Feld batch/custom/event.

Zum Erstellen und Ausführen eines Jobs mit benutzerdefinierten Statusereignissen, die angeben, wenn ein wichtiges Ereignis eintritt, konfigurieren Sie ein oder mehrere Runnables so, dass ein strukturiertes Log durch Drucken 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"
}
...

Beispielsweise kann ein Job mit benutzerdefinierten Statusereignissen, die angeben, wann ein wichtiges Ereignis eintritt, eine JSON-Konfigurationsdatei haben, die in etwa so aussieht:

{
  "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