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 Afficher l'historique d'une mission via les événements d'état
Les événements d'état personnalisés vous permettent de fournir des informations supplémentaires dans l'historique d'une tâche sur la progression de ses exécutables, ce qui peut aider plus faciles à analyser et à dépanner. Par exemple, vous pouvez configurer des événements d'état personnalisés qui décrivent quand un exécutable commence, se termine, atteint une barrière exécutable ou qu'un événement important se produit au cours de la progression de votre code.
Avant de commencer
- Si vous n'avez jamais utilisé Batch auparavant, consultez Premiers pas avec Batch et activez Batch en suivant la les conditions préalables pour les projets et les utilisateurs.
-
Pour obtenir les autorisations nécessaires à la création d'un job, demandez à votre administrateur de vous accorder le rôles IAM suivants:
-
Éditeur de jobs 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 page Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
-
Éditeur de jobs par lot (
Configurer des événements d'état personnalisés
Configurez des événements d'état personnalisés à l'aide d'un ou de plusieurs des éléments suivants lors de la création d'une tâche:
Décrire 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 les définitions des exécutables de script et de conteneur.
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 fichier exécutable de conteneur ou de script, 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 termine cet exécutable et le code de sortie correspondant.
Si vous définissez un nom à afficher pour un barrière exécutable, Batch ajoute ensuite automatiquement un événement d'état personnalisé qui indique chaque fois qu'une tâche atteint cet obstacle.
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 CLI gcloud, de l'API ou de la bibliothèque Batch.
gcloud
Utiliser la Google Cloud CLI
créer une tâche qui
inclut le champ displayName
dans une ou plusieurs définitions runnables
dans le fichier JSON:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
Par exemple, une tâche avec des événements d'état personnalisés qui décrivent l'état de chaque exécutable peut avoir 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
DISPLAY_NAME3
par le nom de l'exécutable,
doit être unique au sein de la tâche (par exemple, script 1
, barrier 1
et
script 2
API
Utiliser l'API REST pour
créer une tâche qui
inclut le champ displayName
dans une ou plusieurs définitions runnables
dans le fichier JSON:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
Par exemple, une tâche avec des événements d'état personnalisés qui décrivent l'état de chaque exécutable peut avoir 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
).
Go
Java
Node.js
Python
Une fois l'exemple de tâche exécuté, les événements d'état personnalisés générés pour chaque tâche ressemblent à ce qui 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 les é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-le afin d'écrire
journal structuré des tâches qui définit une chaîne pour la ressource
Événement d'état personnalisé (batch/custom/event
).
Si un exécutable de conteneur ou de script é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 de tâches structuré pour inclure des champs supplémentaires, l'événement de statut personnalisé n'inclut que la chaîne pour le champ batch/custom/event
.
Pour créer et exécuter un job avec des événements d'état personnalisés qui indiquent quand un
qu'un événement important se produise, configurez un ou plusieurs exécutables pour
Écrire un journal structuré en imprimant JSON
et définir le champ batch/custom/event
dans le journal.
...
"runnables": [
{
...
"echo '{\"batch/custom/event\":\"EVENT_DESCRIPTION\"}'"
...
}
]
...
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
...
Par exemple, un job avec des événements d'état personnalisés qui indique lorsqu'un un événement important peut avoir un fichier de configuration JSON comme suit:
{
"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 du
un événement d'état personnalisé (par exemple, halfway done
).
Une fois l'exécution de l'exemple de job terminée, l'événement d'état personnalisé qui en résulte pour chaque tâche est semblable à ce qui suit:
statusEvents:
...
- description: EVENT_DESCRIPTION
eventTime: '...'
type: RUNNABLE_CUSTOM_EVENT
...
Étape suivante
- Si vous rencontrez des problèmes lors de la création ou de l'exécution d'un job, consultez la section Dépannage.
- Découvrez comment afficher les événements d'état.
- Découvrez comment écrire des journaux de tâches.
- Découvrez d'autres options de création de tâches.