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
- Si vous n'avez jamais utilisé Batch, consultez la page Premiers pas avec Batch et activez Batch en remplissant les conditions préalables pour les projets et les utilisateurs.
-
Pour obtenir les autorisations nécessaires pour créer une tâche, demandez à votre administrateur de vous attribuer les rôles IAM suivants:
-
Éditeur de tâches par lot (
roles/batch.jobsEditor
) sur le projet -
Utilisateur du compte de service (
roles/iam.serviceAccountUser
) sur le compte de service du job, qui est par défaut le compte de service Compute Engine par défaut
Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
-
Éditeur de tâches par lot (
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
- Si vous rencontrez des problèmes pour créer ou exécuter un job, consultez la section Dépannage.
- Découvrez comment afficher les événements d'état.
- Apprenez à écrire des journaux de tâches.
- Apprenez-en plus sur les options de création de tâches.