誰が何をしたか、いくらかかったか、どこで詰まったかを見る

14.1リネージと監査 — system.access.audit / table_lineage / column_lineage と INFORMATION_SCHEMA の使い分け

「この集計テーブルを消したら、どのダッシュボードが壊れますか」「先週この顧客テーブルを参照したのは誰ですか」「このカタログにスキーマはいくつありますか」。三つとも後から確認する問いですが、答えを持つ場所は別々です。取り違えると、監査ログを何時間眺めても依存関係は出てきません。覚え方は一行です。構造は INFORMATION_SCHEMA、依存はリネージ、行為は監査ログです。

下の三つに共通する土台が system カタログです。Unity Catalog を有効にしたアカウントには system という読み取り専用のカタログが用意され、access、billing、lakeflow、compute、query といったスキーマが並びます。中身はただの Delta テーブルで、SQL で集計できます。有効化はアカウント管理者が行い、他の利用者には `USE CATALOG` と `SELECT` が要ります。

いま何があるかは INFORMATION_SCHEMA

現在の姿を知りたいときは `INFORMATION_SCHEMA` です。各カタログの直下に自動で公開される標準ビュー群で、`SCHEMATA` でスキーマ、`TABLES` でテーブル、`COLUMNS` で列、`TABLE_PRIVILEGES` で権限の一覧が返ります。

SELECT schema_name, schema_owner
FROM mycat.INFORMATION_SCHEMA.SCHEMATA;

これだけは他の system テーブルと違って明示的な `SELECT` 権限が要らず、自分が権限を持つオブジェクトだけが自動で絞り込まれて返ります。カタログ直下のものはそのカタログ内しか見えず、横断したいときは `system.information_schema` を使いますが、`hive_metastore` のオブジェクトは含まれません。

どこから来たかはリネージ

画面なら Catalog Explorer の Lineage タブ、SQL なら二つのリネージテーブルです。列は 20 以上ありますが、意味を問われるのは四つです。`source_table_full_name` だけが埋まっていれば読み取りだけ、`target_table_full_name` だけなら書き込みだけ、両方なら読んで書いた 1 イベントです。`entity_type` は `NOTEBOOK`、`JOB`、`PIPELINE`、`DASHBOARD_V3`、`DBSQL_QUERY` のどれかで、実行主体が分かります。`statement_id` は SQL ウェアハウスから実行された場合にだけ入り、Query History へ辿る外部キーになります。`column_lineage` にはさらに `source_column_name` と `target_column_name` が加わります。

SELECT source_table_full_name, entity_type, created_by, event_time
FROM system.access.table_lineage
WHERE target_table_full_name = 'main.sales.sales_agg'
  AND event_date >= current_date() - INTERVAL 30 DAYS;

リネージは実行されたクエリの解析で作られるため宣言もタグ付けも不要ですが、Unity Catalog を経由しない操作は残りません。`spark.read.load("/mnt/raw/...")` のような DBFS パスの直読みは、列どころかテーブルのリネージも記録されません。列リネージは、値を並べただけの `INSERT` のように上流が存在しないイベントも取得しません。UC 非対応のコンピュートも同様です。system テーブルは 1 年で古い行が消えますが、Catalog Explorer とリネージ API は 2024 年 9 月 1 日以降を無期限に保持します。

誰が触ったかは system.access.audit

監査ログは 1 行が 1 回の API 呼び出しで、`user_identity`、`action_name`、`request_params`、`audit_level` などを持ちます。`audit_level` が `ACCOUNT_LEVEL` の行は特定のワークスペースに属さないため、`workspace_id` が `0` で記録されます。既定ではコマンドの本文は残りません。管理コンソールの Advanced タブで詳細監査ログ (`enableVerboseAuditLogs`) を有効にすると、`notebook` と `jobs` の `runCommand`、`databrickssql` の `commandSubmit` と `commandFinish` が追加され、`request_params` に `commandText` が入ります。

行フィルタや列マスク付きテーブルの監査では、誰が叩いたかを `system.access.audit`、どのテーブルと列が読まれたかを `table_lineage` と `column_lineage` で見て組み合わせます。`_delta_log` の JSON やクラスタ上の `/var/log` は、アクセス主体を記録しておらずノード終了で消えるため証跡になりません。検索クエリ例と長期保管の設計は記事「Databricks Audit Logs」(`/articles/databricks/audit-logs/`) に譲ります。

14.2コストの読み方 — DBU 課金式、クラウド課金との二本立て、system.billing.usage

Databricks を使い始めた組織がまず戸惑うのは、請求書が二通届くことです。Databricks からの請求と、AWS / Azure / Google Cloud からの請求が別々に来ます。不備ではなく設計です。Databricks は計算資源の利用料だけを課金し、VM やストレージやネットワークの料金はクラウド事業者が直接請求します。分かれているので、利用者が自分でクラウド事業者と結んだリザーブドインスタンスや割引契約がそのまま効きます。片方だけを見て安いと判断すると、月末にほぼ倍の金額を見ることになります。

DBU は時間あたりの処理能力の単位

Databricks 側の課金単位が DBU です。1 時間あたりの処理能力を表す単位で、課金の刻みは秒単位です。1 時間走らせたら必ず 1 DBU、という意味ではありません。消費量はノード台数と VM のスペックで決まり、単価はワークロード種別で分かれた SKU ごとに違います。同じ処理でも、対話用の `STANDARD_ALL_PURPOSE_COMPUTE` とジョブ専用の `STANDARD_JOBS_COMPUTE` では単価が違います。つまり請求額は「DBU 消費量 × SKU 単価 × 時間」と「クラウド事業者からの VM・ストレージ・ネットワーク費用」の合算です。固定月額ではなく、開発用クラスタが無料になる仕組みもありません。

使用量と単価は別のテーブルにある

ここが試験でも実務でもつまずく点です。使用量を記録する `system.billing.usage` には金額の列がありません。あるのは `usage_unit` (通常 `DBU`) と `usage_quantity` だけです。金額にするには単価表 `system.billing.list_prices` と結合します。

`usage_metadata` は構造体で、`cluster_id`、`job_id`、`job_run_id`、`warehouse_id`、`dlt_pipeline_id`、`node_type` などを持ちます。誰の実行かは `identity_metadata.run_as` です。`pricing` も構造体で、`default` が長期見積り用の定価、`promotional` が期間限定の割引価格、`effective_list` がその時点で実際に適用される実効定価です。ここに載るのは公開定価であり、個別の契約割引は反映されません。

もう一つの落とし穴が `record_type` です。値は `ORIGINAL`、`RETRACTION`、`RESTATEMENT` の 3 種類で、後から訂正が入ると、元の行を打ち消す負の数量の `RETRACTION` 行と、訂正後の `RESTATEMENT` 行が追加されます。したがって全種別をそのまま合計するのが正しい読み方で、`record_type = 'ORIGINAL'` だけに絞ると訂正が反映されず過大に数えます。

実務での確認手順も押さえます。日次の DBU 消費を見たいなら `usage_date` で集計して AI/BI ダッシュボードに載せ、しきい値超過はアラートにします。Serverless を含むすべてのワークロードがこのテーブルに載るのに対し、Spark UI から DBU を読み取る方法はなく、Serverless では計算ノード自体が見えません。クラスタイベント API を定期的に叩く運用も課金用の情報源ではありません。金額に関する問いはまず `system.billing` を見ると決めておくと迷いません。タグ設計とチャージバックの手順は記事「Databricks コストアトリビューション実務」(`/articles/databricks/cost-attribution/`) に譲ります。

14.3system テーブルで全体を見る — job_run_timeline × billing.usage による DBU 按分

「先月いちばんお金を使ったジョブはどれですか」。よく来る質問ですが、`system.billing.usage` だけでは答えられません。入っているのは SKU と ID だけで、ジョブ名も成否もないからです。実行の側は `system.lakeflow` スキーマにあります。

run が複数行に割れる仕様を先に知る

`job_run_timeline` は run ごとに 1 行ではありません。1 時間を超える run は複数行に分割されます。注意点が二つ出ます。行数をそのまま実行回数として数えると水増しになること、そして `result_state` と `termination_code` は run の最後の行にだけ入り、途中のスライスは `NULL` になることです。`result_state` の値は `SUCCEEDED`、`FAILED`、`SKIPPED`、`CANCELLED`、`TIMED_OUT`、`ERROR`、`BLOCKED` です。

所要時間の列には但し書きが要ります。`setup_duration_seconds`、`queue_duration_seconds`、`execution_duration_seconds` などの 5 列はレガシー Jobs API で作られた単一タスクジョブでしか埋まりません。現行のマルチタスクジョブでは 0 が並ぶため、遅さの内訳をここで切り分けようとしても数字は出ません。

DBU をジョブ実行へ按分する

結合は 2 段です。まず使用量を `usage_metadata.job_id` と `job_run_id` で run 単位に集計し、次に `job_run_timeline` を `workspace_id` と `job_id` と `run_id` で突き合わせます。金額まで出すなら三段目に `list_prices` を `sku_name` と `price_start_time` / `price_end_time` の期間で結合します。

WITH j AS (
  SELECT workspace_id,
         usage_metadata.job_id     AS job_id,
         usage_metadata.job_run_id AS run_id,
         SUM(usage_quantity)       AS dbus
  FROM system.billing.usage
  WHERE usage_metadata.job_id IS NOT NULL
    AND usage_date >= current_date() - INTERVAL 30 DAYS
  GROUP BY ALL
)
SELECT j.*, MAX(t.result_state) AS result_state
FROM j LEFT JOIN system.lakeflow.job_run_timeline t
  USING (workspace_id, job_id, run_id)
GROUP BY ALL ORDER BY dbus DESC;

効くのはジョブとして実行した分だけです。`usage_metadata.job_id` が埋まるのはジョブコンピュートかサーバーレスの場合に限られ、汎用クラスタで手回ししたノートブックには付きません。チーム別に割るならタグを付けて `custom_tags` で集計します。SQL ウェアハウスは `warehouse_id`、宣言的パイプラインは `dlt_pipeline_id` が軸です。

前提です。system テーブルは Unity Catalog 有効なワークスペースが条件で、有効化はアカウント管理者が行います。ジョブ側に `dbutils.system.enable()` を書く必要はなく、その API は存在しません。計算資源側は `system.compute.clusters` と `system.compute.node_timeline` で見え、後者だけ保持が 90 日です。テーブル一覧と有効化手順は記事「System Tables とは？」(`/articles/databricks/system-tables/`) に譲ります。

14.4詰まったときにどこを見るか — 組込デバッガと Variable Explorer、event log / driver log / Query History / Spark UI の切り分け表

障害連絡で一番時間を溶かすのは、原因の解析ではなく「どこを開くか」で迷う最初の数分です。Databricks は記録の層がいくつもあり、層を間違えると何も書かれていないログを読み続けることになります。症状から入口を引ける表を 1 枚持っておくと、復旧時間が縮みます。

ノートブックの中で止める

ロジックの誤りは、ログを読むより止めて見るほうが速いです。ノートブックには対話的なデバッガが組み込まれています。対象は Python セルのみで、サーバーレスコンピュート、標準アクセスモードなら Databricks Runtime 14.3 LTS 以上、専用アクセスモードなら 13.3 LTS 以上が要件です。セル左端のガターをクリックしてブレークポイントを置き、ステップ実行とステップインができます。停止中はデバッグコンソールで Python を実行できますが、15 秒でタイムアウトします。

できないことも整理します。Python ライブラリの内部や他のノートブックへはステップインできません。デバッグコンソールで `display()` は使えず、`df.show()` で代用します。そしてローカル PC の `pdb` に attach する構成は取れません。コードはマネージドクラスタのドライバ上で動くためです。手元の IDE から書くなら Databricks Connect を使い、実行はクラスタ側に残します。

Variable Explorer は右側のパネルで、現在のセッションの変数を名前・型・サイズ・値のプレビュー付きで一覧します。Python かつ DBR 12.2 LTS 以上ならセルの実行中に随時更新され、Scala と R、DBR 11.3 LTS 以下の Python ではセルが終わってから更新されます。表示範囲はアタッチ中のノートブックのセッションに閉じています。

ログの層を切り分ける

宣言的パイプラインや Lakeflow Connect のインジェストパイプラインの失敗は、イベントログとドライバログが一次調査です。イベントログは `event_log(TABLE(main.sales.my_mv))` または `event_log(<pipelineId>)` というテーブル値関数で SQL から読めます。返る列は `timestamp`、`message`、`level`、`error`、`details`、`event_type` などです。`level` は `INFO`、`WARN`、`ERROR`、`METRICS` の 4 値で、`details` は JSON 文字列です。この関数を呼べるのは対象のストリーミングテーブルまたはマテリアライズドビューの所有者だけです。

ストリーミングテーブルに行が来ない、件数が合わないという症状の定番は、Expectations による除外です。`event_type = 'flow_progress'` に絞り、`details` の `data_quality` に入る `dropped_records` と、期待値ごとの合否件数を確認します。同じ内容は UI の Data Quality タブにも出ます。`ON VIOLATION DROP ROW` で落ちたのか quarantine で別テーブルへ逃げたのかを、ここで一次切り分けします。

ドライバログには `stdout`、`stderr`、`log4j` の出力が集まります。init script が exit code 0 以外で終わるとクラスタは `INIT_SCRIPT_FAILURE` になるので、Event log タブで終了理由を見てから Driver logs の `stderr` を読みます。クラスタを終了すると辿れなくなるため、残すならログ配信を設定します。配信は 5 分ごと、アーカイブは 1 時間ごとで、宛先には Unity Catalog のボリューム (推奨)、S3、DBFS を選べ、`cluster_id` と同名のサブフォルダに書き出されます。

Query History は SQL の文 1 本ごとの記録です。`statement_id`、`statement_text`、`execution_status` に加え、`total_duration_ms` を `compilation_duration_ms`、`execution_duration_ms`、`result_fetch_duration_ms` に分解した内訳と、`read_rows`、`produced_rows` を持ちます。`compute` 構造体の `type` は `WAREHOUSE` か `SERVERLESS_COMPUTE` で、汎用クラスタのクエリは対象外です。長期の分析はシステムテーブル側 (`system.query.history`、365 日) を使います。第 1 節の `statement_id` がここへの外部キーで、リネージから実行本文まで辿れます。

Spark UI は分散実行の内側を見る画面で、Jobs、Stages、Executors のタブがあります。タスク一覧で最大時間と中央値が桁違いなら偏り、Shuffle Read が突出していれば結合の見直し、Spill が出ていればメモリ不足と読みます。構文エラーのように Spark ジョブが起動する前に失敗した場合、Spark UI には何も残りません。

よく問われる症状別の初手

• 結果が 0 行になった。まず `WHERE` を外して件数・スキーマ・サンプル行を確認します。ウェアハウスのサイズを上げても行は増えません。
• `COPY INTO` がフォーマット例外で落ちる。Query History とドライバログで失敗したファイル名と理由を特定します。再実行しても冪等なので結果は変わりません。
• 取り込みが `403` で失敗する。接続文字列ではなく、接続に紐付くサービスプリンシパルの権限を疑います。
• 本番のバッチは `try` / `except` で想定例外だけを捕捉し、想定外は失敗させて Run output と通知で追います。監査ログにスタックトレースは残りません。

ここまでが後から確認する道具の見取り図です。クエリ履歴からの性能改善の手順は記事「Databricks SQL のクエリ履歴」(`/articles/databricks/dbsql-query-history/`) に譲ります。