App Hosting Monitoring and Logging Guide

Overview

Firebase App Hosting leverages Cloud Build for the build process and Cloud Run for runtime execution, both accessible through Cloud Logging. This guide provides comprehensive instructions for accessing and analyzing deployment and runtime logs using both Firebase CLI and gcloud CLI.

Quick Reference

Common Monitoring Tasks

Build Monitoring: Check Cloud Build logs
Runtime Monitoring: Check Cloud Run logs
Configuration Verification: Verify backend has environment field set
Secret Management: Use firebase apphosting:secrets:grantaccess (not gcloud IAM)
Configuration Check: Check backend environment setting in Firebase Console
Authentication Verification: Check service account permissions

Essential Commands

# Check backend configuration (verify environment field is set)
firebase apphosting:backends:get BACKEND_NAME --project=PROJECT_ID

# List recent builds
gcloud logging read "resource.type=build" --limit=10 --project=PROJECT_ID

# Check specific build logs
gcloud logging read "resource.type=build AND resource.labels.build_id=\"BUILD_ID\"" --project=PROJECT_ID

# Check runtime logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=\"SERVICE_NAME\"" --project=PROJECT_ID

# Grant secret access to backend
firebase apphosting:secrets:grantaccess SECRET_NAME --backend BACKEND_NAME --project=PROJECT_ID

Prerequisites

Required Tools

gcloud CLI: For deep log analysis
Firebase CLI: For App Hosting management
Proper Authentication: Access to the target project

Authentication Setup

# Set the correct project
gcloud config set project PROJECT_ID

# Authenticate (if needed)
gcloud auth login

# Verify authentication
gcloud auth list

Understanding App Hosting Architecture

Build Process (Cloud Build)

Source Code: GitHub repository
Build Trigger: GitHub Actions or manual deployment
Build Environment: Cloud Build container
Output: Container image for Cloud Run

Runtime Process (Cloud Run)

Container: Built from Cloud Build output
Service: Cloud Run service instance
Domain: App Hosting managed domain
Logs: Application and system logs

Step-by-Step Debugging Process

Step 1: Identify the Issue

Check Deployment Status via Firebase Console

Go to Firebase Console
Select your project:
- Production: toto-f9d2f (toto-app) or toto-bo (toto-bo)
- Staging: toto-f9d2f-stg (toto-app) or toto-bo-stg (toto-bo)
Navigate to App Hosting → Rollouts
Check the last 2-3 rollouts for failures

Check Deployment Status via Firebase CLI

# List App Hosting backends
firebase apphosting:backends:list

# Get specific backend details
firebase apphosting:backends:get BACKEND_NAME

# List recent rollouts
firebase apphosting:rollouts:list --project toto-f9d2f

# Get specific rollout details
firebase apphosting:rollouts:get ROLLOUT_ID --project toto-f9d2f

# Check build status
firebase apphosting:builds:list --project toto-f9d2f --limit 5

Identify Build/Rollout

Build ID: Format like build-2025-10-06-002
Status: READY, FAILED, IN_PROGRESS
Commit: Associated Git commit hash

Step 2: Access Cloud Build Logs (Build Issues)

List Recent Builds

# Via gcloud
gcloud logging read "resource.type=build" --limit=20 --project=PROJECT_ID

# Via gcloud builds
gcloud builds list --project toto-f9d2f --limit 5
gcloud builds log BUILD_ID --project toto-f9d2f

Get Specific Build Logs

gcloud logging read "resource.type=build AND resource.labels.build_id=\"build-2025-10-06-002\"" --project=PROJECT_ID --limit=500

Filter for Errors Only

gcloud logging read "resource.type=build AND resource.labels.build_id=\"build-2025-10-06-002\" AND (textPayload:\"error\" OR textPayload:\"Error\" OR textPayload:\"ERROR\")" --project=PROJECT_ID

Common Build Issues

Secret Access: Permission 'secretmanager.versions.get' denied
Dependencies: package.json not found or npm install failed
Configuration: Misconfigured Secret or environment variable issues
Build Commands: npm run build failures

Step 3: Access Cloud Run Logs (Runtime Issues)

Get Service Information

# List Cloud Run services
gcloud run services list --project=PROJECT_ID

# Get service details
gcloud run services describe SERVICE_NAME --region=REGION --project=PROJECT_ID

Access Runtime Logs

# Get logs for specific service
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=\"toto-bo-stg-backend\" AND resource.labels.location=\"us-central1\"" --project=PROJECT_ID --limit=500

# Filter for errors
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=\"toto-bo-stg-backend\" AND (textPayload:\"error\" OR textPayload:\"Error\" OR textPayload:\"ERROR\")" --project=PROJECT_ID

# View runtime logs via Firebase CLI
firebase functions:log --project toto-f9d2f

Common Runtime Issues

Application Crashes: Unhandled exceptions
Database Connection: Firestore permission issues
Environment Variables: Missing or incorrect values
Memory Issues: Out of memory errors
Timeout Issues: Request timeout errors

Common Deployment Failure Causes

1. Build Failures

Symptoms:

Build step fails
TypeScript compilation errors
Missing dependencies
Build timeout

Debug Steps:

Check build logs in Firebase Console
Verify package.json dependencies
Check tsconfig.json configuration
Verify build command in apphosting.yaml:
```
scripts:
  buildCommand: npm run build
```

Common Fixes:

Update dependencies: npm install
Fix TypeScript errors
Increase build timeout if needed
Check Node.js version compatibility

2. Environment Variable Issues

Symptoms:

Runtime errors about missing variables
Authentication failures
API connection errors

Debug Steps:

Check apphosting.yaml environment variables
Verify secrets are set in Firebase Console:
- Go to App Hosting → Settings → Secrets

Check if variables are available at BUILD vs RUNTIME:

env:
  - variable: MY_VAR
    secret: my-secret-name
    availability: [BUILD, RUNTIME]  # or just [RUNTIME]

Common Fixes:

Add missing environment variables
Verify secret names match
Check variable availability (BUILD vs RUNTIME)

3. Runtime Failures

Symptoms:

Application crashes on startup
Health check failures
500 errors

Debug Steps:

Check runtime logs
Verify runCommand in apphosting.yaml:
```
scripts:
  runCommand: npm start
```
Check application startup code
Verify all required services are accessible

Common Fixes:

Fix application startup errors
Verify database connections
Check service account permissions
Verify API endpoints are accessible

4. Configuration Issues

Symptoms:

Deployment succeeds but app doesn't work
Wrong environment configuration
Missing files

Debug Steps:

Check apphosting.yaml configuration

Verify outputFiles includes all necessary files:

outputFiles:
  serverApp:
    include: [.next, public, package.json, next.config.js]

Verify environment-specific configs:
- apphosting.yaml (default)
- apphosting.production.yaml (production)
- apphosting.staging.yaml (staging)

Common Fixes:

Update outputFiles to include missing files
Fix environment-specific configurations
Verify file paths are correct

5. Authentication/Permission Issues

Symptoms:

Service account errors
Permission denied errors
Firebase Admin initialization failures

Debug Steps:

Verify service account credentials:

env:
  - variable: FIREBASE_PRIVATE_KEY
    secret: firebase-private-key
  - variable: FIREBASE_CLIENT_EMAIL
    secret: firebase-client-email

Check service account permissions in GCP Console
Verify Firebase Admin initialization code

Common Fixes:

Update service account credentials
Grant necessary IAM roles
Fix Firebase Admin initialization

6. Backend Configuration Issues

Problem: `Cannot find module '/workspace/server.js'` or missing files in runtime

Symptoms:

Build succeeds but runtime fails with "Cannot find module" errors
Missing node_modules, server.js, or other critical files
outputFiles configuration appears correct but isn't being applied

Root Cause: Backend is missing the environment field, so it's using the default apphosting.yaml instead of environment-specific configuration files (apphosting.staging.yaml or apphosting.production.yaml).

How to Check:

# Compare backend configuration between working staging and failing production
firebase apphosting:backends:get BACKEND_NAME --project=PROJECT_ID

# Look for the "environment" field in the JSON output
# Working: {"environment": "staging", ...}
# Failing: {no environment field}

Solution:

Set environment via Firebase Console (CLI doesn't support this yet):
- Go to Firebase Console → App Hosting
- Select your backend
- Navigate to Settings
- Set "Environment" to either staging or production
Verify the correct config file is being used:
- Staging backends should use apphosting.staging.yaml
- Production backends should use apphosting.production.yaml
Trigger a new deployment to apply the changes

Prevention:

Always set the environment field when creating new backends
Ensure environment-specific YAML files have matching outputFiles configurations
Document which backends should use which environment

Problem: Secret permission errors despite correct IAM bindings

Root Cause: Using manual gcloud IAM bindings instead of Firebase's secret access management.

Solution:

# Use Firebase CLI's built-in secret access management
firebase apphosting:secrets:grantaccess SECRET_NAME --backend BACKEND_NAME --project=PROJECT_ID

# NOT: gcloud secrets add-iam-policy-binding (this may not work for App Hosting)

Grant access to all secrets for a backend:

# List all secrets first
gcloud secrets list --project=PROJECT_ID

# Grant access to each secret
firebase apphosting:secrets:grantaccess SECRET_NAME_1 --backend BACKEND_NAME --project=PROJECT_ID
firebase apphosting:secrets:grantaccess SECRET_NAME_2 --backend BACKEND_NAME --project=PROJECT_ID
# ... repeat for all required secrets

Advanced Debugging Techniques

Time-Based Filtering

# Get logs from last hour
gcloud logging read "resource.type=build AND timestamp>=\"$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)\"" --project=PROJECT_ID

# Get logs from specific time range
gcloud logging read "resource.type=build AND timestamp>=\"2025-10-06T00:00:00Z\" AND timestamp<=\"2025-10-06T23:59:59Z\"" --project=PROJECT_ID

Severity-Based Filtering

# Get only ERROR and CRITICAL logs
gcloud logging read "resource.type=build AND severity>=ERROR" --project=PROJECT_ID

# Get logs with specific severity
gcloud logging read "resource.type=build AND severity=ERROR" --project=PROJECT_ID

Text Pattern Matching

# Search for specific error messages
gcloud logging read "resource.type=build AND textPayload:\"Misconfigured Secret\"" --project=PROJECT_ID

# Search for multiple patterns
gcloud logging read "resource.type=build AND (textPayload:\"error\" OR textPayload:\"failed\" OR textPayload:\"exception\")" --project=PROJECT_ID

Firebase Console Alternative

Visual Log Access

Go to Firebase Console → App Hosting
Select your backend
Go to Rollouts tab
Click on specific rollout
Click "View logs" or "View in Cloud Logging"

Advantages of Console

Pre-filtered logs: Automatically filtered for specific rollout
Visual interface: Easier to navigate for beginners
Direct links: Quick access to Cloud Build and Cloud Run logs
Real-time updates: Live log streaming

Proper Development Workflow

Local Development → Staging → Production

Local Development

# Work on feature branch
git checkout -b feature/my-feature

# Test locally
cd toto-app
npm run dev

# Run tests
npm test
npm run lint

# Build locally to catch errors
npm run build

Deploy to Staging

# Commit and push to staging branch
git checkout staging
git merge feature/my-feature
git push origin staging

# Or deploy manually
firebase use toto-f9d2f-stg
firebase deploy --only apphosting

Test in Staging
- Verify functionality works
- Check logs for errors
- Run smoke tests
- Verify environment variables

Deploy to Production (Main)

# Only after staging is verified
git checkout main
git merge staging
git push origin main

# Or deploy manually
firebase use toto-f9d2f
firebase deploy --only apphosting

Pre-Deployment Checklist

Before deploying, verify:

Code builds successfully locally (npm run build)
All tests pass (npm test)
Linting passes (npm run lint)
Environment variables are configured
Secrets are set in Firebase Console
apphosting.yaml is correct
Dependencies are up to date
No TypeScript errors
Application starts successfully locally

Emergency Rollback

If deployment fails in production:

# List previous successful rollouts
firebase apphosting:rollouts:list --project toto-f9d2f

# Rollback to previous version
firebase apphosting:rollouts:rollback ROLLOUT_ID --project toto-f9d2f

Debugging Checklist

Before Starting

Identify the correct project ID
Ensure proper authentication
Note the specific build ID or rollout
Understand the expected behavior

For Build Issues

Check Cloud Build logs for the specific build ID
Look for secret access errors
Verify build configuration
Check for dependency issues
Review build command execution

For Runtime Issues

Check Cloud Run logs for the service
Look for application errors
Verify environment variables
Check database connections
Monitor resource usage

After Finding the Issue

Document the root cause
Implement the fix
Test the solution
Update documentation if needed

Automation & Scripts

Quick Debug Script

#!/bin/bash
# Quick debug script for App Hosting issues

PROJECT_ID="toto-bo-stg"
BUILD_ID="build-2025-10-06-002"
SERVICE_NAME="toto-bo-stg-backend"

echo "🔍 Checking recent builds..."
gcloud logging read "resource.type=build" --limit=5 --project=$PROJECT_ID

echo "🔍 Checking specific build logs..."
gcloud logging read "resource.type=build AND resource.labels.build_id=\"$BUILD_ID\"" --project=$PROJECT_ID --limit=100

echo "🔍 Checking runtime logs..."
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=\"$SERVICE_NAME\"" --project=$PROJECT_ID --limit=50

Error Monitoring Script

#!/bin/bash
# Monitor for specific errors

PROJECT_ID="toto-bo-stg"
ERROR_PATTERN="error|Error|ERROR|failed|Failed|FAILED"

echo "🚨 Monitoring for errors..."
gcloud logging read "resource.type=build AND (textPayload:\"$ERROR_PATTERN\")" --project=$PROJECT_ID --limit=20

Getting Help

If deployment continues to fail:

Check Firebase Status: Firebase Status Page
Review Logs: Check all logs (build, runtime, application)
Compare with Working Version: Check what changed since last successful deployment
Test Locally: Reproduce the issue locally if possible
Check Dependencies: Verify all dependencies are compatible

Additional Resources

Google Cloud Documentation

Firebase Documentation

Best Practices

Log Analysis

Start with recent logs: Focus on the most recent deployments
Filter by severity: Look for ERROR and CRITICAL logs first
Check both build and runtime: Issues can occur in either phase
Use time-based filtering: Narrow down to specific timeframes
Document findings: Keep track of issues and solutions

Prevention

Test locally first: Use npm run build locally before deploying
Check secrets: Verify all required secrets exist and are accessible
Monitor deployments: Set up alerts for failed deployments
Regular maintenance: Clean up old logs and unused secrets
Documentation: Keep debugging guides updated

💡 Pro Tip: The combination of Firebase CLI for App Hosting management and gcloud CLI for deep log analysis provides the most comprehensive debugging experience. Use the Firebase Console for quick visual access and gcloud CLI for detailed, scriptable log analysis.

Overview​

Quick Reference​

Common Monitoring Tasks​

Essential Commands​

Prerequisites​

Required Tools​

Authentication Setup​

Understanding App Hosting Architecture​

Build Process (Cloud Build)​

Runtime Process (Cloud Run)​

Step-by-Step Debugging Process​

Step 1: Identify the Issue​

Check Deployment Status via Firebase Console​

Check Deployment Status via Firebase CLI​

Identify Build/Rollout​

Step 2: Access Cloud Build Logs (Build Issues)​

List Recent Builds​

Get Specific Build Logs​

Filter for Errors Only​

Common Build Issues​

Step 3: Access Cloud Run Logs (Runtime Issues)​

Get Service Information​

Access Runtime Logs​

Common Runtime Issues​

Common Deployment Failure Causes​

1. Build Failures​

2. Environment Variable Issues​

3. Runtime Failures​

4. Configuration Issues​

5. Authentication/Permission Issues​

6. Backend Configuration Issues​

Problem: Cannot find module '/workspace/server.js' or missing files in runtime​

Problem: Secret permission errors despite correct IAM bindings​

Advanced Debugging Techniques​

Time-Based Filtering​

Severity-Based Filtering​

Text Pattern Matching​

Firebase Console Alternative​

Visual Log Access​

Advantages of Console​

Proper Development Workflow​

Local Development → Staging → Production​

Pre-Deployment Checklist​

Emergency Rollback​

Debugging Checklist​

Before Starting​

For Build Issues​

For Runtime Issues​

After Finding the Issue​

Automation & Scripts​

Quick Debug Script​

Error Monitoring Script​

Getting Help​

Additional Resources​

Google Cloud Documentation​

Firebase Documentation​

Related Guides​

Best Practices​

Log Analysis​

Prevention​

Overview

Quick Reference

Common Monitoring Tasks

Essential Commands

Prerequisites

Required Tools

Authentication Setup

Understanding App Hosting Architecture

Build Process (Cloud Build)

Runtime Process (Cloud Run)

Step-by-Step Debugging Process

Step 1: Identify the Issue

Check Deployment Status via Firebase Console

Check Deployment Status via Firebase CLI

Identify Build/Rollout

Step 2: Access Cloud Build Logs (Build Issues)

List Recent Builds

Get Specific Build Logs

Filter for Errors Only

Common Build Issues

Step 3: Access Cloud Run Logs (Runtime Issues)

Get Service Information

Access Runtime Logs

Common Runtime Issues

Common Deployment Failure Causes

1. Build Failures

2. Environment Variable Issues

3. Runtime Failures

4. Configuration Issues

5. Authentication/Permission Issues

6. Backend Configuration Issues

Problem: `Cannot find module '/workspace/server.js'` or missing files in runtime

Problem: Secret permission errors despite correct IAM bindings

Advanced Debugging Techniques

Time-Based Filtering

Severity-Based Filtering

Text Pattern Matching

Firebase Console Alternative

Visual Log Access

Advantages of Console

Proper Development Workflow

Local Development → Staging → Production

Pre-Deployment Checklist

Emergency Rollback

Debugging Checklist

Before Starting

For Build Issues

For Runtime Issues

After Finding the Issue

Automation & Scripts

Quick Debug Script

Error Monitoring Script

Getting Help

Additional Resources

Google Cloud Documentation

Firebase Documentation

Related Guides

Best Practices

Log Analysis

Prevention