monitoring-background-jobs

バックグラウンドジョブの監視

ユーザークエリとは別の、失敗、一時停止、長時間実行中のジョブを特定して、バックグラウンドジョブの健全性を監視します。SQL のみのインターフェース（SHOW JOBS および SHOW AUTOMATIC JOBS）を使用して、DB Console にアクセスすることなく、スキーマ変更、バックアップ／復元、自動統計収集、SQL 統計の圧縮を確認できます。

前提条件

• VIEWJOB システム権限（読み取り専用）または CONTROLJOB ロールオプション（制御）を持つ SQL 接続
• バックグラウンドジョブは 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 倍を超える場合（影響を受けるテーブル、データベース、または RANGE に対して SHOW ZONE CONFIGURATION FOR ... を実行し、有効な値を確認してください。ゾーン設定は階層的に引き継がれ、任意のレベルで上書きされる場合があります）

この現象が起きる理由： 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 ジョブが 1 日に複数回正常終了する（テーブルの更新頻度によって異なります）
   • AUTO SQL STATS COMPACTION が定期的に実行される（通常は 1 時間に 1 回）

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： キャンセルするとスキーマが不整合な状態になる可能性があるため、PAUSE して調査することをおすすめします
• BACKUP： キャンセルしても安全です（再試行できます）。一時的な問題の場合は一時停止する方が適切です
• RESTORE： キャンセルするとデータベースの復元が部分的な状態になり、クリーンアップが必要になる場合があります
• AUTO CREATE STATS： キャンセルしても安全です（後で自動的に再試行されます）

ベストプラクティス： 監視と診断を重視し、明示的に必要で、許可されている場合にのみ制御操作を使用してください。

CONTROLJOB ロールオプションの設定については、権限のリファレンスを参照してください。

トラブルシューティング

問題	原因	解決方法
SHOW JOBS の結果が空	過去 12 時間以内にジョブがない、または権限が不足している	VIEWJOB 権限を付与し、クラスターで最近ジョブが実行されたか確認します
「waiting for MVCC GC」が何時間も続く	DROP 操作後の SCHEMA CHANGE GC では通常の動作です	gc.ttlseconds（デフォルトは 4 時間）まで待ちます。影響を受けるテーブル／データベース／範囲に対して 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（デフォルトは 4 時間）に依存します
• 自動ジョブの健全性： AUTO CREATE STATS が定期的に実行されることは、クエリオプティマイザーのパフォーマンスに不可欠です
• ジョブ制御： CANCEL より PAUSE の方が安全です。キャンセル後に手動でのクリーンアップが必要になる場合があります
• 進捗： 一部のジョブの種類では、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 権限