cloud-logging-finops

Cloud Logging Finops

非対話型の実行。 ユーザーが回答できない場合（スケジュール実行や自動実行など）は、何も質問しません。依頼で指定されたプロジェクト、またはアクティブな gcloud プロジェクトを監査し、--billing-mode=search を使用して、5 つすべてのレポート項目（ステップ 2.5）を対象とし、API を有効にしたり、ログバケットをアップグレードしたりしないでください。ユーザーの対応が必要だった事項（無効な API、不足しているロール、アップグレードに関する注意事項）は、代わりにレポートに記載してください。

ステップ 0：Cloud Billing エクスポートを特定する

監査の対象は、ユーザーが指定したプロジェクト、または指定がない場合はアクティブな gcloud プロジェクト（gcloud config get project）である、単一の Google Cloud プロジェクト {project_id} です。ユーザーに確認してください。

それ以外のもの（ログバケット、Observability Analytics、シンク、除外、指標）は、すべて自分で調べてください。ユーザーに尋ねないでください。例外は請求エクスポートです。自力で見つけようとすると、請求先アカウントのすべてのプロジェクトをスキャンする場合があるため、何かを実行する前に一度だけ尋ねてください。ユーザーが回答 3 を選択するまでは検索を開始しないでください（単一選択。ホストに質問ツールがある場合はそれを使用してください）。

{project_id} の Cloud Billing エクスポートの場所はわかりますか？

1. はい — こちらです（BigQuery テーブル ID project.dataset.table、またはプロジェクトとデータセットのみ）
2. このプロジェクトには請求エクスポートがありません
3. いいえ／わかりません — 検索してください（小規模なプロジェクトなら数秒、大規模な請求先アカウントでは長時間かかる場合があります）

回答	フラグ	コストの数値
1	--billing-mode=explicit と --billing-table（または --billing-project／--billing-dataset）	請求額
2	--billing-mode=none	定価に基づく推定額
3	--billing-mode=search（デフォルト）	見つかった場合は請求額、見つからない場合は推定額

回答 3 の検索には時間制限がありません。まず {project_id} を確認し（通常は 10 秒未満、テーブルが多い場合は 1～2 分）、次に請求先アカウント内のすべてのプロジェクトを確認します（数分かかる場合があり、30 秒ごとに進捗が表示されます）。検索を開始する前に、このことをユーザーに伝えてください。待ち時間が許容できない場合は、回答 1（テーブルを調べてもらう）か回答 2（エクスポートをスキップして定価に基づく推定額を使用する）に切り替える案を提示してください。検索を速くするためにエクスポートを設定するよう勧めないでください。

検索でエクスポートが見つかった場合は、ユーザーに次のように伝えてください。「次回は --billing-table=<table> を渡せば、検出にかかる時間を約 2 秒に短縮できます。」

ステップ 1：環境のセットアップ

ステップ 2 に進む前に、以下の前提条件を確認してください。不足しているものだけを修正します。

• gcloud： gcloud がインストールされていない場合は、 https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt に従ってください。
• プロジェクト： gcloud config get project を実行します。値が {project_id} （ステップ 0 の値）でない場合は、gcloud config set project {project_id} を実行します。
• 認証情報： スクリプトは Application Default Credentials を使用します。gcloud auth application-default login を実行するか、 GOOGLE_APPLICATION_CREDENTIALS にサービスアカウントキーを設定します。
• 請求： プロジェクトに有効な請求先アカウントが関連付けられている必要があります。
• API： 事前に API を有効にしないでください。新しいプロジェクトでは、Logging、Monitoring、BigQuery、Observability の API はデフォルトで有効になっています。コレクターが API の無効状態（SERVICE_DISABLED、「has not been used in project」）を報告した場合に限り、その API 名を伝えてユーザーに確認し、承認されたら gcloud services enable {api} --project={project_id} を実行します（下記の説明に従ってタグを付けます）。
  • logging、monitoring：必須です。これらがないと監査できません。
  • bigquery：請求エクスポートからの請求額を取得します。
  • observability：プロジェクトのデフォルトのログスコープを解決し、ログのサンプルを Logs Explorer に表示される内容と一致させます。
  • cloudasset、cloudbilling：請求先アカウント全体を検索する「回答 3」の場合にのみ必要です。

監査を実行する ID に必要な IAM ロールです。このスキルがロールを付与することはありません。スクリプトはユーザー自身の認証情報で実行され、その認証情報で読み取り可能な情報のみを読み取ります。ステップで権限エラーが発生した場合、アドバイザリーに該当ステップが示されます。必要なロールを以下から確認し、ユーザーに伝えてください。

ロール	必要な用途
roles/logging.viewer、roles/monitoring.viewer	すべての監査：ログバケット、シンク、ログサンプル、ボリューム指標
roles/bigquery.jobUser、roles/bigquery.dataViewer（エクスポートデータセット上）	請求エクスポートからの請求額
他プロジェクトのログビューに対する roles/logging.viewAccessor	それらを含むデフォルトのログスコープを通じたサンプルの読み取り
roles/cloudasset.viewer、roles/billing.viewer（請求先アカウント）	請求先アカウント全体に対する --billing-mode=search
roles/logging.configWriter	Observability Analytics への任意のアップグレード（ステップ 3B）のみ

[ -f /tmp/finops_venv/bin/python ] || (uv venv /tmp/finops_venv && uv pip install -r scripts/requirements.txt --python /tmp/finops_venv/bin/python)

同梱のスクリプトは Google Cloud API リクエストにタグを付けます。自分で実行するコマンドにも、各コマンドにインラインでタグを付けてください。

• gcloud：CLOUDSDK_METRICS_ENVIRONMENT="google-skills google-skills/1.0 (skill:cloud-logging-finops)" gcloud ...
• HTTP：curl -H "User-Agent: google-skills/1.0 (skill:cloud-logging-finops)" ...

ステップ 2：データの収集

以下のコレクターをバックグラウンドプロセスとして開始します（数秒から数分以上かかります）。実行中にステップ 2.5 に進んでください。

/tmp/finops_venv/bin/python scripts/collect_logging_data.py \
  --project-id {project_id} --billing-mode={none|explicit|search}

任意のオプション：--billing-project、--billing-dataset、--billing-table（例： billing-proj.ds.gcp_billing_export_v1_XXXX またはキュレーション済みの FinOps ビュー）。

出力：logging_usage_summary.json、monthly_details/、service_details/、 および [FINOPS ADVISORY] 行（ステップ 3 を参照）。コレクターの出力の最後には、各ステージの所要時間を示す [COLLECTION PROFILE] テーブルがあります。実行時間がステップ 0 の所要時間を超えた場合や、ユーザーから監査に時間がかかった理由を尋ねられた場合は、推測する前にそのテーブルを確認してください。

ステップ 2.5：レポートで何を明らかにするかを尋ねる

コレクターの実行中に、必ずこの質問をしてください（複数選択可）。ユーザーが回答を省略した場合は、次の5つのトピックすべてを扱います。

このレポートで何を明らかにしますか？

• 費用はどこに向かっているか — サービス別、ストリーム別のアトリビューション
• 支出は増えているか — 傾向と予測
• 安全に停止できるものは何か — 具体的なコスト削減策
• これらのログは実際に何を示しているか — 最も多いパターンとサンプル
• 重大度と監査ログの状況

ユーザーの選択によって、どの出力を詳しく読み、要約で何を優先するかが決まります。コレクターが収集する内容は変わりません。

関心事項	詳しく読む項目
アトリビューション	service_details/*.json、daily_services
増加傾向	monthly_details/*.json、mom_patterns、cost_projection
コスト削減策	reduction_actions、extraneous_spend
ログの内容	severity_summary.samples_by_service、granular_analytics.top_signatures（Observability Analytics のみ）
重大度／監査	severity_summary、保留されたルールの理由

説明文は insights/executive_summary.html に記述します（ エグゼクティブサマリーの作成を参照）。 コスト削減策は記述しないでください。生成されたレポートの「Cost Optimizer」タブに、reduction_actions から取得した項目が表示されます。

注意

assets/report_template.html は絶対に編集しないでください。

ステップ 3：注意事項に従う

A. コストの数値の根拠をユーザーに伝える

重要

数値が請求額に基づくものでない場合（billing_metadata.invoiced）、どこを調べ、何が見つかり、数値が何に基づくのかを、わかりやすい言葉でユーザーに伝えてください。内部情報（ステージ番号、モード名、HTTP コード、「quota project」、「Cloud Asset Inventory」）はログと billing_metadata.fallback_chain に記録してください。

• 回答1：指定された場所に費用情報がなかった（explicit_table または explicit_scope のステップが found ではない）：コレクターはユーザーが指定した範囲を超えて検索しません。ステップの detail に基づき、何が問題だったか（このプロジェクトの行がない、その場所にエクスポートテーブルがない、クエリが失敗したなど）を伝え、費用は定価による推定額であることを説明し、場所を修正して再実行するか、回答3で再実行するよう提案してください。
• 回答2（user_declared_no_export）：「請求エクスポートがないとのことでしたので、検索はしていません。費用は請求額ではなく、定価による推定額です。」スキップした検索を、検索し尽くしたかのように説明しないでください。
• 回答3：何も見つからなかった（billing_account のステータスが not_found）：「このプロジェクトと請求先アカウントを検索しましたが、請求エクスポートは見つかりませんでした。費用は、直近30日間における定価による推定額です（各 SKU の価格と無料利用枠を引用してください：pricing.skus）。」エクスポートの設定を勧められるのはこの場合のみです。定価の出典として、公式料金ページ (https://cloud.google.com/products/observability/pricing)を引用してください。
• 回答3：権限の問題で検索に失敗した（いずれかのステップのステータスが inconclusive）：検索を完了できなかったため、費用は推定額であると伝えてください。請求エクスポートが存在しないとは伝えないでください。検索は完了していません。
• 回答3：このプロジェクトのテーブルが該当しなかった（local_project のステータスが no_project_records）：「このプロジェクトには請求エクスポートがありますが、このプロジェクトのレコードは含まれていなかったため、請求先アカウントの残りの範囲を検索しました。」その後、前述のとおり、より広い範囲での検索結果を報告してください。
• **一部の期間のみ実績がある場合：**各月には actual_bq_billing または usage_estimated のラベルが付いています。エグゼクティブサマリーには、正確な日付の境界を明記してください。

定価に基づく場合は、精度向上のためにエクスポートを勧めてください。今後の監査では、複数月分の割引適用後の実際の請求額が使用されます。

B. オブザーバビリティ分析

オブザーバビリティ分析は以前、ログ分析と呼ばれていました。スクリプト内の注意事項とフィールド名には、今も旧名称が使われています。

• 無効： 注意事項を提示し、ログバケットのアップグレードは元に戻せないことも伝えてから、回答の最後を直接的な質問で締めくくります。例："ログバケット _Default をオブザーバビリティ分析にアップグレードしますか？この操作は元に戻せません。" ユーザー自身で実行する方法を伝えるだけでは、質問したことになりません。ユーザーがそのログバケットのアップグレードを承認した後に限り、/tmp/finops_venv/bin/python scripts/enable_log_analytics.py --project-id {project_id} を実行します。どちらの場合も、監査は Cloud Monitoring で続行されます。

注意

注意事項を提示するのと同じターン、または「必要なことは何でもして」といった一般的な許可だけを得た状態で、enable_log_analytics.py や gcloud logging buckets update --enable-analytics を実行してはいけません。

• 24 時間未満： サンプルが蓄積される（約1～2時間）までは、Cloud Monitoring の14日間のベースラインを使用します。
• 1～13日： レポートにサンプル期間を記載します。
• 14日以上： 完全な SQL 分析を使用します。
• Representative logs unavailable の注意事項： ストリームが空なのではなく、環境でログエントリを読み取れないためサンプルがありません（roles/logging.viewer が必要です）。エラーとロールを伝えます。ストリームごとの詳細は severity_summary.sample_errors にあります。
• サンプルは空だが、ストリームには量がある場合： サンプルは Logs Explorer と同様に、プロジェクトのデフォルトログスコープを通じて読み取られます（analytics_metadata.log_read_scope）。source が project で note がある場合、スコープを解決できなかったため、このプロジェクトのログバケット外に保管されたログは読み取られていません。そのことを伝え、note の内容を伝えます。ストリームにログがないとは決して言わないでください。

C. 測定の整合性

注意

オブザーバビリティ分析のペイロードバイト数の合計から算出したコストや量を引用してはいけません。請求対象の量を約2倍に過大評価します。

質問	ソース
コスト、取り込み済み GiB	請求データのエクスポート（billing.query_logging_billing_costs、daily_gib、monthly_costs）
サービス構成	logging.googleapis.com/billing/bytes_ingested（resource_type）
ログストリーム／重大度別の量	logging.googleapis.com/byte_count（log、severity）
重大度の構成、エントリの内容	オブザーバビリティ分析の SQL（constants.PAYLOAD_BYTES_SQL）

• 合計値は、請求書がある場合は請求書から取得します。メトリクスは構成比の算出にのみ使用します。メトリクスから算出した合計値を、請求書の合計値と並べて示してはいけません。
• byte_count（受信量）と billing/bytes_ingested（請求対象量）は約1.5倍以上異なります。互いに割り算してはいけません。
• telemetry_integrity.status が degraded の場合、記載された日の減少は自然に解消されないメトリクスの不具合に見えることを伝え、telemetry_integrity.note に記載された制限事項も繰り返します。何も変化していないと断定してはいけません。
• is_partial: true の月は月初から現在までの期間です。そのように明記し、完全な月や「先月」と呼んではいけません。

D. 余分な支出

extraneous_spend.headline は保守的な下限です。reduction_actions.actions のうち counted: true のアクション（重複バケットへのルーティング、フローログのサンプリング、DEBUG ログ、古い除外設定）の合計であり、それぞれの対策で削減される分だけを正確に計上します。それ以外はすべて表に出しますが、計上はしません。対象期間超過（定量化されていません）、サンプリングされた除外ルール（推定値）、Data Access 監査ログ（withheld 内）が該当します。

1. 目安ではなく下限（≥ X%）として報告します。「最大で」とは言わないでください。
2. status が insufficient_data の場合、数値は示しません。推測値、ベンチマーク、$0 も示さないでください。
3. アクションの flag は、読者向けに書かれているため、一字一句そのまま引用します。
4. 計上しないアクションや uncounted_total_pct は、削減余地として触れることはできますが、見出しの数値に加算してはいけません。
5. headline.exceeds_sanity_ceiling が true の場合、見出しの数値は信頼できないと伝え、計上対象のうち最大のアクションを挙げて、手動確認が必要であることを明示します。数値は示しません。
6. inventory_unavailable が空でない場合、ログシンク、除外設定、フローログの各アクションは確認されていないと伝えます。存在しないとは言わないでください。
7. Data Access 監査ログに触れる場合（withheld の項目がある場合、またはユーザーがログの名前を挙げた場合）は、コンプライアンス上の判断が必要なため、数値に含めていないと伝えます。コンプライアンスやセキュリティのポリシーにより、無効化や除外が禁止されていることが多いため、対応する前に所有者の確認が必要です。

E. 除外フィルターとアクション

• フィルターと削減額があるのは Cost Optimizer のアクションだけです。Service Details のボリュームは削減額ではありません。sample_coverage.shown_pct を報告します。
• ルールのサンプル期間の GiB（granular_analytics.exclusion_candidates）ではなく、アクションの月間数値（monthly_gib、monthly_usd）を引用します。
• rule_scope: stream は、そのストリーム内の該当する重大度のログエントリをすべて削除することを意味します。その旨を伝えてください。
• refused_claims が空でない場合、安全ゲートによって除外されたストリームを挙げます。

アクションとして提示してはいけないもの：CRITICAL／ALERT／EMERGENCY（インシデントのシグナル）、無料の _Required ストリーム（$0、監査ログの保持）、Data Access 監査ログ（コンプライアンス上必須の場合が多いため、報告はしても計上しない）、および測定済みのボリュームがないストリーム。

注意

手書きの除外フィルターには、重大度の条件を含めてください（DEFAULT の場合は severity = "DEFAULT" を指定します。省略するとすべてに一致します）。URL エンコードされたログ ID（compute.googleapis.com%2Ffirewall）を使用してください。エスケープされていないログテキストや、ローテーションするトークン（UUID、IP アドレス、長い整数、時刻）を正規表現に埋め込んではいけません。また、上記の一覧を遵守してください。

ステップ 4：レポートを作成して渡す

/tmp/finops_venv/bin/python scripts/build_report.py --summary logging_usage_summary.json --insights-dir insights/ --output log_usage_report.html

build_report.py は、insights/executive_summary.html を指定しない限り、エグゼクティブサマリーを作成します。

ユーザーが実際にいる場所から、クリックすると完全にレンダリングされたレポートが開くリンクを 1 つ提示してください。生の HTML や、存在しないファイルへのリンクではいけません。リンクを投稿する前に、実際に開けることを確認してください。

続けて、ユーザーが確認できる内容（グラフ、サービス別の詳細、コピー可能なフィルター付きの優先順位付きアクション、✓ Prove It ドロワー）を列挙し、このプロジェクトのデータに基づく、回答としてそのまま尋ねられるフォローアップ質問を 3～4 件提案してください。

ユーザーから具体的な質問があった場合は、monthly_aggregations（latest_complete_month は最新の完了済み月を示し、各月の top_service はその月の Top Cost Driver です）、mom_patterns、cost_projection、trailing_30d_summary（その top_driver は請求書を使わないレポート上の Top Cost Driver です）、granular_analytics（Observability Analytics の実行時のみ存在）、またはサービス／月ごとの詳細ファイルを参照し、GiB と USD の両方で直接回答してください。

ステップ 5：追加の質問

フェーズ 1（デフォルト）： ディスク上の JSON を基に、数文または簡単な表で回答し、データからは判断できないことを明示したうえで、そこで止めて、さらに掘り下げる方法を 3～4 つ提示します。収集を再実行したり、ソースを再クエリしたりしないでください。

質問の内容	参照先
重大度について	severity_summary、その重大度の granular_analytics.top_signatures
サービスについて	service_details/{service}.json、そのサービスの top_signatures と top_log_names
最適化アクションについて	reduction_actions.actions 内の該当項目（claims、refused_claims、flag、counted）

フェーズ 2（ユーザーが方向を選んだ後のみ）： 必要な深さまで掘り下げます。コレクターが測定した _AllLogs ビューである analytics_metadata.table_name に対して、Observability Analytics SQL を実行します。ステップ 3 の適用は引き続き必要です。

ステップ 6：根拠を示す

provenance.claims[<id>] には、各主要数値の formula、sources（正確なクエリ、Google Cloud コンソールのリンク、手順。各アクションにつき最大 10 個のストリームのみ）、コンソールとの差分として判明している differences、実行可能な checks（すべてのストリームを対象）が記録されています。ID には latest_complete_spend、mtd_run_rate、trailing_30d_volume、estimated_run_rate、top_cost_driver、extraneous_spend、severity_costs、service_mix、action::<action id> があります。ほかの項目から組み立てられた主張は、see_also にそれらの項目を記載します（extraneous_spend → 該当する集計済みアクション）。それらも根拠を示してください。verify_claim.py は、それらも合わせて再確認します。

数値の根拠を求められた場合：

1. まず、ディスク上のデータから： 入力値を使って計算式を順に説明します。各ソースについて、Google Cloud コンソールのリンク、記録されているクエリの正確な内容、手順を列挙し、その後に differences を示します。
2. 同じ応答内で、バックグラウンドで： /tmp/finops_venv/bin/python scripts/verify_claim.py --summary <summary> --claim "<id>" を実行します。完了を待たないでください。
3. 完了後： （check | report | live | Δ | ✓/△/✗）の表と、1 行の判定を示します。△ の理由は記録されている differences を用いて説明し、✗ の原因はそれぞれ 1 行で示します。

注意

根拠を示す依頼は、ソースを再クエリしてよい唯一の依頼です。その場合も verify_claim.py 経由に限ります。収集を再実行したり、記録済みのクエリを変更したりしないでください。

該当する場合は、以下を明示してください。主張の価格算定方式が per_sku（各 SKU の価格と無料枠は pricing.skus）か、blended（理由は pricing.notes）か。サービス別および重大度別の数値はクレジットを除外していること。また、cross_project_billing の場合、これを再現するには課金エクスポートのデータセットに対する roles/bigquery.dataViewer と roles/bigquery.jobUser が必要であること。