クイックスタート — dwh-auditor のインストールと初回監査実行

このページでは、dwh-auditor のインストールから BigQuery の初回監査実行までを 5 分以内に完了することを目標に解説します。

前提条件

要件

詳細

Python バージョン

3.9 以上

GCP 認証

gcloud auth application-default login または GOOGLE_APPLICATION_CREDENTIALS

IAM 権限

roles/bigquery.metadataViewer / roles/bigquery.resourceViewer

インストール

pip でのインストール

pip install dwh-auditor

インストール確認:

dwh-auditor --help

uv を使ったインストール（推奨）

uv を使うと、依存関係の解決が高速で再現性も高まります。

uv add dwh-auditor

ソースからのインストール（開発者向け）

git clone https://github.com/shirokurolab/dwh-auditor.git
cd dwh-auditor

# Create virtual environment and install dependencies
uv venv && uv pip install -e ".[dev]"

GCP 認証の設定

Application Default Credentials（推奨）

ローカル開発では、Google Cloud SDK の ADC を使うのが最もシンプルです。

gcloud auth application-default login

サービスアカウントキーを使う場合（CI/CD 環境向け）

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

警告

サービスアカウントキー（JSON ファイル）は Git リポジトリに絶対コミットしないでください。 CI/CD 環境では GitHub Actions の Secrets またはWorkload Identity Federation を使用してください。

設定ファイルの生成（init コマンド）

監査を実行する前に、設定ファイルのテンプレートを生成します。

dwh-auditor init

カレントディレクトリに config.yaml が生成されます。 内容はコスト単価やしきい値のカスタマイズに使います。 詳細は 設定ファイル (config.yaml) — コスト単価・しきい値の DWH 監査設定 を参照してください。

監査の実行（analyze コマンド）

基本的な使い方

# Analyze my-gcp-project for the past 30 days and output to console
dwh-auditor analyze --project my-gcp-project --days 30

東京リージョンを指定する場合

dwh-auditor analyze \
  --project my-gcp-project \
  --region region-asia-northeast1 \
  --days 30

Markdown レポートを生成する場合

dwh-auditor analyze \
  --project my-gcp-project \
  --days 30 \
  --output markdown \
  --report-path audit_report.md

Tip

--output markdown を指定すると GitHub Actions の Artifact として保存し、チームに共有するのに便利です。

JSON を出力する場合

dwh-auditor analyze \
  --project my-gcp-project \
  --output json > result.json

複数のコンピューティングプロジェクトをまたいで分析する場合

ストレージ（データ用プロジェクト）とコンピューティング（クエリ実行用プロジェクト）が分かれている場合、 クエリが実行されるプロジェクトのリストをカンマ区切りで渡します。

dwh-auditor analyze \
  --project my-storage-project \
  --job-projects my-compute-prj1,my-compute-prj2 \
  --days 30

コマンドリファレンス

analyze コマンドのオプション一覧

Usage: dwh-auditor analyze [OPTIONS]

Options:

  -p, --project TEXT       分析対象の GCP プロジェクト ID  [required]
  -jp, --job-projects TEXT クエリが実行されるプロジェクトのカンマ区切りリスト
  -r, --region TEXT        BigQuery のリージョン           [default: region-us]
  -d, --days INTEGER       過去何日分を分析するか          [default: 30]
  -c, --config TEXT        設定ファイルのパス              [default: config.yaml]
  -o, --output TEXT        出力形式: console, markdown または json [default: console]
      --report-path TEXT   Markdown レポートの出力先       [default: report.md]
  --help                   ヘルプを表示

次のステップ