Skip to main content

Cloud Billing API Setup Guide

This guide explains how to set up the Cloud Billing API integration for accurate cost monitoring.

📋 Overview​

The cost monitoring system now uses the Cloud Monitoring API to fetch real usage metrics and calculate costs for:

  • Firestore: Document reads, writes, and storage
  • Cloud Run (App Hosting): CPU, memory, and request costs
  • Firebase Storage: Storage volume costs

🔐 Prerequisites​

  1. Service Account with appropriate permissions
  2. Cloud Monitoring API enabled
  3. Project IDs configured

🚀 Setup Steps​

Step 1: Enable Cloud Monitoring API​

For each Firebase project (toto-f9d2f, toto-bo, toto-ai-hub):

  1. Go to Google Cloud Console
  2. Select your project
  3. Navigate to APIs & Services → Library
  4. Search for "Cloud Monitoring API"
  5. Click Enable

Step 2: Configure Service Account Permissions​

The service account used by toto-bo needs the following IAM roles:

  1. Go to IAM & Admin → Service Accounts
  2. Find your service account (the one used by toto-bo)
  3. Click Edit → Add Another Role
  4. Add these roles:
    • Monitoring Viewer (roles/monitoring.viewer)
    • Cloud Billing Account Viewer (roles/billing.accountViewer) - Optional, for billing account info
    • Cloud Monitoring Metrics Reader (roles/monitoring.metricReader)

Minimum Required Role:

  • roles/monitoring.viewer - Allows reading monitoring metrics

Step 3: Configure Environment Variables​

Add these environment variables to your Firebase App Hosting configuration or .env:

# GCP Project IDs (optional - defaults provided)
GCP_PROJECT_ID_APP=toto-f9d2f
GCP_PROJECT_ID_BO=toto-bo
GCP_PROJECT_ID_AI_HUB=toto-ai-hub

# Billing Account ID (optional - will be auto-detected)
GCP_BILLING_ACCOUNT_ID=XXXXX-XXXXX-XXXXX

For Firebase App Hosting, add to apphosting.yaml:

env:
  - variable: GCP_PROJECT_ID_APP
    value: toto-f9d2f
    availability:
      - RUNTIME
  - variable: GCP_PROJECT_ID_BO
    value: toto-bo
    availability:
      - RUNTIME
  - variable: GCP_PROJECT_ID_AI_HUB
    value: toto-ai-hub
    availability:
      - RUNTIME

Step 4: Verify Service Account Credentials​

The system uses the same service account credentials as Firebase Admin:

  • FIREBASE_PRIVATE_KEY
  • FIREBASE_CLIENT_EMAIL
  • FIREBASE_PROJECT_ID

These should already be configured. Verify they have the monitoring permissions listed in Step 2.

🔍 How It Works​

Data Flow​

Cost Monitoring Dashboard
    ↓
/api/cost-monitoring/comprehensive
    ↓
Cloud Monitoring API (fetch usage metrics)
    ↓
Calculate costs using pricing formulas
    ↓
Return real-time cost data

Fallback Behavior​

If the Cloud Monitoring API is unavailable or returns errors:

  • Firestore: Falls back to estimated costs based on document counts
  • Cloud Run: Shows placeholder with error message
  • Storage: Shows placeholder with error message

The system gracefully degrades to estimates, so the dashboard always works.

📊 Metrics Queried​

Firestore​

  • firestore.googleapis.com/api/request_count (ReadDocument, WriteDocument)
  • firestore.googleapis.com/database/storage_size

Cloud Run​

  • run.googleapis.com/container/cpu/utilizations
  • run.googleapis.com/container/memory/utilizations
  • run.googleapis.com/request_count

Firebase Storage​

  • storage.googleapis.com/storage/total_bytes

⚠️ Important Notes​

  1. Cost Calculation: The system calculates costs from usage metrics using Google Cloud pricing formulas. Actual billing may vary slightly due to:

    • Discounts and credits
    • Regional pricing differences
    • Minimum billing thresholds

  2. API Limits: Cloud Monitoring API has rate limits. The system queries metrics efficiently, but if you have many projects, consider:

    • Caching results (5-minute TTL recommended)
    • Using Cloud Scheduler for periodic updates

  3. Permissions: The service account needs access to all projects you want to monitor. If projects are in different GCP organizations, you may need separate service accounts.

  4. Time Range: Metrics are aggregated over the selected time range. For accurate costs:

    • Use consistent time ranges
    • Be aware that some metrics are sampled (e.g., CPU utilization)

🐛 Troubleshooting​

Error: "Billing API client not available"​

  • Cause: Missing service account credentials
  • Fix: Ensure FIREBASE_PRIVATE_KEY and FIREBASE_CLIENT_EMAIL are set

Error: "Permission denied" or "403 Forbidden"​

  • Cause: Service account lacks monitoring permissions
  • Fix: Add roles/monitoring.viewer role to service account

Error: "API not enabled"​

  • Cause: Cloud Monitoring API not enabled for project
  • Fix: Enable Cloud Monitoring API in GCP Console

Costs showing as $0 or placeholders​

  • Cause: No usage data or API errors
  • Fix:
    1. Check Cloud Monitoring API is enabled
    2. Verify service account permissions
    3. Check project IDs are correct
    4. Review server logs for specific errors

Costs seem inaccurate​

  • Cause: Usage metrics may be sampled or aggregated
  • Fix:
    • Compare with actual GCP billing dashboard
    • Note that calculated costs are estimates based on usage
    • For exact costs, use BigQuery billing export (future enhancement)

🔄 Alternative: BigQuery Billing Export​

For exact cost data (not estimates), you can set up BigQuery billing export:

  1. Enable BigQuery billing export in GCP Console
  2. Export billing data to BigQuery
  3. Query BigQuery for exact costs

This is more complex but provides 100% accurate billing data. See the roadmap for future implementation.

📚 Related Documentation​

✅ Verification Checklist​

  • Cloud Monitoring API enabled for all projects
  • Service account has roles/monitoring.viewer permission
  • Environment variables configured (or defaults are correct)
  • Service account credentials are valid
  • Cost monitoring dashboard shows real data (not just placeholders)
  • Fallback to estimates works if API fails

Last Updated: January 2025
Status: ✅ Implemented - Ready for testing