Skip to main content
← back to extensions

Gcp/vertex Usage

@webframp/gcp/vertex-usagev2026.08.21.2· 1d agoMODELS
01README

GCP Vertex AI token usage monitoring — multi-project scanning of token_count metrics via the Cloud Monitoring API. Provides per-model breakdowns with input/output direction split and tokens-per-minute rates.

Authentication

Uses a GCP service account JSON key (signed JWT exchange). Provide via serviceAccountJson global arg or set GOOGLE_APPLICATION_CREDENTIALS env var pointing to a key file. No gcloud CLI dependency.

Required Permissions

  • monitoring.timeSeries.list on each project

Usage

swamp model create @webframp/gcp/vertex-usage vertex-usage \
  --global-arg 'projects=["my-project","my-other-project"]' \
  --global-arg 'serviceAccountJson=<vault:gcp/sa-key>'

# Scan all projects
swamp model method run vertex-usage scan_projects

# Single project
swamp model method run vertex-usage get_token_usage --input project=my-project

Methods

  • scan_projects — Fan-out across all configured projects, per-model breakdown
  • get_token_usage — Single project with model breakdown
02Release Notes

2026.08.21.2

Changed: The projects global argument now requires at least one non-empty project ID; previously an empty list silently produced a scan of zero projects with no explanation. Service-account credential loading errors — a missing or unreadable GOOGLE_APPLICATION_CREDENTIALS file, or a malformed JSON key — now name the path/field that failed instead of surfacing a bare filesystem or JSON.parse error. Cloud Monitoring API failures now include the response body and the project ID in the error message instead of just an HTTP status code, and a malformed JSON response from either the OAuth token endpoint or the Monitoring API now raises a clear "returned malformed JSON" error naming the request that failed.

2026.08.21.1

Changed: Added .describe(...) documentation to previously undocumented fields in ModelUsageSchema, ProjectUsageSchema, and ScanResultsSchema (model/project identity fields, token counts, period and rate fields, and the truncated flag). Tightened the project argument on get_token_usage to require a non-empty string. No behavioral changes.

2026.07.31.1

Fixed: README incorrectly stated authentication uses gcloud CLI (Application Default Credentials). The extension actually uses a service account JSON key with signed JWT exchange. README now documents the correct auth mechanism, required role (roles/monitoring.viewer), and all global arguments.

03Models1
@webframp/gcp/vertex-usagev2026.08.21.2gcp/vertex_usage.ts
fn scan_projects(days: number)
Fan-out scan across all configured GCP projects. Returns per-project token usage with model-level breakdown.
ArgumentTypeDescription
daysnumberLookback period in days
fn get_token_usage(project: string, days: number)
Get token usage for a single GCP project with model breakdown.
ArgumentTypeDescription
projectstringGCP project ID
daysnumberLookback period in days

Resources

scan_results(6h)— Multi-project Vertex AI token usage scan results
single_scan(6h)— Single project Vertex AI token usage scan
04Previous Versions8
2026.08.21.1

2026.08.21.1

Changed: Added .describe(...) documentation to previously undocumented fields in ModelUsageSchema, ProjectUsageSchema, and ScanResultsSchema (model/project identity fields, token counts, period and rate fields, and the truncated flag). Tightened the project argument on get_token_usage to require a non-empty string. No behavioral changes.

2026.07.31.1

Fixed: README incorrectly stated authentication uses gcloud CLI (Application Default Credentials). The extension actually uses a service account JSON key with signed JWT exchange. README now documents the correct auth mechanism, required role (roles/monitoring.viewer), and all global arguments.

2026.07.31.1

2026.07.31.1

Fixed: README incorrectly stated authentication uses gcloud CLI (Application Default Credentials). The extension actually uses a service account JSON key with signed JWT exchange. README now documents the correct auth mechanism, required role (roles/monitoring.viewer), and all global arguments.

2026.07.21.1

2026.07.21.1

Changed: Authentication no longer shells out to gcloud auth print-access-token. Auth now uses a GCP service account JSON key — the extension signs a JWT (RS256) and exchanges it for an access token at Google's token endpoint. This eliminates the gcloud CLI runtime dependency.

Added: serviceAccountJson optional global argument (sensitive). Accepts a stringified service account JSON key. Falls back to reading the file at GOOGLE_APPLICATION_CREDENTIALS if omitted.

Upgrade note: Existing model instances must provide credentials via one of:

  1. --global-arg 'serviceAccountJson=<vault:path/to/sa-key>' (recommended)
  2. Set GOOGLE_APPLICATION_CREDENTIALS env var pointing to a key file

The extension no longer requires gcloud to be installed or authenticated.

2026.07.18.1

2026.07.18.1

Added: An upgrades array entry (no-op) to vertex_usage.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.

2026.07.10.1

Changed: Replaced internal org identifiers in the manifest usage examples with generic placeholders. No functional, API, or schema changes.

2026.07.10.1

2026.07.10.1

Changed: Replaced internal org identifiers in the manifest usage examples with generic placeholders. No functional, API, or schema changes.

2026.06.21.1
2026.06.15.1
2026.05.12.1
05Stats
A
100 / 100
Downloads
5
Archive size
16.8 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License declared1/1earned
  • Verified public repository2/2earned
Repository
https://github.com/webframp/swamp-extensions
06Platforms
07Labels
#gcp#vertex-ai#ai#token-usage#monitoring#finops