/cloud-logging-finops

name: cloud-logging-finops
metadata:
  version: "1.0.0"
  category: CloudObservabilityAndMonitoring
description: >-
  Audits Cloud Logging costs for a Google Cloud project: the charges for log entries written to log buckets, the services, log streams and severities that drive them, and the log sinks that route them. Reconciles Cloud Billing export costs with Cloud Monitoring volume metrics, and generates a FinOps report with charts and copy-paste exclusion filters. Use when auditing Cloud Logging spend, finding logging waste, identifying top logging contributors, generating log cost reduction reports, or creating log sink exclusion filters. Don't use for querying log entries (use cloud-logging-query-generation), configuring Cloud Monitoring alerts, or querying metrics/traces.

Cloud Logging Finops

**Non-interactive runs.** When no user can answer (e.g. a scheduled or automated run), ask nothing: audit the project named in the request, or the active gcloud project; use `--billing-mode=search`; cover all five report topics (Step 2.5); and never enable an API or upgrade a log bucket. Put anything that needed a user (a disabled API, a missing role, the upgrade advisory) in the report instead.

Step 0: Locate the Cloud Billing Export

The audit covers one Google Cloud project, `{project_id}`: the project the user names or, if they don't name one, the active gcloud project (`gcloud config get project`), confirmed with the user.

Discover everything else (log buckets, Observability Analytics, sinks, exclusions, metrics) yourself; never ask the user about those. The billing export is the exception: finding it unaided can mean scanning every project on the billing account, so ask once, before running anything, and don't start a search until the user has chosen answer 3 (single-select, using the host's question tool if it has one):

> **Do you know where the Cloud Billing export for `{project_id}` is?** > > 1. **Yes** — here it is *(the BigQuery table ID `project.dataset.table`, or > just the project and dataset)* > 2. **There's no billing export** for this project > 3. **No / not sure** — search for it *(seconds on a small project; on a large > billing account it can take a long time)*

Answer | Flags | Cost figures ------ | --------------------------------------------------------------------------------------------- | ------------ 1 | `--billing-mode=explicit` plus `--billing-table` (or `--billing-project`/`--billing-dataset`) | invoiced 2 | `--billing-mode=none` | list-price estimates 3 | `--billing-mode=search` *(default)* | invoiced if found, else estimates

Answer 3's search has no time limit: it checks `{project_id}` first (usually under 10 s, 1–2 min with many tables), then every project on its billing account (can take many minutes; progress prints every 30 s). Tell the user this before launching. If the wait is unacceptable, offer to switch to answer 1 (they look up the table) or answer 2 (skip the export and use list-price estimates). Don't suggest setting up an export to make the search faster.

If the search found an export, tell the user: *"Next time, pass `--billing-table=<table>` and discovery drops to about two seconds."*

Step 1: Environment Setup

Check these prerequisites before Step 2; fix only what is missing:

• **gcloud:** if `gcloud` is not installed, follow

https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt.

• **Project:** run `gcloud config get project`; if it isn't `{project_id}`

(from Step 0), run `gcloud config set project {project_id}`.

• **Credentials:** the scripts use Application Default Credentials. Run

`gcloud auth application-default login`, or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key.

• **Billing:** the project must have an active billing account attached.
• **APIs:** don't enable APIs up front; the Logging, Monitoring, BigQuery and

Observability APIs are on by default in new projects. Only if the collector reports an API as disabled (`SERVICE_DISABLED`, "has not been used in project"), name it, ask the user, and on approval run `gcloud services enable {api} --project={project_id}` (tagged as described below):

• `logging`, `monitoring`: required; without them there is nothing to

audit.

• `bigquery`: invoiced costs from the billing export.
• `observability`: resolves the project's default log scope, so log

samples match what Logs Explorer shows.

• `cloudasset`, `cloudbilling`: only answer 3's search across the billing

account.

IAM roles for the identity running the audit. The skill never grants roles: the scripts run with the user's own credentials and read only what those credentials can. When a step fails on permissions, its advisory names the step; tell the user which role below it needs:

Role | Needed for -------------------------------------------------------------------- | ---------- `roles/logging.viewer`, `roles/monitoring.viewer` | Every audit: log buckets, sinks, log samples, volume metrics `roles/bigquery.jobUser`, `roles/bigquery.dataViewer` (on the export dataset) | Invoiced costs from the billing export `roles/logging.viewAccessor` on log views in other projects | Reading samples through a default log scope that includes them `roles/cloudasset.viewer`, `roles/billing.viewer` (billing account) | `--billing-mode=search` across the billing account `roles/logging.configWriter` | Only the optional Observability Analytics upgrade (Step 3B)

[ -f /tmp/finops_venv/bin/python ] || (uv venv /tmp/finops_venv && uv pip install -r scripts/requirement