Observability & Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
The Observability and Troubleshooting systems in FusionOps provide a comprehensive framework for monitoring application health, diagnosing connection issues, and handling runtime exceptions across the monorepo architecture. These tools ensure that developers can maintain the stability of the Astro-based frontend and the distributed Cloudflare Workers backend.
The system is categorized into three primary layers: proactive infrastructure validation, real-time runtime error handling, and specialized connectivity debugging. These components work together to surface issues ranging from missing environment variables to database connection failures and React component crashes.
Infrastructure Validation & Setup Checks
FusionOps utilizes dedicated scripts to validate environment configurations and service availability before and during development. These scripts perform "pre-flight" checks to ensure that the complex web of Cloudflare Workers, D1 databases, and Neon Postgres instances is correctly mapped and accessible.
Connectivity Debugging
The debug-connections.js script provides a six-point check of the entire system's connectivity. It validates environment variables, database connections, and worker responsiveness.
| Check | Target | Description |
|---|---|---|
| Check 1 | Environment Variables | Validates VITE_API_BASE and NEON_DATABASE_URL presence. |
| Check 2 | Neon Database | Executes a test query (SELECT 1) and lists available tables. |
| Check 3 | API Worker | Tests the /settings endpoint of the primary API worker. |
| Check 4 | D1 Databases | Uses Wrangler CLI to verify fusionops-main, pixel, and callback databases. |
| Check 5 | Workers | Directly pings worker URLs for lp-factory-api and lp-factory-pixel. |
| Check 6 | Frontend Config | Ensures api.js production base URL matches the environment. |
Sources: debug-connections.js:61-220, INFRASTRUCTURE_SETUP.md:270-300
Diagnostic Logic Flow
The following diagram illustrates the automated validation sequence performed during a system debug:
The script uses execSync to interface with the Cloudflare Wrangler CLI and fetch for HTTP-based service health checks.
Sources: debug-connections.js:145-185, scripts/check-setup.mjs
Runtime Error Handling
The frontend application utilizes React's error boundary pattern to prevent total application failure when specific "islands" or dashboard components encounter exceptions.
Error Boundary Architecture
The ErrorBoundary.jsx component wraps high-risk areas of the dashboard. When a child component crashes, it captures the error and displays a fallback UI instead of a blank screen.
getDerivedStateFromError: Updates the component state to trigger the fallback UI.componentDidCatch: Logs the error details and the component stack trace to theErrorLog.
Sources: src/components/ErrorBoundary.jsx:5-25
Error Logging UI
The ErrorLog.jsx component provides a centralized view for developers to inspect captured runtime errors. This log persists in-memory and displays critical debugging information.
| Field | Description |
|---|---|
| Timestamp | When the error occurred. |
| Message | The primary error message. |
| Stack | The detailed trace identifying the file and line number. |
| Component | The specific component that triggered the boundary. |
Sources: src/components/ErrorLog.jsx:10-30
Infrastructure Monitoring
FusionOps monitors its distributed infrastructure via Cloudflare and Sentry integrations. This ensures observability across the 6 different Cloudflare Workers and the primary dashboard.
Service Monitoring Matrix
The project is configured to report errors and performance metrics to external providers as defined in the infrastructure documentation.
The system monitors requests, errors, CPU time, and memory usage for each worker through the Cloudflare Dashboard.
Sources: CLAUDE.md:120-140, INFRASTRUCTURE_SETUP.md:320-335
Troubleshooting Common Issues
The repository includes specific guidance for resolving recurring development and deployment failures.
Build and Deployment Failures
Common troubleshooting steps for the CI/CD pipeline and local build process include:
- Missing
.env.local: Ensure the environment file is seeded from.env.example. - Astro Script Directives: Verify scripts use
is:inlineto prevent Astro from stripping them. - Wrangler Auth: Run
wrangler whoamiandwrangler tailto diagnose worker deployment issues. - Node Version: The project strictly requires Node.js ≥ 22.
Sources: CLAUDE.md:320-350, README.md:10-25
Database Connectivity
If D1 or Neon connections fail, the following actions are recommended:
- Validate D1 bindings in
wrangler.tomlagainst the IDs generated duringwrangler d1 create. - Check
VITE_NEON_URLin the frontend; it must includesslmode=require. - Use
wrangler d1 executeto manually verify that migrations (like0001_init.sql) have been applied.
Sources: INFRASTRUCTURE_SETUP.md:60-100, debug-connections.js:105-130
Conclusion
Observability in FusionOps is designed to handle the complexity of a multi-cloud, serverless environment. By combining proactive pre-flight connection scripts with reactive React Error Boundaries and Cloudflare-native monitoring, the system provides developers with the visibility needed to troubleshoot issues from the database layer up to the user interface. Significant significance is placed on the initial setup validation to prevent configuration drift in production environments.
Sources: CLAUDE.md, INFRASTRUCTURE_SETUP.md