Google API Monitoring

Dashboard und Sync-Infrastruktur fuer die Ueberwachung der Google Cloud API Quota-Nutzung pro Projekt.

Sync Command

php artisan google:sync-api-usage

Laeuft stuendlich via Scheduler. Holt fuer jedes konfigurierte Google Cloud Projekt:

1. Quota-Limits via serviceusage.googleapis.com/v1beta1 (consumerQuotaMetrics)
2. Quota-Usage via monitoring.googleapis.com/v3 (timeSeries mit rate/net_usage)

Der Command iteriert ueber alle Projekte in GOOGLE_API_USAGE_PROJECTS und synchronisiert Limits + Usage in die lokale Datenbank.

Location: app/Console/Commands/SyncGoogleApiUsage.php

JWT Authentication

Die Authentifizierung erfolgt ueber manuellen JWT-Token-Exchange -- kein gcloud CLI erforderlich.

Ablauf

1. Service Account Credentials aus GOOGLE_APPLICATION_CREDENTIALS (JSON-Datei) lesen
2. JWT mit cloud-platform Scope erstellen und mit dem Private Key signieren
3. Token-Exchange ueber POST https://oauth2.googleapis.com/token:

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<signed-jwt>"
}

4. Access Token aus Response verwenden fuer nachfolgende API-Calls

Location: app/Services/GoogleApiUsage/GoogleApiUsageService.php

Quota Limits API

Endpoint: GET https://serviceusage.googleapis.com/v1beta1/projects/{projectId}/services/{service}/consumerQuotaMetrics

Liefert alle definierten Quota-Metriken fuer einen Service (z.B. youtube.googleapis.com) inkl. Limit-Werten, Overrides und Units.

Gespeicherte Felder

project_id, service, quota_metric, display_name, unit,
limit_value, effective_limit_value, raw

effective_limit_value beruecksichtigt Admin-Overrides (erhoehte Limits via Google Cloud Console).

Usage Metrics API

Endpoint: GET https://monitoring.googleapis.com/v3/projects/{projectId}/timeSeries

Filter: metric.type="serviceruntime.googleapis.com/quota/rate/net_usage" AND resource.type="consumer_quota" AND resource.labels.service="{service}"

Zeitraum: Start of today Pacific Time (PT) bis jetzt (UTC). YouTube Quotas resetten um Mitternacht PT — daher wird der Abfragezeitraum auf den PT-Tag ausgerichtet, nicht auf UTC.

Gespeicherte Felder

project_id, service, quota_metric, date,
used_value, by_credential (JSON), collected_at

by_credential enthaelt die Usage aufgeschluesselt nach API Key (credential_id), sodass im Dashboard erkennbar ist, welcher Key wie viel Quota verbraucht.

Datenmodell

google_api_quota_limits

Spalte	Typ	Beschreibung
project_id	string	Google Cloud Project ID
service	string	API Service Name
quota_metric	string	Quota-Metrik-Identifier
display_name	string	Menschenlesbarer Name
unit	string	z.B. 1/min, 1/d
limit_value	integer	Standard-Limit
effective_limit_value	integer	Effektives Limit (nach Overrides)
raw	json	Vollstaendige API-Payload

Unique Constraint: (project_id, service, quota_metric, display_name, unit)

google_api_quota_usages

Spalte	Typ	Beschreibung
project_id	string	Google Cloud Project ID
service	string	API Service Name
quota_metric	string	Quota-Metrik-Identifier
date	date	Nutzungsdatum (PT-Tag, nicht UTC)
used_value	integer	Verbrauchte Units
by_credential	json	Aufschluesselung pro API Key
collected_at	timestamp	Zeitpunkt der Datenerhebung

Unique Constraint: (project_id, service, quota_metric, date)

Location: app/Models/GoogleApiQuotaLimit.php, app/Models/GoogleApiQuotaUsage.php

Dashboard UI

Route: /admin/google-api-usage (Admin-Gate geschuetzt)

Features

• Donut-Charts pro Quota-Typ: Used vs. Remaining mit Prozentanzeige
• Per-Project View: Jedes konfigurierte Projekt wird separat dargestellt
• Quota-Typen: Daily, per Minute, per Minute per User
• Quota-Reset: Naechster Reset-Zeitpunkt (Mitternacht PT in UTC angezeigt)
• Circuit Breaker Status: Gruener/roter Punkt pro API Key Pool (basiert auf Job-Fehlern, nicht auf Cloud Monitoring)
• QuotaGuard Metriken: Circuit-Opened, Jobs-Blocked, Jobs-Released pro Pool (tagesaktuell)
• No-Data Warning: Rote Callout + graue Charts wenn Google Cloud Monitoring API keine Usage-Daten liefert (verhindert irrefuehrende gruene Charts bei 0 default)
• Sync-Timestamp: Letzter erfolgreicher Sync-Zeitpunkt (auch sichtbar wenn keine Usage-Daten)
• Fehler-Meldungen: Sync-Probleme werden direkt im Dashboard angezeigt

Timezone-Kette

Alle drei Schichten (Service, Command, Dashboard) verwenden Pacific Time fuer den Quota-Tag:

Schicht	Timezone	Was passiert
API-Abfrage	PT → UTC	startOfDay('America/Los_Angeles')->utc() als Startzeit fuer Cloud Monitoring API
DB-Speicherung	PT	now('America/Los_Angeles')->toDateString() als date-Wert
Dashboard-Query	PT	now('America/Los_Angeles')->toDateString() fuer whereDate()
Cron	UTC	Nur Trigger (stuendlich), beeinflusst Datenlogik nicht

Location: app/Livewire/Admin/GoogleApiUsage/Index.php, resources/views/livewire/admin/google-api-usage/index.blade.php

IAM-Berechtigungen

Der Service Account benoetigt Leserechte auf jedem zu ueberwachenden Google Cloud Projekt:

Rolle	Zweck
roles/monitoring.viewer	Lesen von Usage-Metriken via Cloud Monitoring API
roles/serviceusage.serviceUsageViewer	Lesen von Quota-Limits via Service Usage API

Einrichtung pro Projekt

1. Google Cloud Console -> Projekt auswaehlen
2. IAM & Admin -> IAM -> + GRANT ACCESS
3. Service Account Email eintragen
4. Rollen Monitoring Viewer + Service Usage Viewer zuweisen
5. Projekt-ID zu GOOGLE_API_USAGE_PROJECTS hinzufuegen

YouTube API Key anlegen

1. Google Cloud Console -> Projekt waehlen/erstellen
2. APIs & Services -> Library -> "YouTube Data API v3" aktivieren
3. APIs & Services -> Credentials -> + CREATE CREDENTIALS -> API Key
4. Key einschraenken: API restrictions -> YouTube Data API v3
5. Key in .env eintragen

.env Variablen

Variable	Default	Beschreibung
GOOGLE_API_USAGE_PROJECTS	--	Kommaseparierte Google Cloud Project IDs
GOOGLE_APPLICATION_CREDENTIALS	--	Pfad zur Service Account JSON-Datei
GOOGLE_API_USAGE_SERVICE	youtube.googleapis.com	Zu ueberwachender API-Service

Relevante Dateien

Bereich	Pfad
Service (API Calls)	app/Services/GoogleApiUsage/GoogleApiUsageService.php
Repository (DB)	app/Services/GoogleApiUsage/GoogleApiUsageRepository.php
Sync Command	app/Console/Commands/SyncGoogleApiUsage.php
Livewire Dashboard	app/Livewire/Admin/GoogleApiUsage/Index.php
Config	config/google_api_usage.php
Models	app/Models/GoogleApiQuotaLimit.php, app/Models/GoogleApiQuotaUsage.php