监控 dbt Projects on Snowflake

本主题说明如何使用 Snowflake 上 dbt Projects on Snowflake 的监控功能来检查 dbt 项目执行情况（无论是手动执行还是任务调度执行），以及如何查看日志和工件。

部分

描述

为 dbt 项目对象启用监控功能

获取 dbt 项目对象以及运行该对象的任何计划任务的日志记录和跟踪事件。要启用此功能，您必须在部署 dbt 项目对象和任务的架构上设置日志记录、跟踪和指标。

监控 dbt 项目对象的按计划执行情况

在 Snowsight 中，在左侧导航菜单中，选择 Transformation » dbt Projects 以查看 dbt 项目对象的运行历史记录、任务图和查询详细信息。当工作区连接到根据任务计划运行的 dbt 项目对象时，您可以从工作区中打开任务运行历史记录和任务图。

以编程方式访问 dbt 工件和日志

使用 DBT_PROJECT_EXECUTION_HISTORY 表函数和 dbt 系统函数，以编程方式访问 dbt 工件和日志。

为 dbt 项目对象启用监控功能

要针对您的 dbt 项目对象启用监控功能，请在创建 dbt 项目对象的数据库和架构上设置 LOG_LEVEL、TRACE_LEVEL 和 METRIC_LEVEL，如以下 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';

监控 dbt 项目对象的按计划执行情况

如果您使用任务定期执行已部署的 dbt 项目对象，且该任务与 dbt 项目对象位于同一模式中，则可以通过选择 Connect 然后选择 View Schedules，直接从工作区查看计划任务。

备注

此功能仅适用于连接到 dbt 项目对象的工作区。

从工作区监控 dbt 项目对象的按计划执行情况：

  1. 在项目窗格右侧的 dbt 项目菜单中，在 Scheduled runs 下选择 View schedules。

  2. 从列表中，选择要检查的计划（任务），然后选择 View details。

    任务的信息窗格将会打开，您可以在其中查看 Task details、任务 Graph`（如果适用）和该任务的 :ui:`Run History。有关更多信息，请参阅 View tasks and task graphs in Snowsight。

  3. 在列表中针对任何计划的 dbt 项目对象执行，从其 Run History 中选择最右侧的 Open query history 按钮，以查看运行的查询详细信息、查询配置文件和查询遥测。有关更多信息，请参阅 查看特定查询的详细信息和配置文件。

在 Snowsight 中监控 dbt 项目对象

要查看 dbt 项目对象执行的详细监控信息，请在 Snowsight 中导航至 Transformations » dbt Projects。您必须使用具有 MONITOR 权限的角色才能查看 dbt 项目对象的监控信息。有关更多信息，请参阅 Snowflake 上 dbt 项目的访问控制。

  1. 在导航菜单中，选择 Transformation » dbt Projects。直方图显示 dbt 项目对象执行频率和已运行的项目列表。

    dbt 项目对象列表包含具有以下信息的列。您可以按日期范围、命令和运行状态筛选列表。

    • PROJECT – dbt 项目对象的名称和所选时间段内的执行（运行）次数。

    • LAST COMMAND – 在上次运行期间执行的 dbt 命令。

    • LAST RUN STATUS – 运行的结果：Succeeded、Executing 或 Failed。

    • LAST RUN – 自上次运行以来经过的时间。要反转排序顺序，请选择列标题。默认情况下，最先显示最近的运行。

    • PREVIOUS RUNS – 按状态排列所选时间段内的运行次数。

    • DATABASE 和 SCHEMA – 用于保存 dbt 项目对象的数据库和架构。

    • LAST RUN PARAMETERS – 在上次 dbt 项目对象执行的 EXECUTE DBT PROJECT 命令中指定的 dbt 命令行实参 (ARGS)。

  2. 要检查单个项目运行，请从列表中选择 dbt 项目对象。

    数据库对象资源管理器中会打开该 dbt 项目对象的 dbt 项目对象详细信息页面。

    默认情况下，Run History 选项卡处于选中状态，其中包含在所选时间段内每个作业运行的以下信息：

    • COMMAND – 在上次运行期间执行的 dbt 命令。

    • STATUS – 运行的结果：Succeeded、Executing 或 Failed。

    • RUN TIME – 自上次运行以来经过的时间。要反转排序顺序，请选择列标题。默认情况下，最先显示最近的运行。

    • PARAMETERS 在上次 dbt 项目对象执行的 EXECUTE DBT PROJECT 命令中指定的 dbt 命令行实参 (ARGS)。

  3. 要查看某次运行的详情，请从列表中将其选中。

    系统将打开运行该 EXECUTE DBT PROJECT 查询的 Query Details 页面。此页面包含以下选项卡：

    • Query Details – 显示执行状态、开始时间、结束时间、时长、仓库规模、查询 ID，以及 EXECUTE DBT PROJECT 命令的 SQL 文本。还会显示所运行 dbt 命令的各个模型结果（例如 build），包括每个模型的名称、耗时和状态。

    • Query Profile – 显示查询执行计划和性能统计信息。

    • Query Telemetry – 显示执行的遥测数据。

    • DAG – 可视化执行过程中运行的模型及其结果。有关更多信息，请参阅 查看查询历史记录 DAG。

    有关更多信息，请参阅 查看特定查询的详细信息和配置文件。

查看查询历史记录 DAG

dbt 项目对象执行的 Query Details 包含一个 DAG 选项卡，用于可视化执行过程和每个模型的结果。这与项目详细信息页面上的 DAG 不同，后者是项目的文档层，包含模型、测试、源及其依赖关系。

查询历史记录 DAG 是根据执行期间生成的 manifest.json 和 run_results.json 工件构建的。在 DAG 中选择一个节点可打开侧面板，查看该特定查询的详细信息，包括查询 ID 以及失败时的错误消息。

要查看查询历史记录 DAG，请执行以下操作：

  1. 在导航菜单中，选择 Transformations » dbt Projects。

  2. 从 dbt 项目对象列表中选择一个项目。

  3. 在 Run History 选项卡中，选择一次运行记录以打开该执行对应的 Query Details。

  4. 选择 DAG 选项卡。

备注

如果查询历史记录 DAG 显示“No data available”，则该次运行可能在生成 run_results.json 之前就已失败。有关更多信息，请参阅 查询历史记录 DAG 的限制。

以编程方式访问 dbt 工件和日志

使用 DBT_PROJECT_EXECUTION_HISTORY 表函数和以下系统函数，以编程方式访问 dbt 工件和日志。

函数

返回的内容

典型用途

备注

SYSTEM$GET_DBT_LOG

文本日志输出（运行的日志尾部）

在 SQL 中进行快速调试。例如，在不下载文件的情况下查看错误和警告。

返回日志内容；不会创建或移动任何内容。

SYSTEM$LOCATE_DBT_ARTIFACTS

文件夹路径（例如， snow://…/results/query_id_…/），包含工件文件，例如 manifest.json、已编译 SQL、日志。

通过 LIST、 GET或 COPY FILES 浏览或复制特定文件。

仅提供定位功能 (URL)；您仍需执行 GET/COPYFILES 来提取。

SYSTEM$LOCATE_DBT_ARCHIVE

单个 ZIP 文件 URL （例如， …/dbt_artifacts.zip）。

当您想下载一个文件时（例如，使用 GET）非常方便。

使用 GET '<url>' file:///local/dir 进行下载。

获取日志并下载最新 dbt 项目查询的 ZIP 文件

以下示例查询 Snowflake 的 dbt 执行历史记录，以显示 dbt 项目对象的最新查询 ID。它会提取该执行的日志输出，并返回该执行的压缩 dbt 工件的位置。

The Snowflake CLI 示例使用 GET 请求将工件 ZIP 件或特定文件（如 manifest.json）下载到本地文件夹。

要从 Snowsight 下载 ZIP 文件，请导航至 Transformations » dbt Projects，选择您的项目，然后选择一次执行记录进入 Query Details，然后在 dbt Output 下选择 Download Build Artifacts。

您必须使用对 dbt 项目对象具有 OWNERSHIP、USAGE 或 MONITOR 权限的角色。

小技巧

尽可能使用 DATABASE、SCHEMA 和 OBJECT_NAME 等函数实参来筛选结果。这些筛选器会先于 RESULT_LIMIT``（默认值：100 行）执行，因此使用它们可以确保您获得最相关的结果，而不是在可能已被截断的结果集上使用 ``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

要查看 Snowflake 存储 dbt 项目对象执行工件的暂存区路径，请使用 SYSTEM$LOCATE_DBT_ARTIFACTS 函数。然后，您可以在 Snowflake CLI 中使用该路径配合 GET 或 COPY FILES，下载诸如 manifest.json、已编译的 SQL 或日志等内容。

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

您还可以创建一个新的内部暂存区，找到指定 dbt 项目对象执行工件的 Snowflake 管理路径，并将这些工件复制到暂存区中进行检索，如以下示例所示：

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