Configurer des événements d'état personnalisés pour décrire les exécutables

Ce document explique comment configurer des événements d'état personnalisés, qui décrivent les exécutables d'une tâche, lorsque vous créez et exécutez une tâche par lot. Pour en savoir plus sur les événements d'état, consultez la page Afficher l'historique d'un job via les événements d'état.

Les événements d'état personnalisés vous permettent de fournir des détails supplémentaires dans l'historique d'une tâche sur la progression de ses exécutables, ce qui peut faciliter l'analyse et le dépannage d'une tâche. Par exemple, vous pouvez configurer des événements d'état personnalisés qui décrivent le moment où un exécutable démarre, se termine, lorsqu'une barrière exécutable est atteinte ou lorsqu'un événement important se produit pendant la progression de votre code.

Avant de commencer

Configurer des événements d'état personnalisés

Lorsque vous créez une tâche, configurez des événements d'état personnalisés à l'aide d'une ou de plusieurs des options suivantes:

  • Décrivez l'état d'un exécutable en définissant son nom à afficher. Vous pouvez le faire lorsque vous créez un job à l'aide de gcloud CLI ou de l'API Batch.

  • Indiquez les événements d'exécution importants en écrivant un journal de tâches structuré avec le champ batch/custom/event pour chaque événement. Vous pouvez le faire lorsque vous utilisez n'importe quelle méthode pour créer une tâche dans le cadre de la définition des exécutables et des conteneurs.

Décrire l'état d'un exécutable

Vous pouvez configurer des événements d'état personnalisés qui décrivent l'état d'un exécutable en définissant son nom à afficher (champ displayName). Les événements d'état personnalisés qui en résultent varient légèrement selon les types d'exécutables:

  • Si vous définissez un nom à afficher pour un conteneur ou un script exécutable, Batch ajoute automatiquement deux types d'événements d'état personnalisés. Le premier événement d'état personnalisé indique chaque fois qu'une tâche démarre cet exécutable. Le deuxième événement d'état personnalisé indique chaque fois qu'une tâche met fin à l'exécutable et le code de sortie correspondant.

  • Si vous définissez un nom à afficher pour un exécutable de barrière, Batch ajoute automatiquement un événement d'état personnalisé qui indique chaque fois qu'une tâche atteint cette barrière.

Pour créer et exécuter une tâche avec des événements d'état personnalisés décrivant l'état d'un exécutable, définissez le champ displayName pour un ou plusieurs exécutables à l'aide de la gcloud CLI ou de l'API Batch.

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

Par exemple, une tâche avec des événements d'état personnalisés décrivant l'état de chaque exécutable peut comporter un fichier de configuration JSON semblable à celui-ci:

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

Remplacez DISPLAY_NAME1, DISPLAY_NAME2 et DISPLAY_NAME3 par le nom de l'exécutable, qui doit être unique dans la tâche (par exemple, script 1, barrier 1 et script 2).

Une fois l'exécution de l'exemple de tâche terminée, les événements d'état personnalisés obtenus pour chaque tâche se présentent comme suit:

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

Indiquer des événements d'exécution importants

Vous pouvez configurer des événements d'état personnalisés qui indiquent quand un événement important se produit pendant qu'un exécutable est en cours d'exécution. Pour ce faire, configurez cet exécutable de sorte qu'il écrive un journal de tâches structuré qui définit une chaîne pour le champ d'événement d'état personnalisé Batch (batch/custom/event).

Si un conteneur exécutable ou un script exécutable écrit un journal de tâches structuré qui définit le champ JSON batch/custom/event, il génère un événement d'état personnalisé à ce moment-là. Bien que vous puissiez configurer le journal des tâches structurées de manière à inclure des champs supplémentaires, l'événement d'état personnalisé n'inclut que la chaîne du champ batch/custom/event.

Pour créer et exécuter une tâche avec des événements d'état personnalisés qui indiquent quand un événement important se produit, configurez un ou plusieurs exécutables pour écrire un journal structuré en imprimant JSON et définissez le champ batch/custom/event dans le journal.

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

Par exemple, une tâche avec des événements d'état personnalisés qui indiquent quand un événement important se produit peut disposer d'un fichier de configuration JSON semblable à celui-ci:

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

Remplacez EVENT_DESCRIPTION par la description de l'événement d'état personnalisé (par exemple, halfway done).

Une fois l'exécution de l'exemple de tâche terminée, l'événement d'état personnalisé généré pour chaque tâche se présente comme suit:

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

Étapes suivantes