监控并对 DCM Projects 进行故障排除

本主题介绍如何监控 DCM 部署，并对执行失败 DCM 计划执行故障排除。

对 DCM project 进行故障排除

如果您不熟悉 DCM project，可能会因配置错误或其他常见陷阱而遇到报错。本部分将介绍这些错误及其解决方法。

常见错误原因

下表列出了 DCM project 执行过程中常见的错误原因：

错误类别

常见原因

次要角色

  • 用户在运行 DCM 命令时，可能会在无意中使用次要角色权限，从而导致行为不一致。

角色权限不足

  • 角色权限不足，无法创建已定义的对象类型

  • 角色权限不足，无法修改或删除已被其他角色拥有的现有对象

  • 角色权限不足，无法使用系统 DMFs

  • 角色权限不足，无法运行仓库以在创建动态表时进行刷新

Jinja 渲染问题

  • Jinja 语法不正确导致的 Jinja 渲染问题

  • 值类型不匹配导致的 Jinja 渲染问题

项目问题

  • 清单路径不正确

  • 定义文件夹为空

  • 定义文件位于错误的仓库分支上且版本过旧

  • 已被其他 DCM project 部署的对象

  • 项目与对象引用不匹配

观察与审计 DCM project 部署

DCM Projects 旨在为账户基础设施的所有变更提供完整的透明度和审计追踪能力。这就要求您遵循若干软件开发最佳实践，来设置基础设施部署流程。有关更多信息，请参阅 自动化 DCM project 部署。

您可以通过以下来源查看历史部署记录：

  • 存储在 DCM project 中的 部署工件

  • 部署历史记录

  • 来自 DCM project 的 :ref:`label-dcm_projects_event_logging`（取决于日志级别设置）

部署工件

对于每次执行的部署，系统都会在 DCM project 中保存一份不可变的部署工件快照，其中包含以下信息：

  • 清单文件 (manifest.yml)

  • sources 文件夹内的所有对象定义文件和宏文件（.sql 文件）

  • PLAN 操作 (plan_result.json) 和 DEPLOY 操作 (deploy_result.json) 的输出，包括：

    • 本次部署所使用的模板变量

    • 部署元数据，包括时间戳、对象名称和查询 ID

    • 变更集

这组完整信息使得所有部署操作均可复现，便于调试、审计或重新部署所定义的状态。

以下命令可用于观察和审计 DCM project：

  • 拥有 MONITOR 权限后，您可以：

    • 列出存储在 DCM project 中的所有部署。

    • 列出指定部署中的所有文件。

    • 读取、复制或下载该部署中的特定文件。

  • 拥有 OWNERSHIP 权限后，如果某个部署包含敏感数据，您可以手动将其删除。

  • 拥有 READ 权限后，您可以运行 DESCRIBE 命令，查看指定 DCM project 的最新部署名称、别名和时间戳。

命令示例：

DESCRIBE DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV;

SHOW DEPLOYMENTS IN DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV;

LIST 'snow://project/DCM_DEMO.PROJECTS.DCM_PROJECT_DEV/deployments/DEPLOYMENT$1/';

ALTER DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV DROP DEPLOYMENT DEPLOYMENT$1;

部署历史记录

DCM_DEPLOYMENT_HISTORY Information Schema 表函数提供了基于角色的访问权限和低延迟方式，用于查看选定 DCM project 的成功与失败部署。

有关完整的语法、实参、输出列和示例，请参阅 DCM_DEPLOYMENT_HISTORY 参考。

SELECT *
FROM
  TABLE (DCM_DEMO.INFORMATION_SCHEMA.DCM_DEPLOYMENT_HISTORY(
    project_name => 'DCM_DEMO.PROJECTS.DCM_PROJECT_DEV',
    result_limit => 50
  ));

事件日志

您可以在 DCM project 对象上设置所需的 LOG_LEVEL，也可以从父架构、数据库或账户继承已定义的 LOG_LEVEL。

如果已为 DCM project 设置了 LOG_LEVEL，则执行失败的 PLAN 和 DEPLOY 会将其对应的错误信息作为事件记录到日志中，您可以通过查询已定义的事件表来查看这些事件。有关设置事件表和日志级别的更多信息，请参阅 事件表概述。

例如：

SELECT
  TIMESTAMP,
  RESOURCE_ATTRIBUTES:"snow.executable.name" ::STRING AS PROJECT_NAME,
  CASE
    WHEN RESOURCE_ATTRIBUTES:"snow.project.dcm.execution.command" ::STRING = 'plan' THEN 'PLAN'
    WHEN RESOURCE_ATTRIBUTES:"snow.project.dcm.execution.command" ::STRING = 'deploy' THEN 'DEPLOY'
    ELSE RESOURCE_ATTRIBUTES:"snow.project.dcm.execution.command" ::STRING
  END AS COMMAND,
  CASE
    WHEN VALUE:"state" ::STRING = 'SUCCEEDED' THEN 'SUCCEEDED'
    WHEN VALUE:"state" ::STRING = 'FAILED' THEN 'FAILED'
    ELSE VALUE:"state" ::STRING
  END AS STATUS,
  COALESCE(
    CONCAT('Error message: ',VALUE:"message"::STRING),
    VALUE:"operation"::STRING)
  AS OPERATIONS,
  RESOURCE_ATTRIBUTES:"snow.session.role.primary.name" ::STRING AS ROLE,
  RESOURCE_ATTRIBUTES:"db.user" ::STRING AS USER_NAME,
  RECORD:"severity_text" ::STRING AS SEVERITY
FROM
  SNOWFLAKE.TELEMETRY.EVENTS
WHERE
  RESOURCE_ATTRIBUTES:"snow.executable.type" ::STRING = 'DCM_PROJECT'
ORDER BY
  TIMESTAMP DESC
LIMIT
  250;