Monitorare le corse

Questo documento mostra come:

Prima di iniziare

Per monitorare i log di esecuzione, assicurati di:

  1. Nella console Google Cloud , vai alla pagina Dataform.

    Vai a Dataform

  2. Seleziona o crea un repository.

  3. Seleziona o crea un'area di lavoro di sviluppo.

  4. Attiva un'esecuzione almeno una volta.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per visualizzare i log di esecuzione, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Editor Dataform (roles/dataform.editor) nel repository Dataform in cui vengono monitorate le esecuzioni del workflow
  • Verifica della configurazione di un'esecuzione: Utente dell'account di servizio (roles/iam.serviceAccountUser) sul service account personalizzato

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Il ruolo IAM Visualizzatore log (roles/logging.viewer) ti concede l'accesso di sola lettura a tutte le funzionalità di Cloud Logging. Per saperne di più sui ruoli e sulle autorizzazioni di Identity and Access Management che si applicano ai dati di Logging, consulta Controllo dell'accesso con IAM.

Per creare e gestire gli avvisi basati su log, assicurati che il tuo ruolo IAM includa le autorizzazioni descritte in Ruoli richiesti per creare e utilizzare le policy di avviso basate su log.

Monitora i log di esecuzione

Questa sezione mostra come visualizzare i log di esecuzione in Dataform.

Puoi visualizzare i log di tutte le esecuzioni attivate in un repository e i log delle esecuzioni attivate in un workspace nelle ultime 24 ore.

Ispeziona i log di esecuzione del repository

Per visualizzare i log di tutte le esecuzioni attivate in un repository, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Dataform.

    Vai a Dataform

  2. Vai al tuo repository.

  3. Fai clic su Log di esecuzione del flusso di lavoro.

  4. Per visualizzare i dettagli di un'esecuzione, fai clic sull'esecuzione.

  5. Per visualizzare i dettagli di un'azione all'interno dell'esecuzione, fai clic su Visualizza dettagli.

Ispeziona i log di esecuzione di Workspace

Per visualizzare i log delle 1000 esecuzioni più recenti attivate in un workspace nelle ultime 24 ore, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Dataform.

    Vai a Dataform

  2. Vai al tuo repository e seleziona il tuo workspace.

  3. Nell'area di lavoro, fai clic su Esecuzioni.

  4. Per visualizzare i dettagli di un'esecuzione, fai clic sull'esecuzione.

  5. Per visualizzare i dettagli di un'azione all'interno dell'esecuzione, fai clic su Visualizza dettagli.

Visualizza i log di Logging per Dataform

Questa sezione mostra come visualizzare i log di Cloud Logging per le chiamate dei workflow di Dataform.

Ogni chiamata del workflow Dataform viene registrata utilizzando Logging. Il logging viene abilitato automaticamente per le chiamate dei workflow di Dataform, che possono comportare addebiti di fatturazione per Logging. Per saperne di più, consulta i prezzi di Dataform.

Visualizza i log

Per informazioni su come filtrare i log di Logging in Esplora log, consulta Visualizza i log utilizzando Esplora log.

I log di Dataform sono indicizzati per repository Dataform.

Formato log

Dataform invia i messaggi di log delle chiamate workflow nel seguente formato:

{
  "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"
}

Informazioni registrate nei log

Le voci di log di Dataform contengono informazioni utili per monitorare ed eseguire il debug delle chiamate dei workflow.

Le voci di log contengono i seguenti tipi di informazioni:

  • receiveTimestamp
  • release_config_id
  • repository_id
  • resource_container
  • workflow_invocation_id
  • workflow_config_id
  • severity: può essere INFO, WARNING o ERROR
  • terminalState: può essere SUCCEEDED, CANCELED o FAILED
  • timestamp
  • @type

I log del servizio Dataform forniscono eventi di chiamata di alto livello, come i log di completamento della chiamata del workflow. Tuttavia, questi log del servizio non includono i singoli ID job BigQuery o le esecuzioni di azioni granulari a livello di tabella. Per recuperare i dettagli di esecuzione granulari a livello di azione e gli ID job BigQuery corrispondenti per un'esecuzione del workflow, consulta Correlare i job BigQuery alle esecuzioni del workflow.

Configura metriche e avvisi con Cloud Monitoring

Puoi utilizzare Monitoring per osservare le tendenze nei log e per ricevere notifiche quando si verificano le condizioni che descrivi.

Per fornire a Monitoring i dati dei tuoi log, Logging offre quanto segue:

  • Metriche basate su log, che puoi utilizzare come segue:
    • Per creare policy di avviso che ti informano delle modifiche nel tempo.
    • Per creare grafici che mostrano le variazioni nel tempo.
  • Avvisi basati su log, che ti avvisano ogni volta che un evento specifico viene visualizzato in un log.

Per saperne di più sulle metriche basate su log e sugli avvisi basati su log, consulta Monitora i log.

Per scoprire come configurare gli avvisi basati su log per le chiamate dei workflow di Dataform, consulta Configura gli avvisi per le chiamate dei workflow non riuscite.

Correlare i job BigQuery alle esecuzioni dei workflow

I log del servizio Dataform con il tipo di risorsa dataform.googleapis.com/Repository forniscono eventi di chiamata del workflow di alto livello, ad esempio i log di completamento della chiamata del workflow. Tuttavia, questi log dei servizi non includono esecuzioni di azioni granulari a livello di tabella o ID job BigQuery specifici.

Quando Dataform esegue azioni come la creazione o l'aggiornamento di tabelle, viste o asserzioni, invia job in BigQuery e collega automaticamente le etichette a ogni job. Puoi anche recuperare l'ID job BigQuery per ogni azione direttamente dall'API Dataform chiamando il metodo workflowInvocations.query e ispezionando il campo bigqueryAction.jobId.

La tabella seguente elenca le etichette delle chiavi che Dataform associa ai job BigQuery:

Chiave di etichetta Descrizione
dataform_workflow_execution_id L'ID sottoposto a sanificazione della chiamata del workflow Dataform.
dataform_repository_id L'ID sottoposto a sanitizzazione del repository Dataform.
dataform_workflow_execution_action_id_database Il progetto (database) di destinazione dell'azione.
dataform_workflow_execution_action_id_schema Il set di dati di destinazione (schema) dell'azione.
dataform_workflow_execution_action_id_name Il nome della tabella, della vista o dell'asserzione di destinazione dell'azione.

Per correlare i job BigQuery e i dettagli di esecuzione a livello di azione a un'invocazione del workflow, segui questi passaggi:

  1. Ottieni l'ID di chiamata del workflow per l'esecuzione. Per cercare l'ID in Esplora log, esegui una query su uno dei seguenti tipi di log di Dataform:

    • Log workflow_invocation_completion (attivati per impostazione predefinita): copia il valore del campo jsonPayload.workflowInvocationId dalla voce di log:

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

    • Audit log di accesso ai dati CreateWorkflowInvocation (se gli audit log di accesso ai dati sono abilitati per le operazioni DATA_WRITE): copia il segmento WORKFLOW_INVOCATION_ID alla fine del campo 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"

    Sostituisci REPOSITORY_ID con l'ID del tuo repository Dataform.

  2. Per trovare i job BigQuery correlati eseguendo query sugli audit log di BigQuery in Esplora log o sulla vista INFORMATION_SCHEMA.JOBS in BigQuery, seleziona una delle seguenti opzioni:

    Esplora log

    1. Nella console Google Cloud , vai alla pagina Esplora log.

      Vai a Esplora log

    2. Nel riquadro Query, inserisci la seguente query:

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

      Sostituisci WORKFLOW_INVOCATION_ID con l'ID di chiamata del workflow.

    3. Fai clic su Esegui query.

      La query restituisce le voci di log dei job BigQuery per l'esecuzione del workflow. In ogni voce di log, il campo protoPayload.metadata.jobChange.job.jobName contiene il nome della risorsa del job BigQuery, mentre i campi jobStats e jobStatus forniscono statistiche di esecuzione e dettagli sullo stato.

    BigQuery Studio

    1. Nella console Google Cloud , vai alla pagina BigQuery Studio.

      Vai a BigQuery Studio

    2. Nell'editor di query, esegui questa query:

      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'
  );

      Sostituisci quanto segue:

      • LOCATION: la località BigQuery in cui sono stati eseguiti i job, ad esempio us o eu.
      • WORKFLOW_INVOCATION_ID: l'ID della tua chiamata del workflow.

Configura gli avvisi per le chiamate del workflow non riuscite

Questa sezione mostra come configurare gli avvisi basati su log per le chiamate dei workflow di Dataform non riuscite utilizzando Esplora log.

Puoi utilizzare Monitoring per osservare le tendenze nei log di Logging per le chiamate dei workflow di Dataform e per ricevere notifiche quando si verificano le condizioni descritte.

Ogni chiamata del workflow Dataform viene registrata utilizzando Logging. Il logging viene abilitato automaticamente per le chiamate dei workflow di Dataform, il che può comportare addebiti di fatturazione per Logging. Per saperne di più, consulta i prezzi di Dataform.

Per ricevere avvisi quando l'esecuzione di un workflow di Dataform non va a buon fine, puoi creare avvisi basati su log.

Puoi creare avvisi basati su log dalla pagina Esplora log nella console Google Cloud o utilizzando l'API Monitoring. Questa sezione descrive come creare avvisi basati su log per gli errori di chiamata del workflow di Dataform utilizzando Esplora log.

Per configurare gli avvisi basati su log per le chiamate dei workflow di Dataform non riuscite, segui questi passaggi:

  1. Nella console Google Cloud , seleziona Logging, quindi seleziona Esplora log.

    Vai a Esplora log

  2. Nel riquadro Query, seleziona Mostra query e inserisci la seguente query:

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

    Questa query ti avvisa di tutte le chiamate di workflow di Dataform non riuscite.

    1. (Facoltativo) Per filtrare le esecuzioni del workflow non riuscite in base a una configurazione della release, aggiungi quanto segue alla query:

          jsonPayload.releaseConfigId="RELEASE_CONFIGURATION_ID"

      Sostituisci RELEASE_CONFIGURATION_ID con l'ID della configurazione della release.

    2. (Facoltativo) Per filtrare le esecuzioni dei workflow non riusciti in base a una configurazione del workflow, aggiungi quanto segue alla query:

          jsonPayload.workflowConfigId="WORKFLOW_CONFIGURATION_ID"

      Sostituisci WORKFLOW_CONFIGURATION_ID con l'ID della configurazione del workflow.

    La seguente query ti avvisa quando un'invocazione del workflow Dataform correlata sia alla configurazione della release daily sia alla configurazione del workflow production non va a buon fine:

     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. (Facoltativo) Per convalidare la query, utilizza Esegui query nel riquadro Risultati delle query.

  4. Nell'intestazione del riquadro Risultati delle query, fai clic su Crea avviso. Se la finestra è ridotta, l'opzione Crea avviso potrebbe essere visualizzata nel menu Azioni.

  5. Nel riquadro Dettagli avviso, assegna un nome e una descrizione all'avviso:

    1. Inserisci un nome per l'avviso nel campo Nome avviso. Ad esempio: Dataform: workflow failure.

    2. Inserisci una descrizione dell'avviso. Puoi anche includere informazioni che potrebbero aiutare il destinatario di una notifica a diagnosticare il problema. La seguente stringa riassume il motivo dell'avviso:

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

      Per informazioni su come formattare e personalizzare i contenuti di questo campo, consulta Annota le notifiche con la documentazione definita dall'utente.

  6. Per passare al passaggio successivo, fai clic su Avanti.

  7. Nel riquadro Scegli i log da includere nell'avviso, controlla la query e i risultati facendo clic su Anteprima dei log.

    Ti consigliamo di creare la query nel riquadro Query di Esplora log. In questo riquadro viene visualizzata anche la query che hai creato nel riquadro Query.

    Se necessario, puoi modificare la query in questo riquadro. Se modifichi la query, controlla i risultati facendo clic su Anteprima dei log.

  8. Fai clic su Avanti.

  9. Seleziona il tempo minimo tra le notifiche. Questo valore ti consente di controllare il numero di notifiche che ricevi da questo avviso se viene attivato più volte. Per questo esempio, seleziona 5 min dalle opzioni.

  10. (Facoltativo) Seleziona la durata della chiusura automatica degli incidenti. Per impostazione predefinita, la durata della chiusura automatica degli incidenti è impostata su 7 giorni.

  11. Fai clic su Avanti.

  12. Seleziona uno o più canali di notifica per il tuo avviso. In questo esempio, seleziona un canale di notifica via email.

    Se hai già configurato un canale di notifica via email, puoi selezionarlo dall'elenco. In caso contrario, fai clic su Gestisci canali di notifica e aggiungi un canale email. Per informazioni sulla creazione di canali di notifica, consulta Crea e gestisci i canali di notifica.

  13. Fai clic su Salva.

L'avviso basato su log è ora pronto per essere testato. Per istruzioni su come testare l'avviso, consulta Testa la policy di avviso basata sui log di esempio.

Passaggi successivi