Configura eventi di stato personalizzati per descrivere gli elementi eseguibili

Questo documento spiega come configurare eventi di stato personalizzati, che descrivono gli elementi eseguibili di un job, quando crei ed esegui un job batch. Per informazioni sugli eventi di stato, consulta Visualizzare la cronologia di un job tramite gli eventi di stato.

Gli eventi di stato personalizzati consentono di fornire ulteriori dettagli nella cronologia di un'attività in merito all'avanzamento degli elementi eseguibili, il che può contribuire a semplificare l'analisi e la risoluzione dei problemi di un job. Ad esempio, puoi configurare eventi di stato personalizzati che descrivono quando un avvio eseguibile, una fine eseguibile, viene raggiunta una barriera eseguibile o si verifica un evento importante durante l'avanzamento del codice.

Prima di iniziare

Se non hai mai utilizzato Batch, consulta la Guida introduttiva all'utilizzo di Batch e abilita Batch completando i prerequisiti per progetti e utenti.
Per ottenere le autorizzazioni necessarie per creare un job, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Editor job batch (roles/batch.jobsEditor) sul progetto
- Utente account di servizio (roles/iam.serviceAccountUser) nell'account di servizio del job, che per impostazione predefinita è l'account di servizio Compute Engine predefinito
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura eventi di stato personalizzati

Configura eventi di stato personalizzati utilizzando una o più delle seguenti opzioni durante la creazione di un job:

Descrivi lo stato di un eseguibile definendo il nome visualizzato. Puoi farlo quando crei un job utilizzando gcloud CLI o l'API Batch.
Indica eventi di runtime importanti scrivendo un log delle attività strutturato con il campo batch/custom/event per ogni evento. Puoi farlo quando utilizzi qualsiasi metodo per creare un job nell'ambito delle definizioni degli elementi eseguibili di script e container.

Descrivere lo stato di un elemento eseguibile

Puoi configurare eventi di stato personalizzati che descrivono lo stato di un elemento eseguibile definendo il nome visualizzato di un eseguibile (campo displayName). Gli eventi di stato personalizzati risultanti variano leggermente a seconda dei tipi di elementi eseguibili:

Se definisci un nome visualizzato per un container eseguibile o uno script eseguibile, Batch aggiunge automaticamente due tipi di eventi di stato personalizzati. Il primo evento di stato personalizzato indica ogni volta che un'attività avvia questo eseguibile. Il secondo evento di stato personalizzato indica quando un'attività termina questo eseguibile e il codice uscita corrispondente.
Se definisci un nome visualizzato per un elemento eseguibile di una barriera, Batch aggiunge automaticamente un evento di stato personalizzato che indica ogni volta che un'attività raggiunge questa barriera.

Per creare ed eseguire un job con eventi di stato personalizzati che descrivono lo stato di un elemento eseguibile, definisci il campo displayName per uno o più elementi eseguibili utilizzando l'interfaccia a riga di comando gcloud o l'API Batch.

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

Ad esempio, un job con eventi di stato personalizzati che descrivono lo stato di ogni eseguibile può avere un file di configurazione JSON simile al seguente:

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

Sostituisci DISPLAY_NAME1, DISPLAY_NAME2 e DISPLAY_NAME3 con il nome dell'elemento eseguibile, che deve essere univoco all'interno del job, ad esempio script 1, barrier 1 e script 2.

Al termine dell'esecuzione del job di esempio, gli eventi di stato personalizzati risultanti per ogni attività sono simili ai seguenti:

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
  ...

Indicano eventi di runtime importanti

Puoi configurare eventi di stato personalizzati che indicano quando si verifica un evento importante mentre un elemento eseguibile è in esecuzione, configurandolo come eseguibile in modo da scrivere un log delle attività strutturato che definisca una stringa per il campo Evento di stato personalizzato Batch (batch/custom/event).

Se un container eseguibile o uno script scrive un log di attività strutturato che definisce il campo JSON batch/custom/event, in quel momento viene generato un evento di stato personalizzato. Sebbene sia possibile configurare il log delle attività strutturato in modo da includere campi aggiuntivi, l'evento di stato personalizzato include solo la stringa per il campo batch/custom/event.

Per creare ed eseguire un job con eventi di stato personalizzati che indicano quando si verifica un evento importante, configura uno o più elementi eseguibili per scrivere un log strutturato stampando JSON e definisci il campo batch/custom/event come parte del log.

...
"runnables": [
  {
    ...
    "echo '{\"batch/custom/event\":\"EVENT_DESCRIPTION\"}'"
    ...
  }
]
...
"logsPolicy": {
  "destination": "CLOUD_LOGGING"
}
...

Ad esempio, un job con eventi di stato personalizzati che indicano quando si verifica un evento importante può avere un file di configurazione JSON simile al seguente:

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "sleep 30; echo '{\"batch/custom/event\": \"EVENT_DESCRIPTION\"}'; sleep 30"
            }
          }
        ]
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

Sostituisci EVENT_DESCRIPTION con una descrizione per l'evento di stato personalizzato, ad esempio halfway done.

Al termine dell'esecuzione del job di esempio, l'evento di stato personalizzato risultante per ogni attività è simile al seguente:

statusEvents:
  ...
  - description: EVENT_DESCRIPTION
    eventTime: '...'
    type: RUNNABLE_CUSTOM_EVENT
  ...

Passaggi successivi

In caso di problemi durante la creazione o l'esecuzione di un job, consulta Risoluzione dei problemi.
Scopri come visualizzare gli eventi relativi allo stato.
Scopri come scrivere i log delle attività.
Scopri di più sulle opzioni per la creazione di job.