Execuções de monitoramento

Esta página mostra como fazer o seguinte:

Antes de começar

Para monitorar os registros de execução, faça o seguinte:

  1. No Google Cloud console, acesse a página Dataform.

    Acesse o Dataform

  2. Selecione ou crie um repositório.

  3. Selecione ou crie um espaço de trabalho de desenvolvimento.

  4. Acione uma execução pelo menos uma vez.

Funções exigidas

Para receber as permissões necessárias para visualizar os registros de execução, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Editor do Dataform (roles/dataform.editor) no repositório do Dataform em que as execuções de fluxo de trabalho estão sendo rastreadas
  • Verificar a configuração de uma execução: Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

O papel do IAM de Visualizador de registros (roles/logging.viewer) oferece acesso somente leitura a todos os recursos do Cloud Logging. Para mais informações sobre as permissões e os papéis do Identity and Access Management que se aplicam aos dados do Logging, consulte Controle de acesso com o IAM.

Para criar e gerenciar alertas com base em registros, verifique se o papel do IAM inclui as permissões descritas em Papéis necessários para criar e usar políticas de alertas com base em registros.

Monitorar registros de execução

Nesta seção, mostramos como visualizar registros de execução no Dataform.

É possível ver os registros de todas as execuções acionadas em um repositório e os registros de execuções acionadas em um espaço de trabalho nas últimas 24 horas.

Inspecionar registros de execução do repositório

Para ver os registros de todas as execuções acionadas em um repositório, siga estas etapas:

  1. No Google Cloud console, acesse a página Dataform.

    Acesse o Dataform

  2. Acesse o repositório.

  3. Clique em Registros de execução de fluxo de trabalho.

  4. Para conferir os detalhes de uma execução, clique nela.

  5. Para conferir os detalhes de uma ação na execução, clique em Ver detalhes.

Inspecionar registros de execução do espaço de trabalho

Para conferir os registros das 1.000 execuções mais recentes que foram acionadas em um espaço de trabalho nas últimas 24 horas, siga estas etapas:

  1. No Google Cloud console, acesse a página Dataform.

    Acesse o Dataform

  2. Acesse o repositório e selecione o espaço de trabalho.

  3. No espaço de trabalho, clique em Execuções.

  4. Para conferir os detalhes de uma execução, clique nela.

  5. Para conferir os detalhes de uma ação na execução, clique em Ver detalhes.

Acessar registros do Logging para o Dataform

Nesta seção, mostramos como visualizar os registros do Cloud Logging para invocações de fluxo de trabalho do Dataform.

Cada invocação de fluxo de trabalho do Dataform é registrada usando o Logging. A geração de registros é ativada automaticamente para invocações de fluxo de trabalho do Dataform, o que pode gerar cobranças de faturamento do Logging. Para mais informações, consulte Preços do Dataform.

Como visualizar registros

Para informações sobre como filtrar registros do Logging na Análise de registros, consulte Ver registros usando a Análise de registros.

Os registros do Dataform são indexados pelo repositório do Dataform.

Formato do registro

O Dataform envia mensagens de registro de invocação de fluxo de trabalho no seguinte 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"
}

O que é registrado

As entradas de registro do Dataform contêm informações úteis para monitorar e depurar as invocações de fluxo de trabalho.

As entradas de registro contêm os seguintes tipos de informações:

  • receiveTimestamp
  • release_config_id
  • repository_id
  • resource_container
  • workflow_invocation_id
  • workflow_config_id
  • severity: pode ser INFO, WARNING ou ERROR
  • terminalState: pode ser SUCCEEDED, CANCELED ou FAILED
  • timestamp
  • @type

Os registros de serviço do Dataform fornecem eventos de invocação de alto nível, como registros de conclusão de invocação de fluxo de trabalho. No entanto, esses registros do serviço não incluem códigos da tarefa individuais do BigQuery nem execuções de ações granulares no nível da tabela. Para recuperar detalhes granulares de execução no nível da ação e os códigos da tarefa do BigQuery correspondentes para uma invocação de fluxo de trabalho, consulte Correlacionar códigos da tarefa do BigQuery a invocações de fluxo de trabalho.

Configurar métricas e alertas com o Cloud Monitoring

Use o Monitoring para observar tendências nos registros e receber notificações quando as condições descritas ocorrerem.

Para fornecer ao Monitoring dados dos seus registros, o Logging oferece o seguinte:

  • Métricas com base em registros, que podem ser usadas da seguinte maneira:
    • Para criar políticas de alertas que avisem você sobre alterações ao longo do tempo.
    • Para criar gráficos que mostrem mudanças ao longo do tempo.
  • Alertas com base em registros, que notificam você sempre que um evento específico aparece em um registro.

Para mais informações sobre métricas com base em registros e alertas com base em registros, consulte Monitorar seus registros.

Para saber como configurar alertas com base em registros para invocações de fluxo de trabalho do Dataform, consulte Configurar alertas para invocações de fluxo de trabalho com falha.

Correlacionar jobs do BigQuery com invocações de fluxo de trabalho

Os registros de serviço do Dataform no tipo de recurso dataform.googleapis.com/Repository fornecem eventos de invocação de fluxo de trabalho de alto nível, como registros de conclusão de invocação de fluxo de trabalho. No entanto, esses registros de serviço não incluem execuções de ações granulares no nível da tabela ou IDs de jobs específicos do BigQuery.

Quando o Dataform executa ações como criar ou atualizar tabelas, visualizações ou declarações, ele envia jobs no BigQuery e anexa automaticamente rótulos a cada job. Também é possível recuperar o ID da tarefa do BigQuery para cada ação diretamente da API Dataform chamando o método workflowInvocations.query e inspecionando o campo bigqueryAction.jobId.

A tabela a seguir lista os rótulos de chave que o Dataform anexa aos jobs do BigQuery:

Chave de rótulo Descrição
dataform_workflow_execution_id O ID limpo da invocação do fluxo de trabalho do Dataform.
dataform_repository_id O ID limpo do repositório do Dataform.
dataform_workflow_execution_action_id_database O projeto de destino (banco de dados) da ação.
dataform_workflow_execution_action_id_schema O conjunto de dados de destino (esquema) da ação.
dataform_workflow_execution_action_id_name O nome da tabela, visualização ou declaração de destino da ação.

Para correlacionar jobs do BigQuery e detalhes de execução no nível da ação a uma invocação de fluxo de trabalho, faça o seguinte:

  1. Consiga o ID de invocação do fluxo de trabalho para sua execução. Para procurar o ID na Análise de registros, consulte um dos seguintes tipos de registro do Dataform:

    • Registros do workflow_invocation_completion (ativados por padrão): copie o valor do campo jsonPayload.workflowInvocationId da entrada de registro:

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

    • Registros de auditoria de acesso a dados do CreateWorkflowInvocation (se os registros de auditoria de acesso a dados estiverem ativados para as operações do DATA_WRITE): copie o segmento WORKFLOW_INVOCATION_ID no final do 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"

    Substitua REPOSITORY_ID pelo ID do repositório do Dataform.

  2. Para encontrar os jobs correlacionados do BigQuery, consulte os registros de auditoria do BigQuery na Análise de registros ou a visualização INFORMATION_SCHEMA.JOBS no BigQuery. Selecione uma das seguintes opções:

    Análise de registros

    1. No console do Google Cloud , acesse a página Análise de registros.

      Acessar a Análise de registros

    2. No painel Consulta, insira a seguinte consulta:

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

      Substitua WORKFLOW_INVOCATION_ID pelo ID de invocação do fluxo de trabalho.

    3. Clique em Executar consulta.

      A consulta retorna entradas de registro de jobs do BigQuery para essa invocação de fluxo de trabalho. Em cada entrada de registro, o campo protoPayload.metadata.jobChange.job.jobName contém o nome do recurso do job do BigQuery, e os campos jobStats e jobStatus fornecem estatísticas de execução e detalhes de status.

    BigQuery Studio

    1. No console do Google Cloud , acesse a página BigQuery Studio.

      Acessar o BigQuery Studio

    2. No Editor de consultas, execute esta consulta:

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

      Substitua:

      • LOCATION: o local do BigQuery em que os jobs foram executados, como us ou eu.
      • WORKFLOW_INVOCATION_ID: o ID de invocação do fluxo de trabalho.

Configurar alertas para invocações de fluxo de trabalho com falha

Nesta seção, mostramos como configurar alertas com base em registros para invocações de fluxo de trabalho do Dataform com falha usando a Análise de registros.

É possível usar o Monitoring para observar tendências nos registros do Logging para invocações de fluxo de trabalho do Dataform e receber notificações quando as condições descritas ocorrerem.

Cada invocação de fluxo de trabalho do Dataform é registrada usando o Logging. A geração de registros é ativada automaticamente para invocações de fluxo de trabalho do Dataform, o que pode gerar cobranças de faturamento do Logging. Para mais informações, consulte Preços do Dataform.

Para receber alertas quando uma invocação de fluxo de trabalho do Dataform falhar, crie alertas com base em registros.

É possível criar alertas com base em registros na página Análise de registros no console do Google Cloud ou usando a API Monitoring. Nesta seção, descrevemos como criar alertas com base em registros para falhas de invocação de fluxo de trabalho do Dataform usando a Análise de registros.

Para configurar alertas com base em registros para invocações de fluxo de trabalho do Dataform com falha, siga estas etapas:

  1. No console do Google Cloud , selecione Logging e, em seguida, Análise de registros.

    Acessar a Análise de registros

  2. No painel Consulta, selecione Mostrar consulta e insira a seguinte consulta:

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

    Essa consulta alerta você sobre todas as invocações de fluxo de trabalho do Dataform que falharam.

    1. Opcional: para filtrar as invocações de fluxo de trabalho com falha por uma configuração de versão, adicione o seguinte à consulta:

          jsonPayload.releaseConfigId="RELEASE_CONFIGURATION_ID"

      Substitua RELEASE_CONFIGURATION_ID pelo ID da configuração da versão.

    2. Opcional: para filtrar invocações de fluxo de trabalho com falha por uma configuração de fluxo de trabalho, anexe o seguinte à consulta:

          jsonPayload.workflowConfigId="WORKFLOW_CONFIGURATION_ID"

      Substitua WORKFLOW_CONFIGURATION_ID pelo ID da configuração do fluxo de trabalho.

    A consulta a seguir alerta você quando uma invocação de fluxo de trabalho do Dataform relacionada à configuração de lançamento daily e à configuração de fluxo de trabalho production falha:

     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. Opcional: para validar a consulta, use Executar consulta no painel Resultados da consulta.

  4. No cabeçalho do painel Resultados da consulta, clique em Criar alerta. Quando a janela é estreita, a opção Criar alerta pode aparecer no menu Ações.

  5. No painel Detalhes do alerta, forneça um nome e uma descrição para o alerta:

    1. Digite um nome para o alerta no campo Nome do alerta. Por exemplo, Dataform: workflow failure.

    2. Digite uma descrição deste alerta. Você também pode incluir informações que possam ajudar o destinatário de uma notificação a diagnosticar o problema. A string a seguir resume o motivo do alerta:

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

      Para saber como formatar e personalizar o conteúdo desse campo, consulte Anotar notificações com documentação definida pelo usuário.

  6. Para avançar para a próxima etapa, clique em Próxima.

  7. No painel Escolher registros a serem incluídos no alerta, verifique a consulta e os resultados clicando em Visualizar registros.

    Recomendamos criar a consulta no painel Consulta do Explorador de registros. A consulta que você criou no painel Consulta também é exibida nesse painel.

    É possível editar a consulta neste painel, se necessário. Se você editar a consulta, verifique os resultados clicando em Visualizar registros.

  8. Clique em Próxima.

  9. Selecione o tempo mínimo entre as notificações. Esse valor permite controlar o número de notificações recebidas desse alerta, se ele for acionado várias vezes. Neste exemplo, selecione 5 minutos nas opções.

  10. Opcional: selecione a duração do fechamento automático de incidentes. Por padrão, a duração do fechamento automático de incidentes é definida como 7 dias.

  11. Clique em Próxima.

  12. Selecione um ou mais canais de notificação para seu alerta. Neste exemplo, selecione um canal de notificação por e-mail.

    Se você já tiver um canal de notificação por e-mail configurado, selecione-o na lista. Caso contrário, clique em Gerenciar canais de notificação e adicione um canal de e-mail. Para saber como criar canais de notificação, consulte Criar e gerenciar canais de notificação.

  13. Clique em Salvar.

Seu alerta com base em registros está pronto para ser testado. Para instruções sobre como testar o alerta, consulte Testar o exemplo de política de alertas com base em registros.

A seguir