Admin Diagnostics Dashboard

The Diagnostics Dashboard provides system health monitoring and build version information for both web and API services.

Overview

The Diagnostics page allows administrators to:

• View current build information for web and API services
• Monitor Git commit versions for deployed code
• Check build timestamps to verify deployment recency
• Identify environment configuration (development, staging, production)
• Copy diagnostic information for support tickets

Page Layout

The dashboard displays two main information cards side-by-side:

1. Web Build Info - Frontend application build details
2. API Build Info - Backend service build details

Each card shows identical information types for its respective service.

Key Features

Build Information Display

Each service card displays three critical pieces of information:

Git SHA:

• Full commit hash of the deployed code
• Allows exact version tracking in Git repository
• Useful for debugging and rollback operations

Build Time:

• Timestamp when the application was compiled
• Displayed in your local timezone
• Helps verify deployment recency

Environment:

• Current runtime environment (development, staging, production)
• Capitalized for easy visibility
• Critical for understanding deployment context

Copy All Info Button

The "Copy All Info" button (top-right corner) provides quick access to formatted diagnostic data:

1. Click the button to copy all build information to clipboard
2. Information is formatted as plain text for easy pasting
3. Button shows "Copied!" confirmation for 2 seconds
4. Includes timestamp of when the copy was made

Use cases for copied diagnostics:

• Support ticket submissions
• Deployment verification
• Version comparison between environments
• Incident reporting

Common Workflows

Verify Recent Deployment

1. Navigate to `/admin/diagnostics`
2. Check the Build Time for both web and API
3. Confirm timestamps match expected deployment time
4. Verify Git SHA matches your Git repository commit

Compare Web and API Versions

1. Check if Web and API Git SHA values match

2. Mismatched SHAs may indicate:

   • Partial deployment (only one service updated)
   • Deployment in progress
   • Configuration error

3. Contact DevOps if versions should match but don't

Report Issues to Support

1. Click "Copy All Info" button
2. Paste copied diagnostics into support ticket
3. Include description of the issue you're experiencing
4. Support team can quickly identify your exact deployment version

Environment Verification

1. Check the Environment field on both cards

2. Verify you're on the expected environment:

   • Development: Local or dev servers
   • Staging: Pre-production testing environment
   • Production: Live customer-facing deployment

3. Critical before making configuration changes

RBAC Requirements

Minimum Role: Admin
Required Permissions: `monitoring:read`
2FA Required: No

Only administrators with monitoring permissions can access this page. This ensures sensitive deployment information is restricted to authorized personnel.

Troubleshooting

"Failed to load diagnostics" Error

Possible causes:

• API service is down or unreachable
• Network connectivity issues
• Authentication token expired

Solutions:

1. Refresh the page to retry the request
2. Check if API health endpoint responds: `/api/health`
3. Verify you're still logged in (token may have expired)
4. Check browser console for detailed error messages
5. Contact system administrator if issue persists

Loading State Persists

Symptoms: Page shows loading skeleton indefinitely

Solutions:

1. Check browser console for JavaScript errors
2. Verify API endpoint `/api/v1/admin/alpha-ops/version` is accessible
3. Ensure admin client is properly initialized
4. Hard refresh the page (Ctrl+Shift+R or Cmd+Shift+R)

Git SHA Shows "unknown"

Possible causes:

• Build was not created from Git repository
• Git metadata not available during build
• Local development build

Solutions:

• For production: This indicates build process issue, contact DevOps
• For development: This is normal if running `pnpm dev`
• Verify CI/CD pipeline includes Git metadata in builds

Environment Shows Wrong Value

Possible causes:

• Environment variable `NODE_ENV` not set correctly
• Deployment configuration mismatch

Solutions:

1. Verify deployment configuration file matches environment
2. Check environment variables on server
3. Contact DevOps to verify deployment process

Best Practices

Regular Monitoring

• Check diagnostics after each deployment to verify success
• Compare Git SHAs between environments during promotions
• Keep diagnostic snapshots before and after major changes

Issue Reporting

• Always include diagnostic information in support tickets
• Use "Copy All Info" for accurate version reporting
• Include timestamp of when issue occurred

Version Tracking

• Document Git SHAs for stable releases
• Compare SHAs when investigating regression issues
• Use build timestamps to verify deployment order

Related Articles

• System Health Monitoring
• Deployment Process Guide
• Admin Authentication Guide
• RBAC Permission Management