作业系统表参考

注意

lakeflow 架构以前称为 workflow。 这两个架构的内容是完全相同的。 若要使 lakeflow 架构可见,必须单独启用它。

本文是关于如何使用 lakeflow 系统表来监控您帐户中的作业的参考资料。 这些表包括帐户中部署在同一云区域内的所有工作区的记录。 若要查看另一个区域中的记录,必须查看该区域中部署的工作区中的表。

要求

  • system.lakeflow 架构必须由帐户管理员启用。请参阅 启用系统表架构
  • 若要访问这些系统表,用户必须:

可用的作业表

所有与作业相关的系统表都位于 system.lakeflow 架构中。 目前,该架构托管四个表:

说明 支持流式处理 免费保留期 包括全局或区域数据
作业(公共预览版) 跟踪在帐户中创建的所有作业 365 天 区域
job_tasks(公共预览版) 跟踪帐户中运行的所有作业任务 365 天 区域
job_run_timeline(公共预览版) 跟踪作业运行和相关元数据 365 天 区域
作业任务运行时间线(公共预览) 跟踪作业任务运行和相关元数据 365 天 区域

详细架构参考

以下各节为每个与作业相关的系统表提供架构引用。

作业表架构

jobs 表是渐变维度表(SCD2)。 当行发生更改时,系统会发出新行,以逻辑方式替换上一行。

表路径:system.lakeflow.jobs

列名称 数据类型 说明 说明
account_id string 此作业所属帐户的 ID
workspace_id string 此作业所属工作区的 ID
job_id string 作业 ID 仅在单个工作区中唯一
name string 作业名称由用户提供
description string 用户提供的作业说明 如果已配置客户管理的密钥,则此字段为空。

2024 年 8 月下旬之前发出的行不会填充该项
creator_id string 创建作业的主体的 ID
tags string 与此作业关联的用户提供的自定义标记
change_time timestamp 上次修改作业的时间 记录为 +00:00(UTC) 的时区
delete_time timestamp 用户删除任务的时间 记录为 +00:00(UTC) 的时区
run_as string 对作业运行使用其权限的用户或服务主体的 ID

示例查询

-- Get the most recent version of a job
SELECT
  *,
  ROW_NUMBER() OVER(PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
FROM
  system.lakeflow.jobs QUALIFY rn=1

作业任务表架构

作业任务表是一个渐变的维度表(SCD2)。 当行发生更改时,系统会发出新行,以逻辑方式替换上一行。

表路径:system.lakeflow.job_tasks

列名称 数据类型 说明 说明
account_id string 此作业所属帐户的 ID
workspace_id string 此作业所属工作区的 ID
job_id string 作业 ID 仅在单个工作区中唯一
task_key string 作业中任务的引用键 仅在单个作业中唯一
depends_on_keys array 此任务的所有上游依赖项的任务键
change_time timestamp 上次修改任务的时间 记录为 +00:00(UTC) 的时区
delete_time timestamp 用户删除任务的时间 记录为 +00:00(UTC) 的时区

示例查询

-- Get the most recent version of a job task
SELECT
  *,
  ROW_NUMBER() OVER(PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
FROM
  system.lakeflow.job_tasks QUALIFY rn=1

作业运行时间线表架构

作业运行时间线表是不可变的,在生成作业时完成。

表路径:system.lakeflow.job_run_timeline

列名称 数据类型 说明 说明
account_id string 此作业所属帐户的 ID
workspace_id string 此作业所属工作区的 ID
job_id string 作业 ID 此密钥仅在单个工作区中是唯一的
run_id string 作业运行的 ID
period_start_time timestamp 运行或时间段的开始时间 时区信息记录在值末尾,+00:00 表示 UTC
period_end_time timestamp 运行或时间段的结束时间 时区信息记录在值末尾,+00:00 表示 UTC
trigger_type string 可以触发运行的触发器类型 有关可能的值,请参阅触发器类型值
run_type string 作业运行的类型 有关可能的值,请参阅运行类型值
run_name string 与此次任务运行关联的用户提供的运行名称
compute_ids array 包含父作业运行的作业计算 ID 的数组 用于标识 WORKFLOW_RUN 运行类型使用的作业群集。 有关其他计算信息,请参阅 job_task_run_timeline 表。

2024 年 8 月下旬之前发出的行不会填充该项
result_state string 作业运行的结果 有关可能的值,请参阅 结果状态值
termination_code string 作业运行的终止代码 有关可能的值,请参阅终止代码值

2024 年 8 月下旬之前发出的行不会填充该项
job_parameters map 作业运行中使用的作业级别参数 此字段中不包括已弃用的 notebook_params 设置。

2024 年 8 月下旬之前发出的行不会填充该项

示例查询

-- This query gets the daily job count for a workspace for the last 7 days:
SELECT
  workspace_id,
  COUNT(DISTINCT run_id) as job_count,
  to_date(period_start_time) as date
FROM system.lakeflow.job_run_timeline
WHERE
  period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
GROUP BY ALL

-- This query returns the daily job count for a workspace for the last 7 days, distributed by the outcome of the job run.
SELECT
  workspace_id,
  COUNT(DISTINCT run_id) as job_count,
  result_state,
  to_date(period_start_time) as date
FROM system.lakeflow.job_run_timeline
WHERE
  period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
  AND result_state IS NOT NULL
GROUP BY ALL

-- This query returns the average time of job runs, measured in seconds. The records are organized by job. A top 90 and a 95 percentile column show the average lengths of the job's longest runs.
with job_run_duration as (
    SELECT
        workspace_id,
        job_id,
        run_id,
        CAST(SUM(period_end_time - period_start_time) AS LONG) as duration
    FROM
        system.lakeflow.job_run_timeline
    WHERE
      period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
    GROUP BY ALL
)
SELECT
    t1.workspace_id,
    t1.job_id,
    COUNT(DISTINCT t1.run_id) as runs,
    MEAN(t1.duration) as mean_seconds,
    AVG(t1.duration) as avg_seconds,
    PERCENTILE(t1.duration, 0.9) as p90_seconds,
    PERCENTILE(t1.duration, 0.95) as p95_seconds
FROM
    job_run_duration t1
GROUP BY ALL
ORDER BY mean_seconds DESC
LIMIT 100

-- This query provides a historical runtime for a specific job based on the `run_name` parameter. For the query to work, you must set the `run_name`.
SELECT
  workspace_id,
  run_id,
  SUM(period_end_time - period_start_time) as run_time
FROM system.lakeflow.job_run_timeline
WHERE
  run_type="SUBMIT_RUN"
  AND run_name = :run_name
  AND period_start_time > CURRENT_TIMESTAMP() - INTERVAL 60 DAYS
GROUP BY ALL

-- This query collects a list of retried job runs with the number of retries for each run.
with repaired_runs as (
    SELECT
    workspace_id, job_id, run_id, COUNT(*) - 1 as retries_count
    FROM system.lakeflow.job_run_timeline
    WHERE result_state IS NOT NULL
    GROUP BY ALL
    HAVING retries_count > 0
    )
SELECT
    *
FROM repaired_runs
ORDER BY retries_count DESC
    LIMIT 10;

作业运行时间线表架构

作业任务运行时间线表在生成时不可变并完成。

表路径:system.lakeflow.job_task_run_timeline

列名称 数据类型 说明 说明
account_id string 此作业所属帐户的 ID
workspace_id string 此作业所属工作区的 ID
job_id string 作业 ID 仅在单个工作区中唯一
run_id string 任务运行的 ID
job_run_id string 作业运行的 ID 2024 年 8 月下旬之前发出的行不会填充该项
parent_run_id string 父运行的 ID 2024 年 8 月下旬之前发出的行不会填充该项
period_start_time timestamp 任务的开始时间或时间段 时区信息记录在值末尾,+00:00 表示 UTC
period_end_time timestamp 任务的结束时间或时间段 时区信息记录在值末尾,+00:00 表示 UTC
task_key string 作业中任务的引用键 此密钥仅在单个作业中是唯一的
compute_ids array compute_ids数组包含作业任务使用的作业群集、交互式群集和 SQL 仓库的 ID
result_state string 工作任务执行的结果 有关可能的值,请参阅 结果状态值
termination_code string 任务运行的终止代码 有关可能的值,请参阅终止代码值

2024 年 8 月下旬之前发出的行不会填充该项

常见联接模式

以下部分提供了示例查询,这些查询突出显示了作业系统表的常用联接模式。

联接作业和作业运行时间线表

使用作业名称扩充作业运行

with jobs as (
    SELECT
        *,
        ROW_NUMBER() OVER (PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
    FROM system.lakeflow.jobs QUALIFY rn=1
)
SELECT
    job_run_timeline.*
    jobs.name
FROM system.lakeflow.job_run_timeline
    LEFT JOIN jobs USING (workspace_id, job_id)

联接作业运行时间线和使用情况表

使用作业运行元数据扩充每个计费日志

SELECT
    t1.*,
    t2.*
FROM system.billing.usage t1
    LEFT JOIN system.lakeflow.job_run_timeline t2
        ON t1.workspace_id = t2.workspace_id
            AND t1.usage_metadata.job_id = t2.job_id
            AND t1.usage_metadata.job_run_id = t2.run_id
            AND t1.usage_start_time >= date_trunc("Hour", t2.period_start_time)
            AND t1.usage_start_time < date_trunc("Hour", t2.period_end_time) + INTERVAL 1 HOUR
WHERE
    billing_origin_product="JOBS"

计算每次作业运行的成本

此查询与 billing.usage 系统表联接,以计算每个作业运行的成本。

with jobs_usage AS (
  SELECT
    *,
    usage_metadata.job_id,
    usage_metadata.job_run_id as run_id,
    identity_metadata.run_as as run_as
  FROM system.billing.usage
  WHERE billing_origin_product="JOBS"
),
jobs_usage_with_usd AS (
  SELECT
    jobs_usage.*,
    usage_quantity * pricing.default as usage_usd
  FROM jobs_usage
    LEFT JOIN system.billing.list_prices pricing ON
      jobs_usage.sku_name = pricing.sku_name
      AND pricing.price_start_time <= jobs_usage.usage_start_time
      AND (pricing.price_end_time >= jobs_usage.usage_start_time OR pricing.price_end_time IS NULL)
      AND pricing.currency_code="USD"
),
jobs_usage_aggregated AS (
  SELECT
    workspace_id,
    job_id,
    run_id,
    FIRST(run_as, TRUE) as run_as,
    sku_name,
    SUM(usage_usd) as usage_usd,
    SUM(usage_quantity) as usage_quantity
  FROM jobs_usage_with_usd
  GROUP BY ALL
)
SELECT
  t1.*,
  MIN(period_start_time) as run_start_time,
  MAX(period_end_time) as run_end_time,
  FIRST(result_state, TRUE) as result_state
FROM jobs_usage_aggregated t1
  LEFT JOIN system.lakeflow.job_run_timeline t2 USING (workspace_id, job_id, run_id)
GROUP BY ALL
ORDER BY usage_usd DESC
LIMIT 100

获取 SUBMIT_RUN 作业的使用情况日志

SELECT
  *
FROM system.billing.usage
WHERE
  EXISTS (
      SELECT 1
      FROM system.lakeflow.job_run_timeline
      WHERE
        job_run_timeline.job_id = usage_metadata.job_id
        AND run_name = :run_name
        AND workspace_id = :workspace_id
  )

联接作业任务运行时间线和群集表

使用群集元数据扩充作业任务运行

with clusters as (
    SELECT
        *,
        ROW_NUMBER() OVER (PARTITION BY workspace_id, cluster_id ORDER BY change_time DESC) as rn
    FROM system.compute.clusters QUALIFY rn=1
),
exploded_task_runs AS (
  SELECT
    *,
    EXPLODE(compute_ids) as cluster_id
  FROM system.lakeflow.job_task_run_timeline
  WHERE array_size(compute_ids) > 0
)
SELECT
  exploded_task_runs.*,
  clusters.*
FROM exploded_task_runs t1
  LEFT JOIN clusters t2
    USING (workspace_id, cluster_id)

查找基于通用计算运行的作业

此查询与 compute.clusters 系统表联接,以返回最近基于通用计算(而不是作业计算)运行的作业。

with clusters AS (
  SELECT
    *,
    ROW_NUMBER() OVER(PARTITION BY workspace_id, cluster_id ORDER BY change_time DESC) as rn
  FROM system.compute.clusters
  WHERE cluster_source="UI" OR cluster_source="API"
  QUALIFY rn=1
),
job_tasks_exploded AS (
  SELECT
    workspace_id,
    job_id,
    EXPLODE(compute_ids) as cluster_id
  FROM system.lakeflow.job_task_run_timeline
  WHERE period_start_time >= CURRENT_DATE() - INTERVAL 30 DAY
),
all_purpose_cluster_jobs AS (
  SELECT
    t1.*,
    t2.cluster_name,
    t2.owned_by,
    t2.dbr_version
  FROM job_tasks_exploded t1
    INNER JOIN clusters t2 USING (workspace_id, cluster_id)
)
SELECT * FROM all_purpose_cluster_jobs LIMIT 10;

作业监视仪表板

以下仪表板使用系统表来帮助您开始监控作业和运行状况。 它包括常见用例,例如作业性能跟踪、故障监视和资源利用率。

作业成本可观测性仪表板

有关下载仪表板的信息,请参阅使用系统表监视作业成本和性能

故障排除

作业未记录在 lakeflow.jobs 表中

如果任务在系统表中不可见:

  • 在过去 365 天内未修改作业
    • 修改架构中存在的任何作业字段以发出新记录。
  • 作业是在不同区域创建的
  • 作业是最近创建的(表格数据延迟)

找不到在 job_run_timeline 表中显示的作业

并非所有作业运行在任何地方都可见。 虽然 JOB_RUN 条目出现在所有与作业相关的表中,但 WORKFLOW_RUN(笔记本工作流运行)仅记录在 job_run_timeline 中,SUBMIT_RUN(一次性提交的运行)仅记录在这两个时间线表中。 这些运行不会填充到其他作业系统表,例如 jobsjob_tasks

有关每种运行类型在何处可见和可访问的详细信息,请参阅下表 运行类型 表。

作业运行在 billing.usage 表中不可见

system.billing.usage 中,仅针对在作业计算或无服务器计算上运行的作业填充 usage_metadata.job_id

此外,WORKFLOW_RUN 作业在 usage_metadata.job_id 中没有自己的 usage_metadata.job_run_idsystem.billing.usage 属性。 这些计算的使用量将归因于触发它们的父笔记本。 这意味着,当笔记本启动工作流运行时,所有计算成本都归于父笔记本的使用,而不会单独列为工作流作业。

有关详细信息,请参阅 使用情况元数据参考

计算在通用计算上运行的作业的成本

对于在通用计算上运行的作业的成本,不可能 100% 准确地进行精确的成本计算。 当作业在交互式(用途)计算上运行时,多个工作负荷(如笔记本、SQL 查询或其他作业)通常会在同一计算资源上同时运行。 由于群集资源是共享的,因此计算成本和单个作业运行之间没有直接的 1:1 映射。

为了准确跟踪作业成本,Databricks 建议在专用作业计算或无服务器计算上运行作业,其中 usage_metadata.job_idusage_metadata.job_run_id 允许精确的成本归因。

如果必须使用全用途计算,可以:

  • 根据 usage_metadata.cluster_id 监视 system.billing.usage 中的总体群集使用情况和成本。
  • 单独跟踪作业运行时指标。
  • 请考虑由于共享资源,任何成本估算都将是近似值。

有关成本归因的详细信息,请参阅 使用情况元数据参考

引用值

以下部分包括有关作业相关表中选择列的引用。

触发器类型值

trigger_type 列的可能值为:

  • CONTINUOUS
  • CRON
  • FILE_ARRIVAL
  • ONETIME
  • ONETIME_RETRY

运行类型值

run_type 列的可能值为:

类型 说明 UI 位置 API 终结点 系统表
JOB_RUN 标准作业执行 作业和作业运行 UI /jobs 和 /jobs/runs 终结点 jobs、job_tasks、job_run_timeline、job_task_run_timeline
SUBMIT_RUN 通过 POST /jobs/runs/submit 执行一次性运行 仅限作业运行 UI 仅限 /jobs/runs 终结点 job_run_timeline、job_task_run_timeline
WORKFLOW_RUN 笔记本工作流发起的运行 不可见 不可访问 作业运行时间线

结果状态值

result_state 列的可能值为:

国家 说明
SUCCEEDED 运行成功完成
FAILED 运行已完成但出现错误
SKIPPED 未执行过运行,因为未满足条件
CANCELLED 应用户要求取消了运行
TIMED_OUT 该运行在达到超时后已停止
ERROR 运行已完成但出现错误
BLOCKED 运行在上游依赖项上被阻止

终止代码值

termination_code 列的可能值为:

终止代码 说明
SUCCESS 运行已成功完成
CANCELLED Databricks 平台在执行期间取消运行;例如,如果超出了最长运行持续时间
SKIPPED 从未执行过任务,如上游任务运行失败、不满足依赖项类型条件,或没有需要执行的具体任务等情况
DRIVER_ERROR 与 Spark 驱动程序通信时运行遇到错误
CLUSTER_ERROR 由于群集错误,运行失败
REPOSITORY_CHECKOUT_FAILED 由于与第三方服务通信时出错,无法完成签出
INVALID_CLUSTER_REQUEST 运行失败,因为它发出了启动群集的无效请求
WORKSPACE_RUN_LIMIT_EXCEEDED 工作区已达到最大并发活动运行数的配额。 请考虑在更大的时间范围内安排运行
FEATURE_DISABLED 运行失败,因为它尝试访问工作区不可用的功能
CLUSTER_REQUEST_LIMIT_EXCEEDED 群集创建、启动和增加请求数已超过分配速率限制。 请考虑在更大的时间范围内分散运行执行
STORAGE_ACCESS_ERROR 由于访问客户 Blob 存储时出错,运行失败
RUN_EXECUTION_ERROR 运行已完成,但存在部分任务失败
UNAUTHORIZED_ERROR 由于访问资源时出现权限问题,运行失败
LIBRARY_INSTALLATION_ERROR 安装用户请求的库时运行失败。 原因可能包括,但不限于:提供的库无效,没有足够的权限安装库,等等
MAX_CONCURRENT_RUNS_EXCEEDED 计划运行超出了为作业设置的最大并发运行数限制
MAX_SPARK_CONTEXTS_EXCEEDED 运行被安排在一个已达到所配置的最大上下文数量的群集上运行
RESOURCE_NOT_FOUND 运行执行所需的资源不存在
INVALID_RUN_CONFIGURATION 由于配置无效,运行失败
CLOUD_FAILURE 由于云提供商问题,运行失败
MAX_JOB_QUEUE_SIZE_EXCEEDED 因达到作业级别队列大小限制,运行被跳过