gcloud

# Google Cloud Integration ## Connection - **Project**: `BIGQUERY_PROJECT_ID` from Settings → Data sources - **Service account**: from `GOOGLE_APPLICATION_CREDENTIALS_JSON` - **Auth**: `GOOGLE_APPLICATION_CREDENTIALS_JSON` credential (JSON credentials string) — no ADC fallback - **IAM roles**: `monitoring.viewer`, `run.viewer`, `cloudfunctions.viewer`, `logging.viewer` - **Caching**: 5-minute in-memory cache, max 120 entries ## Server Lib & API Routes - **File**: `server/lib/gcloud.ts` ### Exported Functions | Function | Description | | --------------------------------------------------------------------------- | ---------------------------------- | | `listCloudRunServices()` | List all Cloud Run services | | `listCloudFunctions()` | List all Cloud Functions | | `queryMetrics(filter, period, aligner?, reducer?, groupBy?)` | Query Cloud Monitoring time series | | `getServiceMetrics(serviceType, serviceName, metric, period, extraFilter?)` | Convenience metric query | | `listLogEntries(filter, pageSize?)` | Read Cloud Logging entries | ### API Routes | Route | Description | | -------------------------- | ----------------------- | | `GET /api/gcloud/services` | List Cloud Run services | | `GET /api/gcloud/metrics` | Query metrics | | `GET /api/gcloud/logs` | Read log entries | ### Agent Action Use `gcloud` for agent-facing Google Cloud work. Do not call `/api/gcloud/*` directly from the agent. | Mode | Args | Description | | ---------- | ----------------------------------------------------------- | ------------------------------------------- | | `services` | | List Cloud Run services and Cloud Functions | | `metrics` | `service`, `serviceType`, `metric`, `period`, `extraFilter` | Query Cloud Monitoring | | `logs` | `service`, `serviceType`, `severity`, `limit` | Read Cloud Logging | ### Dashboard - `/adhoc/gcloud` — Google Cloud Health dashboard ## Google Cloud APIs Used - Cloud Run Admin API v2: `/v2/projects/{project}/locations/-/services` - Cloud Functions API v2: `/v2/projects/{project}/locations/-/functions` - Cloud Monitoring API v3: `/v3/projects/{project}/timeSeries` - Cloud Logging API v2: `/v2/entries:list` ## Key Metrics - **Cloud Run**: `run.googleapis.com/request_count`, `request_latencies`, `container/instance_count`, `container/cpu/utilization` - **Cloud Functions**: `cloudfunctions.googleapis.com/function/execution_count`, `execution_times`, `active_instances` ## Key Patterns & Gotchas - **Scale**: 78 Cloud Run services, 237+ Cloud Functions — UI uses searchable dropdown - **Alignment periods**: 1h→60s, 6h→300s, 24h→600s, 7d→3600s - `getServiceMetrics` auto-selects aligner/reducer based on metric name (latency→percentile, request_count→ALIGN_DELTA, memory→ALIGN_MEAN) - `queryMetrics` maps point values from `doubleValue`, `int64Value`, or distribution mean - `listLogEntries` uses POST payload; returns entries reversed - Project ID comes from the user's configured `BIGQUERY_PROJECT_ID`.