monitoring-background-jobs

监控后台作业

通过识别与用户查询不同的失败、暂停和运行时间过长的作业，监控后台作业的运行状况。使用纯 SQL 接口（SHOW JOBS 和 SHOW AUTOMATIC JOBS）来显示架构变更、备份/恢复、自动统计信息收集和 SQL 统计信息压缩，无需访问 DB Console。

先决条件

• SQL 连接，并具有 VIEWJOB 系统权限（只读）或 CONTROLJOB 角色选项（控制）
• 后台作业不会显示在 SHOW CLUSTER STATEMENTS 中，也不会显示在 DB Console 的 SQL Activity 页面所展示的语句统计信息中

相关技能： 实时查询请参阅 triaging-live-sql-activity，历史查询分析请参阅 profiling-statement-fingerprints。

关键接口

• SHOW JOBS：用户发起的作业和自动作业（默认显示最近 12 小时；保留期限可通过 jobs.retention_time 集群设置配置，默认 14 天）
• SHOW AUTOMATIC JOBS：仅显示自动作业（AUTO CREATE STATS、SCHEMA CHANGE GC 等）

完整目录请参阅作业类型参考和作业状态参考。

核心诊断查询

查询 1：失败的作业（最近 12 小时）

找出失败并带有错误消息的作业：

-- Failed jobs in last 12 hours
WITH j AS (SHOW JOBS)
SELECT
  job_id,
  job_type,
  description,
  created,
  finished,
  now() - created AS total_duration,
  error
FROM j
WHERE status = 'failed'
  AND created > now() - INTERVAL '12 hours'
ORDER BY created DESC
LIMIT 50;

关键列：

• error：失败原因（检查权限错误、磁盘空间不足、网络问题）
• description：对作业执行内容的易读描述
• total_duration：作业失败前的运行时长

常见失败模式：

• 权限被拒绝：用户缺少所需权限
• 磁盘空间不足：备份目标已满
• 网络超时：无法访问外部存储
• 约束冲突：恢复操作与现有数据冲突

查询 2：运行时间过长的作业

查找运行时间超过预期阈值的作业：

-- Jobs running longer than 1 hour
WITH j AS (SHOW JOBS)
SELECT
  job_id,
  job_type,
  description,
  status,
  running_status,
  created,
  now() - created AS running_for,
  fraction_completed,
  coordinator_id
FROM j
WHERE status = 'running'
  AND created < now() - INTERVAL '1 hour'
ORDER BY created
LIMIT 50;

关键列：

• running_for：自作业启动以来经过的总时间
• fraction_completed：进度估算值（0.0 到 1.0；若不可用则为 NULL）
• running_status：子状态详情（例如，“等待 MVCC GC”）

可自定义的阈值：

• 架构变更：30 分钟到数小时（取决于表的大小）
• 备份：1 到 6 小时以上（取决于数据量）
• 自动作业：通常少于 30 分钟

查询 3：已暂停的作业

找出已暂停且可能需要关注的作业：

-- Paused jobs needing resume
WITH j AS (SHOW JOBS)
SELECT
  job_id,
  job_type,
  description,
  created,
  now() - created AS paused_for,
  coordinator_id
FROM j
WHERE status = 'paused'
ORDER BY created
LIMIT 50;

需要执行的操作： 确认暂停原因后，使用 RESUME JOB <job_id> 恢复作业。

作业暂停的常见原因：

• 用户为维护而手动暂停
• 资源限制（集群暂停了作业）
• 错误需要手动干预

查询 4：等待 MVCC GC 的架构变更

查找正在等待垃圾回收的 SCHEMA CHANGE GC 作业：

-- Schema change cleanup jobs waiting for GC
WITH j AS (SHOW JOBS)
SELECT
  job_id,
  job_type,
  description,
  created,
  now() - created AS waiting_for,
  running_status
FROM j
WHERE status = 'running'
  AND job_type = 'SCHEMA CHANGE GC'
  AND running_status LIKE '%waiting for MVCC GC%'
ORDER BY created
LIMIT 50;

说明：

• **正常情况：**SCHEMA CHANGE GC 作业会根据区域级 gc.ttlseconds（默认 4 小时）等待数据变为可进行垃圾回收的状态
• **预期时长：**最长为 gc.ttlseconds 加上少量额外时间
• **需要注意的情况：**等待时间超过 gc.ttlseconds 的 2 倍（使用 SHOW ZONE CONFIGURATION FOR ... 检查受影响表、数据库或 RANGE 的有效值——区域配置会逐级继承，也可能在任意级别被覆盖）

发生原因： 执行 DROP TABLE/INDEX 操作后，CockroachDB 必须等待所有使用较早时间戳的读取完成，才能实际删除数据。这样可以避免“时间旅行”查询失败。

MVCC GC 的详细说明请参阅作业状态参考。

查询 5：自动作业健康状况（24 小时窗口）

监控统计信息收集等自动后台作业：

-- Automatic jobs in last 24 hours
SELECT
  job_id,
  job_type,
  description,
  status,
  created,
  finished,
  COALESCE(finished, now()) - created AS duration
FROM [SHOW AUTOMATIC JOBS]
WHERE created > now() - INTERVAL '24 hours'
  AND job_type IN ('AUTO CREATE STATS', 'AUTO SQL STATS COMPACTION')
ORDER BY created DESC
LIMIT 50;

主要作业类型：

• AUTO CREATE STATS：自动刷新表统计信息（对查询优化器至关重要）
• AUTO SQL STATS COMPACTION：定期清理语句／事务统计信息表

健康状况指标：

• 健康： 定期成功执行（每隔几小时）
• 不健康： 最近没有执行记录，或失败率较高
• 失败的影响： 统计信息过时会导致查询计划不佳、查询速度变慢

查询 6：按类型和状态查看作业

用于模式分析的汇总视图：

-- Job distribution by type and status (last 24h)
WITH j AS (SHOW JOBS)
SELECT
  job_type,
  status,
  COUNT(*) AS job_count,
  MIN(created) AS oldest,
  MAX(created) AS newest
FROM j
WHERE created > now() - INTERVAL '24 hours'
GROUP BY job_type, status
ORDER BY job_type, status;

使用场景：

• 识别模式（例如，所有 BACKUP 作业都失败，或多个架构变更卡住）
• 发现异常（例如，作业类型数量异常）
• 按类型跟踪作业成功率

查询 7：备份和恢复进度

跟踪备份／恢复作业的进度：

-- Active backup/restore jobs with progress
WITH j AS (SHOW JOBS)
SELECT
  job_id,
  job_type,
  description,
  created,
  now() - created AS running_for,
  ROUND(COALESCE(fraction_completed, 0) * 100, 2) AS percent_complete,
  CASE
    WHEN fraction_completed > 0 AND fraction_completed < 1 THEN
      ((now() - created) / fraction_completed) - (now() - created)
    ELSE NULL
  END AS estimated_time_remaining,
  running_status
FROM j
WHERE status = 'running'
  AND job_type IN ('BACKUP', 'RESTORE')
ORDER BY created
LIMIT 50;

主要列：

• percent_complete：进度百分比（0-100）
• estimated_time_remaining：根据当前进度速率得出的粗略剩余时间估计
• running_status：详细状态（例如，“正在备份到 s3://...”）

注意： 某些作业类型或执行初期的 fraction_completed 可能为 NULL。

常见工作流

工作流 1：调查卡住的架构变更

场景： 用户报告 ALTER TABLE 或 CREATE INDEX 似乎卡住。

1. 检查正在运行的架构变更：

   WITH j AS (SHOW JOBS)
   SELECT job_id, description, created, now() - created AS running_for,
          fraction_completed, running_status
   FROM j
   WHERE status = 'running'
     AND job_type IN ('SCHEMA CHANGE', 'NEW SCHEMA CHANGE')
   ORDER BY created;
   

2. 识别 MVCC GC 等待：

   -- Use Query 4 to find "waiting for MVCC GC" jobs
   

3. 解读结果：

   • 如果 running_status = "waiting for MVCC GC"：对于 DROP 后的清理来说是正常情况（等待时间最长可达 gc.ttlseconds）
   • 如果作业运行时间很长且 fraction_completed 较低：检查是否存在争用、表是否过大或是否受资源限制
   • 如果作业失败：检查 error 列中的具体失败原因

4. 后续步骤：

   • 等待 MVCC GC：针对受影响的对象，使用 SHOW ZONE CONFIGURATION FOR TABLE/DATABASE/RANGE ... 验证生效的 gc.ttlseconds，然后等待
   • 资源限制：检查集群 CPU／内存使用情况
   • 作业失败：解决错误（权限、约束等）并重试操作

工作流 2：排查备份失败

场景： 计划的备份作业失败。

1. 查找最近失败的备份：

   -- Use Query 1 filtered for BACKUP job type
   WITH j AS (SHOW JOBS)
   SELECT job_id, description, created, finished, error
   FROM j
   WHERE status = 'failed'
     AND job_type = 'BACKUP'
     AND created > now() - INTERVAL '24 hours'
   ORDER BY created DESC;
   

2. 分析错误消息：

   • "permission denied"：检查外部存储凭据
   • "timeout"：检查到备份目标的网络连接
   • "no space left"：目标存储空间已满
   • "connection refused"：无法访问外部存储端点

3. 验证备份目标：

   -- Check SHOW BACKUP for successful backups to same destination
   SHOW BACKUP 's3://bucket/path';
   

4. 修复并重试：

   • 修复根本问题（凭据、存储、网络）
   • 重新运行备份命令
   • 使用查询 7 监控进度

工作流 3：自动作业健康检查

场景： 主动监控自动后台作业。

1. 检查 AUTO CREATE STATS 的执行频率：

   -- Use Query 5 to see recent automatic statistics jobs
   SELECT job_type, status, COUNT(*) AS job_count,
          MAX(created) AS most_recent
   FROM [SHOW AUTOMATIC JOBS]
   WHERE created > now() - INTERVAL '24 hours'
     AND job_type = 'AUTO CREATE STATS'
   GROUP BY job_type, status;
   

2. 预期模式：

   • 每天多次成功运行 AUTO CREATE STATS 作业（取决于表的更新频率）
   • 定期运行 AUTO SQL STATS COMPACTION（通常每小时一次）

3. 警示信号：

   • 过去 24 小时内没有 AUTO CREATE STATS：统计信息收集可能已禁用
   • 失败率较高：检查集群资源限制或权限问题
   • 没有 AUTO SQL STATS COMPACTION：统计信息表可能会无限增长

4. 验证设置：

   SHOW CLUSTER SETTING sql.stats.automatic_collection.enabled;  -- Should be true
   SHOW CLUSTER SETTING sql.stats.automatic_collection.min_stale_rows;
   

工作流 4：监控长时间运行的作业

场景： 跟踪预计运行时间较长的操作进度。

1. 识别长时间运行的作业：

   -- Use Query 2 with custom threshold
   WITH j AS (SHOW JOBS)
   SELECT job_id, job_type, description,
          now() - created AS running_for,
          fraction_completed
   FROM j
   WHERE status = 'running'
     AND created < now() - INTERVAL '30 minutes'
   ORDER BY created;
   

2. 随时间监控进度：

   -- Re-run every 10-15 minutes, track fraction_completed changes
   -- Example: 0.25 → 0.40 → 0.55 indicates steady progress
   

3. 估算完成时间：

   -- Use Query 7 for backup/restore jobs with time estimates
   

4. 决定采取何种操作：

   • 进度稳定：继续监控
   • 进度停滞（fraction_completed 未增加）：使用 triaging-live-sql-activity 进行调查
   • 作业失败：使用查询 1 检查错误

安全注意事项

只读操作（所有诊断查询）： 所有 SHOW JOBS 和 SHOW AUTOMATIC JOBS 查询均为只读，在生产环境中运行是安全的。不会影响集群操作的性能。

作业控制操作（自愿执行）：

注意：暂停或取消作业可能影响数据完整性

只有在满足以下条件时，才继续执行作业控制操作：

• 你拥有 CONTROLJOB 角色选项
• 你了解相关影响（例如，在架构变更执行过程中取消作业可能需要手动清理）
• 你获准中断集群操作
• 你已确认该作业确实存在问题（而不只是运行缓慢）

作业控制命令：

-- Pause a running job (can be resumed later)
PAUSE JOB <job_id>;

-- Resume a paused job
RESUME JOB <job_id>;

-- Cancel a job (terminal - cannot be resumed)
CANCEL JOB <job_id>;

不同作业类型的风险：

• 架构变更（SCHEMA CHANGE）： 取消可能导致架构处于不一致状态；建议优先暂停并调查
• 备份（BACKUP）： 取消是安全的（可重试）；遇到临时问题时，暂停更好
• 还原（RESTORE）： 取消可能导致数据库仅部分还原；需要进行清理
• 自动创建统计信息（AUTO CREATE STATS）： 取消是安全的（之后会自动重试）

最佳实践： 重点关注监控和诊断；只有在明确需要且已获授权时才执行控制操作。

请参阅权限参考，了解如何设置 CONTROLJOB 角色选项。

故障排查

问题	原因	解决方法
SHOW JOBS 返回空结果	过去 12 小时内没有作业，或权限不足	授予 VIEWJOB 权限；确认集群近期有作业活动
“waiting for MVCC GC” 持续数小时	DROP 操作后的架构变更 GC 属于正常行为	最多等待 gc.ttlseconds（默认值为 4h）；针对受影响的表、数据库或范围，使用 SHOW ZONE CONFIGURATION FOR ... 检查生效值
无法暂停或恢复作业：“permission denied”	缺少 CONTROLJOB 角色选项	使用 ALTER ROLE <username> WITH CONTROLJOB（不要使用 GRANT SYSTEM）
作业的 fraction_completed 始终不变	作业可能正在处理大型批次，也可能确实卡住了	等待 15-30 分钟后重新检查；如果没有变化，请使用实时查询排查方法进行调查
没有 AUTO CREATE STATS 作业	已禁用自动收集	检查 sql.stats.automatic_collection.enabled = true
SHOW AUTOMATIC JOBS 只显示旧作业	需要按时间范围筛选	添加 WHERE created > now() - INTERVAL '24 hours'
作业因“schema change GC”错误而失败	DROP 操作后的清理失败，属于预期情况	通常可以安全忽略；作业会自动重试
作业错误：“concurrent schema change”	同一表上存在多个架构变更	等待第一个架构变更完成，然后重试

关键注意事项

• 等待 MVCC GC： DROP 操作后的清理过程通常会等待；持续时间取决于区域级的 gc.ttlseconds（默认值为 4h）
• 自动作业健康状况： 定期运行 AUTO CREATE STATS 对查询优化器的性能至关重要
• 作业控制： PAUSE 比 CANCEL 更安全；某些取消操作需要手动清理
• 进度： 某些作业类型的 fraction_completed 可能为 NULL

参考资料

技能参考：

• RBAC 和权限设置
• 作业状态和转换
• 作业类型目录
• SQL 查询变体

相关技能：

• triaging-live-sql-activity - 用于实时查询监控（作业执行的语句可能不会显示）
• profiling-statement-fingerprints - 用于历史查询分析（不包括后台作业）

CockroachDB 官方文档：

• SHOW JOBS
• SHOW AUTOMATIC JOBS
• PAUSE JOB
• RESUME JOB
• CANCEL JOB
• crdb_internal
• 作业页面（DB Console）
• VIEWJOB 权限