Surveiller les exécutions

Ce document vous explique comment :

Avant de commencer

Pour surveiller les journaux d'exécution, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Sélectionnez ou créez un dépôt.

  3. Sélectionnez ou créez un espace de travail de développement.

  4. Déclenchez une exécution au moins une fois.

Rôles requis

Pour obtenir les autorisations nécessaires pour afficher les journaux d'exécution, demandez à votre administrateur de vous accorder les rôles IAM suivants :

  • Éditeur Dataform (roles/dataform.editor) sur le dépôt Dataform où les exécutions de workflows sont suivies
  • Vérification de la configuration d'une exécution : Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le compte de service personnalisé

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Le rôle IAM Lecteur de journaux (roles/logging.viewer) vous donne un accès en lecture seule à toutes les fonctionnalités de Cloud Logging. Pour en savoir plus sur les autorisations et les rôles Identity and Access Management qui s'appliquent aux données Logging, consultez Contrôle des accès avec IAM.

Pour créer et gérer des alertes basées sur les journaux, assurez-vous que votre rôle IAM inclut les autorisations décrites dans Rôles requis pour créer et utiliser des règles d'alerte basées sur les journaux.

Surveiller les journaux d'exécution

Cette section vous explique comment afficher les journaux d'exécution dans Dataform.

Vous pouvez afficher les journaux de toutes les exécutions déclenchées dans un dépôt, ainsi que les journaux des exécutions déclenchées dans un espace de travail au cours des dernières 24 heures.

Inspecter les journaux d'exécution du dépôt

Pour afficher les journaux de toutes les exécutions déclenchées dans un dépôt, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Accédez à votre dépôt.

  3. Cliquez sur Journaux d'exécution de workflow.

  4. Pour afficher les détails d'une exécution, cliquez dessus.

  5. Pour afficher les détails d'une action dans l'exécution, cliquez sur Afficher les détails.

Inspecter les journaux d'exécution de l'espace de travail

Pour afficher les journaux des 1 000 exécutions les plus récentes déclenchées dans un espace de travail au cours des dernières 24 heures, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Accédez à votre dépôt et sélectionnez votre espace de travail.

  3. Dans votre espace de travail, cliquez sur Exécutions.

  4. Pour afficher les détails d'une exécution, cliquez dessus.

  5. Pour afficher les détails d'une action au sein de l'exécution, cliquez sur Afficher les détails.

Afficher les journaux Logging pour Dataform

Cette section explique comment afficher les journaux Cloud Logging pour les appels de workflow Dataform.

Chaque appel de workflow Dataform est consigné à l'aide de Logging. La journalisation est automatiquement activée pour les appels de workflow Dataform, ce qui peut entraîner des frais de facturation Logging. Pour en savoir plus, consultez la page Tarifs de Dataform.

Afficher les journaux

Pour en savoir plus sur le filtrage des journaux Logging dans l'explorateur de journaux, consultez Afficher les journaux à l'aide de l'explorateur de journaux.

Les journaux Dataform sont indexés par dépôt Dataform.

Format du journal

Dataform envoie les messages de journal d'appel de workflow au format suivant :

{
  "insertId": "14ip1tza5",
  "jsonPayload": {
    "terminalState": "SUCCEEDED",
    "workflowInvocationId": "1678383230-ac4ed48c-eb70-4555-b2b0-cda54d13edfa",
    "@type": "type.googleapis.com/google.cloud.dataform.logging.v1.WorkflowInvocationCompletionLogEntry"
  },
  "resource": {
    "type": "dataform.googleapis.com/Repository",
    "labels": {
      "repository_id": "repository-name-example",
      "resource_container": "PROJECT_ID",
      "location": "us-central1"
    }
  },
  "timestamp": "2023-03-09T17:34:06.965981805Z",
  "severity": "INFO",
  "logName": "projects/project-name-example/logs/dataform.googleapis.com%2Fworkflow_invocation_completion",
  "receiveTimestamp": "2023-03-09T17:34:07.362371980Z"
}

Contenu consigné

Les entrées de journal Dataform contiennent des informations utiles pour surveiller et déboguer vos appels de workflow.

Les entrées de journal contiennent les types d'informations suivants :

  • receiveTimestamp
  • release_config_id
  • repository_id
  • resource_container
  • workflow_invocation_id
  • workflow_config_id
  • severity : il peut s'agir de INFO, ​WARNING ou ERROR.
  • terminalState : il peut s'agir de SUCCEEDED, ​CANCELED ou FAILED.
  • timestamp
  • @type

Les journaux du service Dataform fournissent des événements d'appel de haut niveau, tels que les journaux d'achèvement d'appel de workflow. Toutefois, ces journaux de service n'incluent pas les ID de job BigQuery individuels ni les exécutions d'actions précises au niveau de la table. Pour récupérer des détails d'exécution précis au niveau de l'action et les ID de job BigQuery correspondants pour un appel de workflow, consultez Mettre en corrélation des jobs BigQuery avec des appels de workflow.

Configurer des métriques et des alertes avec Cloud Monitoring

Vous pouvez utiliser Monitoring pour observer les tendances dans vos journaux et être averti lorsque les conditions que vous décrivez se produisent.

Pour fournir à Monitoring des données issues de vos journaux, Logging vous propose les options suivantes :

  • Les métriques basées sur les journaux, que vous pouvez utiliser comme suit :
    • Créer des règles d'alerte qui vous informent des modifications au fil du temps.
    • Créer des graphiques qui affichent les modifications au fil du temps.
  • Des alertes basées sur les journaux, qui vous avertissent chaque fois qu'un événement spécifique apparaît dans un journal.

Pour en savoir plus sur les métriques et les alertes basées sur les journaux, consultez Surveiller vos journaux.

Pour savoir comment configurer des alertes basées sur les journaux pour les appels de workflow Dataform, consultez Configurer des alertes pour les appels de workflow ayant échoué.

Mettre en corrélation les jobs BigQuery avec les appels de workflow

Les journaux du service Dataform sous le type de ressource dataform.googleapis.com/Repository fournissent des événements d'appel de workflow de haut niveau, tels que les journaux d'achèvement d'appel de workflow. Toutefois, ces journaux de service n'incluent pas les exécutions d'actions précises au niveau de la table ni les ID de job BigQuery spécifiques.

Lorsque Dataform exécute des actions telles que la création ou la mise à jour de tables, de vues ou d'assertions, il envoie des jobs dans BigQuery et leur associe automatiquement des étiquettes. Vous pouvez également récupérer l'ID de job BigQuery pour chaque action directement à partir de l'API Dataform en appelant la méthode workflowInvocations.query et en inspectant le champ bigqueryAction.jobId.

Le tableau suivant liste les libellés de clé que Dataform associe aux jobs BigQuery :

Clé de l'étiquette Description
dataform_workflow_execution_id ID nettoyé de l'appel de workflow Dataform.
dataform_repository_id ID nettoyé du dépôt Dataform.
dataform_workflow_execution_action_id_database Projet cible (base de données) de l'action.
dataform_workflow_execution_action_id_schema Ensemble de données cible (schéma) de l'action.
dataform_workflow_execution_action_id_name Nom de la table, de la vue ou de l'assertion cible de l'action.

Pour mettre en corrélation les jobs BigQuery et les détails d'exécution au niveau de l'action avec un appel de workflow, procédez comme suit :

  1. Obtenez l'ID d'appel de workflow pour votre exécution. Pour rechercher l'ID dans l'explorateur de journaux, interrogez l'un des types de journaux Dataform suivants :

    • Journaux workflow_invocation_completion (activés par défaut) : copiez la valeur du champ jsonPayload.workflowInvocationId à partir de l'entrée de journal :

      resource.type="dataform.googleapis.com/Repository"
resource.labels.repository_id="REPOSITORY_ID"
log_id("dataform.googleapis.com/workflow_invocation_completion")

    • Journaux d'audit des accès aux données CreateWorkflowInvocation (si les journaux d'audit des accès aux données sont activés pour les opérations DATA_WRITE) : copiez le segment WORKFLOW_INVOCATION_ID à la fin du champ protoPayload.resourceName :

      resource.type="dataform.googleapis.com/Repository"
resource.labels.repository_id="REPOSITORY_ID"
log_id("cloudaudit.googleapis.com/data_access")
protoPayload.methodName:"Dataform.CreateWorkflowInvocation"

    Remplacez REPOSITORY_ID par l'ID de votre dépôt Dataform.

  2. Pour trouver les jobs BigQuery corrélés en interrogeant les journaux d'audit BigQuery dans l'explorateur de journaux ou la vue INFORMATION_SCHEMA.JOBS dans BigQuery, sélectionnez l'une des options suivantes :

    Explorateur de journaux

    1. Dans la console Google Cloud , accédez à la page Explorateur de journaux.

      Accéder à l'explorateur de journaux

    2. Dans le volet Requête, saisissez la requête suivante :

      resource.type="bigquery_project"
protoPayload.metadata.jobChange.job.jobConfig.labels.dataform_workflow_execution_id="WORKFLOW_INVOCATION_ID"

      Remplacez WORKFLOW_INVOCATION_ID par l'ID d'appel de votre workflow.

    3. Cliquez sur Exécuter la requête.

      La requête renvoie les entrées de journal des jobs BigQuery pour ce déclenchement de workflow. Dans chaque entrée de journal, le champ protoPayload.metadata.jobChange.job.jobName contient le nom de la ressource de job BigQuery, et les champs jobStats et jobStatus fournissent des statistiques d'exécution et des détails sur l'état.

    BigQuery Studio

    1. Dans la console Google Cloud , accédez à la page BigQuery Studio.

      Accéder à BigQuery Studio

    2. Dans l'éditeur de requête, saisissez la requête suivante :

      SELECT
  job_id,
  creation_time,
  state,
  error_result,
  total_bytes_billed,
  (SELECT value FROM UNNEST(labels) WHERE key = 'dataform_workflow_execution_action_id_schema') AS target_schema,
  (SELECT value FROM UNNEST(labels) WHERE key = 'dataform_workflow_execution_action_id_name') AS target_name,
  query
FROM
  `region-LOCATION`.INFORMATION_SCHEMA.JOBS
WHERE
  DATE(creation_time) = CURRENT_DATE()
  AND EXISTS (
    SELECT 1
    FROM UNNEST(labels)
    WHERE
      key = 'dataform_workflow_execution_id'
      AND value = 'WORKFLOW_INVOCATION_ID'
  );

      Remplacez les éléments suivants :

      • LOCATION : emplacement BigQuery où les jobs ont été exécutés, par exemple us ou eu.
      • WORKFLOW_INVOCATION_ID : ID d'appel de votre workflow.

Configurer des alertes pour les appels de workflow ayant échoué

Cette section explique comment configurer des alertes basées sur les journaux pour les échecs d'appels de workflow Dataform à l'aide de l'explorateur de journaux.

Vous pouvez utiliser Monitoring pour observer les tendances dans les journaux Logging pour les appels de workflow Dataform et pour vous avertir lorsque les conditions que vous décrivez se produisent.

Chaque appel de workflow Dataform est consigné à l'aide de Logging. La journalisation est automatiquement activée pour les appels de workflow Dataform, ce qui peut entraîner des frais de facturation Logging. Pour en savoir plus, consultez la page Tarifs de Dataform.

Pour recevoir des alertes en cas d'échec d'une invocation de workflow Dataform, vous pouvez créer des alertes basées sur les journaux.

Vous pouvez créer des alertes basées sur les journaux à partir de la page Explorateur de journaux de la console Google Cloud , ou en utilisant l'API Monitoring. Cette section explique comment créer des alertes basées sur les journaux pour les échecs d'appel de workflow Dataform à l'aide de l'explorateur de journaux.

Pour configurer des alertes basées sur les journaux pour les échecs d'appels de workflow Dataform, procédez comme suit :

  1. Dans la console Google Cloud , sélectionnez Logging, puis Explorateur de journaux.

    Accéder à l'explorateur de journaux

  2. Dans le volet Requête, sélectionnez Afficher la requête et saisissez la requête suivante :

        resource.type="dataform.googleapis.com/Repository"
    jsonPayload.@type="type.googleapis.com/google.cloud.dataform.logging.v1.WorkflowInvocationCompletionLogEntry"
    jsonPayload.terminalState="FAILED"

    Cette requête vous alerte en cas d'échec d'appels de workflow Dataform.

    1. Facultatif : Pour filtrer les appels de workflow ayant échoué par configuration de version, ajoutez ce qui suit à la requête :

          jsonPayload.releaseConfigId="RELEASE_CONFIGURATION_ID"

      Remplacez RELEASE_CONFIGURATION_ID par l'ID de la configuration de version.

    2. Facultatif : Pour filtrer les appels de workflow ayant échoué par configuration de workflow, ajoutez ce qui suit à la requête :

          jsonPayload.workflowConfigId="WORKFLOW_CONFIGURATION_ID"

      Remplacez WORKFLOW_CONFIGURATION_ID par l'ID de la configuration du workflow.

    La requête suivante vous alerte lorsqu'une invocation de workflow Dataform liée à la fois à la configuration de version daily et à la configuration de workflow production échoue :

     resource.type="dataform.googleapis.com/Repository"
 jsonPayload.@type="type.googleapis.com/google.cloud.dataform.logging.v1.WorkflowInvocationCompletionLogEntry"
 jsonPayload.terminalState="FAILED"
 jsonPayload.releaseConfigId="daily"
 jsonPayload.workflowConfigId="production"

  3. Facultatif : Pour valider la requête, utilisez Exécuter la requête dans le volet Résultats de la requête.

  4. Dans l'en-tête du volet Résultats de la requête, cliquez sur Créer une alerte. Si votre fenêtre est étroite, l'option Créer une alerte peut s'afficher dans le menu Actions.

  5. Dans le volet Détails de l'alerte, attribuez un nom et une description à l'alerte :

    1. Saisissez un nom pour l'alerte dans le champ Nom de l'alerte. Exemple : Dataform: workflow failure.

    2. Saisissez une description pour cette alerte. Vous pouvez également inclure des informations susceptibles d'aider le destinataire d'une notification à diagnostiquer le problème. La chaîne suivante résume la raison de l'alerte :

      Log-based alert in project ${project} detected a failed Dataform workflow.

      Pour savoir comment mettre en forme et personnaliser le contenu de ce champ, consultez Annoter les notifications avec une documentation définie par l'utilisateur.

  6. Pour passer à l'étape suivante, cliquez sur Suivant.

  7. Dans le volet Sélectionner les journaux à inclure dans l'alerte, vérifiez la requête et les résultats en cliquant sur Prévisualiser les journaux.

    Nous vous recommandons de créer la requête dans le volet Requête de l'explorateur de journaux. La requête que vous avez créée dans le volet Requête s'affiche également dans ce volet.

    Si nécessaire, vous pouvez modifier la requête dans ce volet. Si vous modifiez la requête, vérifiez les résultats en cliquant sur Prévisualiser les journaux.

  8. Cliquez sur Suivant.

  9. Sélectionnez le délai minimal entre les notifications. Cette valeur vous permet de contrôler le nombre de notifications que vous recevez de cette alerte si elle est déclenchée plusieurs fois. Pour cet exemple, sélectionnez l'option 5 min.

  10. Facultatif : sélectionnez la durée de fermeture automatique de l'incident. Par défaut, la durée de fermeture automatique des incidents est de sept jours.

  11. Cliquez sur Suivant.

  12. Sélectionnez un ou plusieurs canaux de notification pour votre alerte. Pour cet exemple, sélectionnez un canal de notification par e-mail.

    Si vous avez déjà configuré un canal de notification par e-mail, vous pouvez le sélectionner dans la liste. Si ce n'est pas le cas, cliquez sur Gérer les canaux de notification et ajoutez un canal de notification par e-mail. Pour en savoir plus sur la création de canaux de notification, consultez Créer et gérer des canaux de notification.

  13. Cliquez sur Enregistrer.

Votre alerte basée sur les journaux est maintenant prête à être testée. Pour savoir comment tester l'alerte, consultez Tester l'exemple de règle d'alerte basée sur les journaux.

Étapes suivantes