Ce document explique comment écrire des journaux de tâches, et comment créer et exécuter un job par lot contenant des journaux de tâches.
Lorsque la journalisation est activée pour une tâche, des journaux de tâches sont générés à partir des messages que les exécutables de la tâche impriment pendant l'exécution. En configurant vos exécutables pour écrire des journaux de tâches, vous pouvez afficher des informations personnalisées dans Cloud Logging, ce qui peut faciliter l'analyse et le dépannage de vos tâches. Pour en savoir plus sur les journaux, consultez la page Analyser une tâche à l'aide des journaux.
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 qui écrit des journaux, demandez à votre administrateur de vous attribuer les rôles IAM suivants:
-
Pour créer une tâche, procédez comme suit :
-
É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
-
Éditeur de tâches par lot (
-
Pour afficher les journaux : Visionneuse de journaux (
roles/logging.viewer
) sur le projet
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.
-
Pour créer une tâche, procédez comme suit :
Créer et exécuter un job contenant des journaux de tâches
Pour créer et exécuter une tâche pour laquelle vous souhaitez disposer de journaux de tâches, procédez comme suit lors de la création de la tâche:
- Activez les journaux pour la tâche. Cela permet de générer tous les journaux écrits pour la tâche.
Pour chaque journal de tâches que vous souhaitez ajouter à la tâche, ajoutez une commande qui écrit un journal de tâches dans un exécutable. Lorsque la tâche s'exécute, un journal de tâches est généré chaque fois qu'une commande d'écriture d'un journal de tâches est exécutée.
Pour savoir comment écrire des journaux de tâches, consultez la section Écrire des journaux de tâches de ce document.
Écrire des journaux de tâches
Un journal de tâches est écrit pour tout contenu que les exécutables d'une tâche impriment dans le flux de sortie standard (stdout
) ou d'erreur standard (stderr
) pendant l'exécution. Par exemple, vous pouvez écrire des journaux de tâches à l'aide de la commande echo
.
La structure du journal des tâches généré varie en fonction du format du contenu imprimé. Plus précisément, vous pouvez écrire chaque journal des tâches en utilisant l'une des options suivantes:
Écrivez un journal non structuré en imprimant une chaîne. Les journaux non structurés sont simples et vous permettent uniquement de définir le champ
textPayload
du journal.Écrivez un journal structuré en imprimant JSON. Les journaux structurés nécessitent une mise en forme JSON, ce qui vous permet de définir plusieurs champs, y compris certains champs de journal standards, champs personnalisés et événements d'état personnalisés.
Par exemple, vous pouvez utiliser des journaux de tâches structurés pour définir le niveau de gravité d'un journal. Vous pouvez l'utiliser comme filtre lorsque vous affichez les journaux d'une tâche.
Écrire un journal non structuré en imprimant une chaîne
Les journaux non structurés vous permettent de définir un message, c'est-à-dire une chaîne qui apparaît dans le champ textPayload
du journal.
Pour écrire un journal non structuré, imprimez une chaîne non mise en forme comme indiqué dans les sections suivantes.
Exemple de journal non structuré
Par exemple, supposons que vous souhaitiez un journal des tâches contenant la chaîne suivante:
MESSAGE
L'impression de cet exemple de chaîne génère un journal des tâches semblable à celui-ci:
insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...
Remplacez les éléments suivants :
MESSAGE
: message, qui est une chaîne résumant l'objectif du journal des tâches (par exemple,The summary for a task log.
).PROJECT_ID
: ID de votre projet.
Imprimer une chaîne
Vous pouvez imprimer une chaîne à l'aide de différentes méthodes, par exemple en incluant la commande echo
suivante dans un exécutable:
echo MESSAGE
Pour obtenir des exemples complets de tâches qui utilisent la commande echo
pour écrire des journaux de tâches non structurés, consultez la page Créer et exécuter une tâche de base.
Écrire un journal structuré en imprimant un objet JSON
Les journaux structurés vous permettent de définir les éléments suivants:
- Champs standards compatibles avec l'agent Cloud Logging
- Champs personnalisés
- Événements d'état personnalisés
Pour écrire un journal structuré, imprimez un objet JSON. Les sections suivantes expliquent comment définir un journal avec certains des champs standards et des champs personnalisés. Si vous souhaitez savoir comment définir un journal avec des événements d'état personnalisés, consultez également Configurer des événements d'état personnalisés.
Exemple de journal structuré
Par exemple, supposons que vous souhaitiez un journal des tâches contenant les informations de l'objet JSON suivant, qui définit un message, un niveau de gravité et deux champs personnalisés.
{
"message": "MESSAGE"
"severity": "SEVERITY"
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
}
L'impression de cet objet JSON génère un journal des tâches semblable à celui-ci:
insertId: ...
jsonPayload:
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
message: MESSAGE
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: SEVERITY
timestamp: ...
Remplacez les éléments suivants :
MESSAGE
: message, qui est une chaîne résumant l'objectif du journal des tâches (par exemple,The summary for a task log.
).SEVERITY
: gravité du journal, que vous pouvez utiliser comme filtre lorsque vous affichez les journaux d'une tâche. Le niveau de gravité doit correspondre à l'une des énumérationsLogSeverity
converties en chaîne dont seule la première lettre est en majuscule. Par exemple, pour l'énumérationERROR
, spécifiezError
.CUSTOM_FIELD_1
etCUSTOM_FIELD_2
: noms des champs personnalisés du journal des tâches (par exemple,custom_field_1
etcustom_field_2
).CUSTOM_VALUE_1
etCUSTOM_VALUE_2
: valeurs des champs personnalisés du journal des tâches, qui peuvent correspondre à différents types de données et nécessiter des guillemets (par exemple,"the first custom field"
et2
).PROJECT_ID
: ID de votre projet.
Imprimer un objet JSON
Vous pouvez imprimer cet exemple d'objet JSON à l'aide de différentes méthodes. Les exemples suivants illustrent certaines des méthodes possibles pour imprimer l'exemple d'objet JSON:
- Affichez une chaîne équivalente à l'aide de la commande
echo
. Affichez un dictionnaire équivalent à l'aide de Python.
commande echo
Pour imprimer l'exemple d'objet JSON à l'aide de la commande echo
et d'une chaîne équivalente, incluez la commande suivante dans un exécutable:
echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'
Par exemple, supposons que vous créiez et exécutez une tâche avec l'exécutable suivant:
"script": {
"text": "echo '{\"message\":\"The message for a structured log.\", \"severity\":\"Error\", \"custom_field_1\":\"the first custom field\", \"custom_field_2\":2}'"
}
Le journal des tâches obtenu ressemble ensuite à ce qui suit:
insertId: ...
jsonPayload:
custom_field_1: the first custom field
custom_field_2: 2
message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...
Python
Pour imprimer l'exemple d'objet JSON à l'aide de Python et d'un dictionnaire équivalent, incluez l'exemple suivant dans un exécutable:
#!/usr/bin/env python3
import json
entry = dict(
severity="SEVERITY",
message="MESSAGE",
CUSTOM_FIELD_1=CUSTOM_VALUE_1,
CUSTOM_FIELD_2=CUSTOM_VALUE_2,
)
print(json.dumps(entry))
Par exemple, supposons que vous créiez et exécutez une tâche avec l'exécutable suivant:
"script": {
"text": "#!/usr/bin/env python3\n\nimport json\n\nentry = dict(\nseverity=\"Error\",\nmessage=\"The summary for a structured task log with error severity.\",\ncustom_field_1=\"the first custom field\",\ncustom_field_2=2,\n)\nprint(json.dumps(entry))"
}
Le journal des tâches obtenu ressemble ensuite à ce qui suit:
insertId: ...
jsonPayload:
custom_field_1: the first custom field
custom_field_2: 2
message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...
Étapes suivantes
- Pour en savoir plus sur la mise en forme des journaux, consultez la section Journalisation structurée dans la documentation Cloud Logging.
- Découvrez comment écrire des journaux de tâches structurés qui incluent des événements d'état personnalisés.
- Découvrez comment afficher les journaux d'une tâche.
- Apprenez-en plus sur les options de création de tâches.