Écrire des journaux de tâches

Ce document explique comment écrire des journaux de tâches et comment créer et exécuter un job Batch contenant des journaux de tâches.

Lorsque la journalisation est activée pour une tâche, les journaux de tâche sont générés à partir des messages que les exécutables du job 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 vous aider à analyser et à résoudre plus facilement vos tâches. Pour en savoir plus sur les journaux, consultez Analyser une tâche à l'aide de journaux

Avant de commencer

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

  2. Pour obtenir les autorisations nécessaires pour créer un job qui écrit des journaux, demandez à votre administrateur de vous accorder les rôles IAM suivants :

    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.

Créer et exécuter une tâche avec des journaux de tâches

Pour créer et exécuter un job pour lequel vous souhaitez disposer de journaux de tâches, procédez comme suit : lors de la création de la tâche:

  1. Activez les journaux pour la tâche. Cela permet de générer tous les journaux écrits pour la tâche.

  2. Pour chaque journal de tâches que vous souhaitez ajouter au job, ajoutez une commande qui écrit un journal des tâches dans un exécutable. Lorsque le job 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 Rédigez des journaux de tâches dans ce document.

Écrire des journaux de tâches

Un journal de tâche est écrit pour tout contenu que les exécutables d'une tâche impriment dans le flux de sortie standard (stdout) ou le flux d'erreur standard (stderr) au moment de l'exécution. Par exemple, vous pouvez écrire des journaux de tâches à l'aide du Commande echo La structure du journal des tâches généré varie en fonction du formatage du contenu imprimé. Plus précisément, vous pouvez écrire chaque journal de tâche à l'aide de l'une des options suivantes :

Écrire un journal non structuré en imprimant une chaîne

Les journaux non structurés vous permettent de définir un message, qui est une chaîne qui apparaît dans le champ textPayload du journal.

Pour écrire un journal non structuré, imprimez une chaîne non formatée, comme illustré dans les sections suivantes.

Exemple de journal non structuré

Par exemple, supposons que vous souhaitiez un journal des tâches contenant les éléments suivants : chaîne:

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: le message, qui est une chaîne qui résume l'objectif du journal des tâches, par exemple, The summary for a task log.
  • PROJECT_ID : ID de projet de votre projet.

Vous pouvez imprimer une chaîne à l'aide de différentes méthodes, par exemple en incluant le paramètre 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ées, consultez Créer et exécuter un job de base

Écrire un journal structuré en imprimant un objet JSON

Les journaux structurés vous permettent de définir les éléments suivants :

Pour écrire un journal structuré, imprimez un objet JSON. Les sections suivantes expliquent comment définir un journal avec certains des champs standards et personnalisés. Pour 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 de tâches contenant les informations de l'objet JSON suivant, qui définit un message, une 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 qui résume 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. La gravité doit correspondre à l'une des valeurs suivantes : Énumérations LogSeverity convertie en une chaîne dont seule la première lettre est en majuscule. Par exemple : Pour l'énumération ERROR, spécifiez Error.
  • CUSTOM_FIELD_1 et CUSTOM_FIELD_2: noms des champs personnalisés pour le journal des tâches (par exemple, custom_field_1 et custom_field_2
  • CUSTOM_VALUE_1 et CUSTOM_VALUE_2: valeurs des champs personnalisés pour la journal des tâches, qui peut être de différents types de données et nécessiter des guillemets, par exemple Exemple : "the first custom field" et 2.
  • PROJECT_ID: le ID du projet de votre projet.

Vous pouvez imprimer cet exemple d'objet JSON de différentes manières. Par exemple, 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.

  • Imprimez 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écutiez un job avec le code 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 fichier , 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 un job 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: ...

Étape suivante