Monitorar dbt Projects on Snowflake

Este tópico explica como você pode usar os recursos de monitoramento do dbt Projects on Snowflake para inspecionar execuções de projetos dbt, manuais ou agendadas por tarefa, e visualizar logs e artefatos.

Seção

Descrição

Habilitação de recursos de monitoramento para objetos de projetos dbt

Capture eventos de registro e rastreamento para um objeto de projeto dbt e para qualquer tarefa agendada que o execute. Para habilitar esse recurso, você deve definir o registro em log, o rastreamento e as métricas no esquema em que a tarefa e o objeto de projeto dbt são implantados.

Monitoramento das execuções programadas dos objetos de projeto dbt

No Snowsight, no menu de navegação, selecione Transformation » dbt Projects para visualizar o histórico de execução, gráficos de tarefas e detalhes de consulta para objetos de projeto dbt. Quando um espaço de trabalho está conectado a um objeto de projeto dbt que é executado de acordo com um cronograma de tarefas, você pode abrir o histórico de execuções e os gráficos das tarefas de dentro do espaço de trabalho.

Acesso programático a artefatos e logs do dbt

Use a função de tabela DBT_PROJECT_EXECUTION_HISTORY e as funções do sistema dbt para acessar artefatos e logs de dbt programaticamente.

Habilitação de recursos de monitoramento para objetos de projetos dbt

Para habilitar os recursos de monitoramento para seu objeto de projeto dbt, defina LOG_LEVEL, TRACE_LEVELe METRIC_LEVEL no banco de dados e no esquema em que o objeto de projeto dbt foi criado, conforme mostrado no seguinte exemplo de SQL:

ALTER SCHEMA my_db.my_dbt_project_schema SET LOG_LEVEL = 'INFO';
ALTER SCHEMA my_db.my_dbt_project_schema SET TRACE_LEVEL = 'ALWAYS';
ALTER SCHEMA my_db.my_dbt_project_schema SET METRIC_LEVEL = 'ALL';

Monitoramento das execuções programadas dos objetos de projeto dbt

Se você executar um objeto de projeto dbt implantado em um cronograma usando uma tarefa, e a tarefa estiver no mesmo esquema que o objeto de projeto dbt, você poderá visualizar as tarefas agendadas diretamente do espaço de trabalho selecionando Connect e depois View Schedules.

Nota

Esse recurso está disponível apenas para espaços de trabalho conectados a um objeto de projeto dbt.

Para monitorar a execução programada de um objeto de projeto dbt de um espaço de trabalho:

  1. No menu do projeto dbt, no lado direito do painel do projeto, em:ui:Scheduled runs, escolha:ui:View schedules.

  2. Na lista, selecione o cronograma (tarefa) que você quer inspecionar e, em seguida, escolha View details.

    O painel de informações da tarefa é aberto, no qual você pode visualizar os Task details, a tarefa Graph (se aplicável) e o Run History da tarefa. Para obter mais informações, consulte View tasks and task graphs in Snowsight.

  3. Na seção Run History de qualquer execução de objeto de projeto dbt programado na lista, selecione o botão Open query history na extremidade direita para ver os detalhes, o perfil e a telemetria da consulta referentes à execução. Para obter mais informações, consulte Revisão dos detalhes e do perfil de uma consulta específica.

Monitoramento de objetos de projeto dbt na Snowsight

Para ver informações detalhadas de monitoramento sobre execuções de objetos de projeto dbt, navegue até Transformations » dbt Projects no Snowsight. Você deve usar uma função com o privilégio MONITOR para visualizar as informações de monitoramento do objeto do projeto dbt. Para obter mais informações, consulte Controle de acesso para projetos de dbt no Snowflake.

  1. No menu de navegação, selecione Transformation » dbt Projects. Um histograma mostra a frequência das execuções de objetos de projetos dbt e uma lista dos projetos que foram executados.

    A lista de objetos de projetos dbt inclui colunas com as informações a seguir. É possível filtrar a lista por intervalo de datas, comando e status da execução.

    • PROJECT: o nome do objeto de projeto dbt e o número de execuções no período selecionado.

    • LAST COMMAND: o comando dbt executado durante a última execução.

    • LAST RUN STATUS: o resultado da execução: Succeeded, Executing ou Failed.

    • LAST RUN: o tempo decorrido desde a última execução. Para inverter a ordem de classificação, selecione o cabeçalho da coluna. A execução mais recente é mostrada primeiro por padrão.

    • PREVIOUS RUNS: o número de execuções no período selecionado por status.

    • DATABASE e SCHEMA: o banco de dados e o esquema em que o objeto de projeto dbt foi salvo.

    • LAST RUN PARAMETERS: os argumentos da linha de comando dbt (ARGS) especificados no comando EXECUTE DBT PROJECT da última execução do objeto de projeto dbt.

  2. Para inspecionar execuções individuais de projetos, selecione um objeto de projeto dbt na lista.

    A página de detalhes do objeto do projeto dbt no explorador de objetos do banco de dados é aberta para esse objeto de projeto dbt.

    A guia Run History está selecionada por padrão, com as seguintes informações para cada execução de trabalho no período selecionado:

    • COMMAND: o comando dbt executado durante a última execução.

    • STATUS: o resultado da execução: Succeeded, Executing ou Failed.

    • RUN TIME: o tempo decorrido desde a última execução. Para inverter a ordem de classificação, selecione o cabeçalho da coluna. A execução mais recente é mostrada primeiro por padrão.

    • PARAMETERS: os argumentos da linha de comando dbt (ARGS) especificados no comando EXECUTE DBT PROJECT da última execução do objeto de projeto dbt.

  3. Para ver os detalhes de uma execução, selecione-a na lista.

    A página Query Details é aberta para a consulta EXECUTEDBTPROJECT executada. Essa página inclui as seguintes guias:

    • Query Details: exibe o status de execução, horário de início, horário de término, duração, tamanho do warehouse, ID da consulta, e o texto SQL do comando EXECUTEDBTPROJECT. Também mostra resultados por modelo para o comando dbt executado (por exemplo,``build``), incluindo cada nome de modelo, tempo gasto e status.

    • Query Profile: mostra o plano de execução da consulta e as estatísticas de desempenho.

    • Query Telemetry: mostra dados de telemetria para a execução.

    • DAG: visualiza os modelos executados durante a execução e os resultados. Para obter mais informações, consulte Visualizar o DAG do histórico de consultas.

    Para obter mais informações, consulte Revisão dos detalhes e do perfil de uma consulta específica.

Visualizar o DAG do histórico de consultas

O Query Details de uma execução de objeto de projeto dbt inclui uma guia DAG que visualiza o que foi executado durante a execução e os resultados para cada modelo. Isso difere do DAG na página de detalhes do projeto, que serve como uma camada de documentação para o seu projeto, incluindo modelos, testes, fontes e as dependências deles.

O histórico de consultas do DAG é criado a partir dos artefatos manifest.json e run_results.json produzidos durante uma execução. Selecione um nó no DAG para abrir um painel lateral com detalhes para essa consulta específica, incluindo o ID da consulta e as mensagens de erro se a consulta falhar.

Para visualizar o DAG do histórico de consultas:

  1. No menu de navegação, selecione Transformations » dbt Projects.

  2. Na lista de objetos de projetos dbt, selecione um.

  3. Na guia Run History, selecione uma execução para abrir o Query Details correspondente.

  4. Selecione a guia DAG.

Nota

Se o histórico de consultas DAG mostrar «No data available», é provável que a execução tenha falhado antes que o run_results.json pudesse ser gerado. Para obter mais informações, consulte Limitações para o DAG de histórico de consultas.

Acesso programático a artefatos e logs do dbt

Use a função de tabela DBT_PROJECT_EXECUTION_HISTORY e as funções do sistema a seguir para acessar artefatos e logs de dbt programaticamente.

Função

O que ela retorna

Uso comum

Notas

SYSTEM$GET_DBT_LOG

Saída de log de texto (a parte final do log de execução)

Depuração rápida em SQL. Por exemplo, veja os erros e avisos sem baixar os arquivos.

Retorna o conteúdo do log. Nada é criado ou movido.

SYSTEM$LOCATE_DBT_ARTIFACTS

Caminho da pasta (por exemplo, snow://…/results/query_id_…/) com os arquivos de artefatos, como manifest.json, SQL compilado e logs.

Navegar ou copiar arquivos específicos com LIST, GET ou COPY FILES.

Apenas um localizador (URL). Você ainda executa GET/COPY FILES para a busca.

SYSTEM$LOCATE_DBT_ARCHIVE

URL do arquivo ZIP único (por exemplo, …/dbt_artifacts.zip).

Útil quando você deseja baixar um arquivo (por exemplo, com GET).

Use GET "<url>" arquivo:///local/dir para o download.

Obtenção de logs e download de arquivo ZIP da consulta de projeto dbt mais recente

O exemplo a seguir consulta o histórico de execução do dbt do Snowflake para mostrar o ID da consulta mais recente para o objeto de projeto dbt. Ele extrai a saída do log e retorna o local dos artefatos de dbt compactados para essa execução.

O exemplo da Snowflake CLI baixa o arquivo ZIP dos artefatos ou arquivos específicos (como manifest.json) para sua pasta local usando GET.

Para baixar o arquivo ZIP do Snowsight, navegue até Transformations » dbt Projects, selecione seu projeto e, em seguida, selecione uma execução para navegar até Query Details e selecione Download Build Artifacts em dbt Output.

Você deve usar uma função com o privilégio OWNERSHIP, USAGE ou MONITOR em seus objetos de projetos dbt.

Dica

Use argumentos de função, como DATABASE, SCHEMA e OBJECT_NAME, para filtrar os resultados sempre que possível. Esses filtros são aplicados antes de RESULT_LIMIT (padrão: 100 linhas), portanto usá-los garante que você tenha os resultados mais relevantes em vez de filtrar um conjunto de resultados possivelmente truncado com uma cláusula WHERE.

--Look up the most recent dbt project object execution
SET latest_query_id = (SELECT query_id
   FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.DBT_PROJECT_EXECUTION_HISTORY(
     DATABASE => 'ANALYTICS_DB',
     SCHEMA => 'DBT_PROD',
     OBJECT_NAME => 'FINANCE_ANALYTICS'
   ))
   ORDER BY query_end_time DESC LIMIT 1);

--Get the dbt run logs for the most recent dbt project object execution
SELECT SYSTEM$GET_DBT_LOG($latest_query_id);

============================== 15:14:53.100781 | 46d19186-61b8-4442-8339-53c771083f16 ==============================
[0m15:14:53.100781 [info ] [Dummy-1   ]: Running with dbt=1.9.4
...
[0m15:14:58.198545 [debug] [Dummy-1   ]: Command `cli run` succeeded at 15:14:58.198121 after 5.19 seconds

Para visualizar o caminho da área de preparação em que o Snowflake armazenou os artefatos de execução do objeto de projeto dbt, use a função SYSTEM$LOCATE_DBT_ARTIFACTS. Depois disso, você poderá usar esse caminho com GET ou COPY FILES com a Snowflake CLI para baixar elementos como manifest.json, SQL compilado ou logs.

--Get the location of the dbt project object archive ZIP file (see all files)
SELECT SYSTEM$LOCATE_DBT_ARTIFACTS($latest_query_id);

+-------------------------------------------------------------------------------------------------+
| SYSTEM$LOCATE_DBT_ARTIFACTS($LATEST_QUERY_ID)                                                   |
+-------------------------------------------------------------------------------------------------+
| snow://dbt/TESTDBT.PUBLIC.MY_DBT_PROJECT/results/query_id_01c01096-010c-0ccb-0000-a99506bd199e/ |
+-------------------------------------------------------------------------------------------------+

--List all the files of a dbt run
ls 'snow://dbt/TESTDBT.PUBLIC.MY_DBT_PROJECT/results/query_id_01bf3f5a-010b-4d87-0000-53493abb7cce/';

Você também pode criar uma nova área de preparação interna, localizar o caminho gerenciado pelo Snowflake para os artefatos da execução do objeto de projeto dbt especificado e copiar esses artefatos para a sua área de preparação para recuperação, conforme mostrado no exemplo a seguir:

CREATE OR REPLACE STAGE my_dbt_stage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');

SELECT SYSTEM$LOCATE_DBT_ARTIFACTS($latest_query_id);

snow://dbt/TESTDBT.PUBLIC.MY_DBT_PROJECT/results/query_id_01bf51c1-010b-5676-0000-53493ae6db02/

COPY FILES INTO @my_dbt_stage/results/ FROM 'snow://dbt/TESTDBT.PUBLIC.MY_DBT_PROJECT/results/query_id_01bf51c1-010b-5676-0000-53493ae6db02/';

results/dbt_artifacts.zip
results/logs/dbt.log
results/target/manifest.json
results/target/semantic_manifest.json