Cortex Framework 可观测性

为了成功运行和运营企业级数据平台，了解流水线执行情况、数据质量和运营错误至关重要。

Cortex Framework 将可观测性分为两个不同的生命周期：

  1. 部署时可观测性：在执行 CLI 工具期间跟踪配置加载、模板编译、验证检查、部署操作和 API 遥测。
  2. 运行时可观测性：跟踪在 Google Cloud内运行的已部署数据流水线的执行情况、流水线进度、查询性能、数据质量断言和自动提醒。

部署时可观测性

部署时可观测性侧重于 CLI 工具（例如 uv run cortex-build、uv run cortex-deploy、uv run cortex-build-and-deploy、uv run cortex-demo、uv run cortex-kc-sync）的执行。

本地控制台日志记录

当您运行 CLI 命令时，Cortex Framework 会将进度直接记录到控制台 (stdout)。

  • 日志级别：默认情况下，日志以 INFO 级别输出。
  • 视觉突出显示：消息采用颜色编码，可动态突出显示错误和警告：
    • ❌ 错误（红色）：表示导致执行停止的严重故障。
    • ⚠️ 警告（橙色）：表示可能存在配置异常或非阻塞性问题。
  • 时间戳和来源：每行日志都会显示执行时间和活跃的 Python 类或模块名称，以便进行精确的跟踪。

持久性本地日志文件

每次执行命令时，Python 编排器都会自动将完整的执行日志流式传输到系统临时目录中的临时日志文件：

/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log

在启动 CLI 工具期间，系统会将确切路径输出到控制台。这些文件包含全面的日志详细信息（包括意外错误的堆栈轨迹），对于调试 CLI 工具执行期间遇到的问题或在附加到支持请求时非常有用。

Google Cloud 环境验证

在执行 build、deploy 或 sync 操作之前，编排引擎会执行 GcpEnvironmentChecker 实用程序。此检查会验证：

  1. 必需的 API：确认关键 Google Cloud API 已启用（例如 bigquery.googleapis.com、dataform.googleapis.com）。
  2. 数据集存在性：验证所需的原始数据集和目标数据集是否存在或是否可以创建。
  3. 位置和区域：确保目标数据集与源数据集的地理区域相匹配。
  4. 容量和设置：验证预订设置和目录配置。

任何不匹配都会记录为错误，并提供有关如何在发出 Google Cloud 服务调用之前解决这些问题的建议提示。

Telemetry

在部署和同步过程中，Cortex Framework 会将匿名采用情况、变体和框架版本遥测数据记录到 Google Cloud。如需详细了解此功能的运作方式以及如何选择停用，请参阅遥测。

运行时可观测性

构建并部署后，Cortex Framework 符合规范的数据层和数据产品完全在 Dataform 和 BigQuery 中运行。因此，运行时可观测性直接与 Google Cloud 运营套件集成。

流水线执行日志记录

所有已部署的流水线都会使用 Cloud Logging 和执行工具进行跟踪：

  • Dataform 执行日志：Dataform 会记录每次编译和执行事件。您可以在 Google Cloud 控制台中或使用 Dataform API 以编程方式访问这些详细信息。
  • BigQuery 作业历史记录：由 Dataform 流水线具体化的每个表和视图都会在 BigQuery 中执行 SQL 查询。详细的资源使用情况、查询性能、处理的字节数和执行时间戳会记录在 BigQuery 作业历史记录中。

流水线监控

您可以通过直观方式或以编程方式监控流水线健康状况、发布配置和运行历史记录：

  1. Dataform 网页界面：前往 Dataform 控制台，执行以下操作：
    • 检查已编译的数据模型并直观呈现已编译的图。
    • 验证发布配置、已编译模板和有效环境的状态。
    • 监控当前和过去的工作流执行历史记录和详细信息。
  2. Cloud Monitoring 集成：通过自定义信息中心面板跟踪 Dataform 流水线指标，例如执行时长、有效编译和工作流作业失败率。

提醒和数据质量

为确保数据完整性并自动标记流水线故障，请使用以下机制配置提醒：

数据质量断言

您可以通过创建 .sqlx 断言文件来定义自定义数据验证规则（例如，确保列永远不为 null、检查主键是否唯一或验证数值范围）。

  • 您可以使用 --assertions 参数提供自定义断言文件： bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
  • 在流水线执行期间，Dataform 会运行这些验证查询。如果断言查询返回一行或多行，则验证失败，并且流水线执行会立即标记为失败。
  • 如需详细了解如何编写数据验证规则，请参阅有关 Dataform 断言的官方文档。

断言文件示例 (assertions.sqlx)

用于检查 NULL 值和重复客户记录的 Dataform 断言查询示例。如果此查询返回任何行，断言将失败并停止执行工作流：

config {
  type: "assertion",
  description: "Ensure customer_number_kunnr is not null and unique"
}

-- Check for NULL values
(
  SELECT
    "customer_number_kunnr is NULL" AS error_message
  FROM
    ${ref("customers")}
  WHERE
    customer_number_kunnr IS NULL
)
UNION ALL
-- Check for duplicate keys
(
  SELECT
    CONCAT("Duplicate customer number found: ", customer_number_kunnr) AS error_message
  FROM
    ${ref("customers")}
  GROUP BY
    customer_number_kunnr,
    client_mandt
  HAVING
    COUNT(*) > 1
)

Cloud Alerting 政策

设置标准Google Cloud 提醒政策，以便在出现问题时通知您的工程或运营团队：

  • 基于日志的提醒：在 Cloud Logging 中创建提醒，以便在日志中检测到错误事件、工作流执行失败或编译器问题时触发提醒。
  • 基于指标的提醒：在 Cloud Monitoring 中根据执行时长或编译失败情况定义阈值。
  • 通知渠道：配置这些提醒，以便将问题路由到团队首选的沟通渠道