Spaces:
Sleeping
Sleeping
| # Observatory Troubleshooting Guide | |
| ## Issue: Blank Page on Launch | |
| ### Fixes Applied (2026-06-16) | |
| 1. **Added Welcome Screen**: When no run/task is selected, the app now shows a proper welcome screen with feature overview instead of just an error message. | |
| 2. **Improved Error Handling**: Added clearer warning messages when run/task data fails to load. | |
| 3. **Better Initial State**: The app now gracefully handles the initial render before any data is loaded. | |
| ### How to Launch | |
| Use the provided launch script: | |
| ```bash | |
| ./launch_observatory.sh | |
| ``` | |
| Or manually: | |
| ```bash | |
| cd /workspace/ainn-cm-poc-data-agent | |
| source .venv/bin/activate | |
| streamlit run src/data_agent_baseline/observatory/app.py --server.port 8501 | |
| ``` | |
| ### Access the App | |
| - **Local**: http://localhost:8501 | |
| - **External**: http://138.108.24.100:8501 (if accessible) | |
| ### Common Issues | |
| #### 1. Blank Page After Launch | |
| **Symptoms**: Browser shows empty white/dark page | |
| **Solutions**: | |
| - Hard refresh the browser (Ctrl+Shift+R or Cmd+Shift+R) | |
| - Clear browser cache | |
| - Try a different browser | |
| - Check browser console for JavaScript errors (F12 → Console tab) | |
| #### 2. "No runs found" Message | |
| **Symptoms**: Sidebar shows "⚠️ No runs found" | |
| **Solutions**: | |
| - Check the artifact path in the sidebar Configuration expander | |
| - Verify the path exists: `/data3/dataFAIR/kdd-dev/public/artifacts/runs/` | |
| - Verify run folders exist in that path | |
| - Click the refresh button after correcting the path | |
| #### 3. Welcome Screen Stuck | |
| **Symptoms**: Shows welcome screen but selecting run/task doesn't load | |
| **Solutions**: | |
| - Check that the selected run folder contains: | |
| - Task subdirectories (task_XXX/) | |
| - `comprehensive_evaluation.csv` (optional but recommended) | |
| - Check browser console for errors | |
| - Try refreshing the page | |
| #### 4. CSS/Styling Issues | |
| **Symptoms**: Page loads but styling looks wrong or content is hidden | |
| **Solutions**: | |
| - The Mission Control CSS is injected when the Mission Summary tab loads | |
| - Try switching to the Mission Summary tab | |
| - Check browser console for CSS errors | |
| - Disable browser extensions that might interfere with styling | |
| #### 5. Port Already in Use | |
| **Symptoms**: Error message "Port 8501 is not available" | |
| **Solutions**: | |
| ```bash | |
| # Kill existing Streamlit processes | |
| pkill -f streamlit | |
| # Or kill specific port | |
| lsof -ti:8501 | xargs kill -9 | |
| # Then relaunch | |
| ./launch_observatory.sh | |
| ``` | |
| ### Verification Steps | |
| Run these commands to verify everything is set up correctly: | |
| ```bash | |
| # 1. Verify Python environment | |
| source .venv/bin/activate | |
| python3 -c "import streamlit; print(f'Streamlit version: {streamlit.__version__}')" | |
| # 2. Verify Observatory imports | |
| python3 -c "from src.data_agent_baseline.observatory import RunDiscovery; print('✓ Imports OK')" | |
| # 3. Verify artifact path | |
| ls -la /data3/dataFAIR/kdd-dev/public/artifacts/runs/ | head -10 | |
| # 4. Check run count | |
| python3 -c "from src.data_agent_baseline.observatory import RunDiscovery; d=RunDiscovery(); runs=d.discover_runs(); print(f'{len(runs)} runs found')" | |
| ``` | |
| ### Expected Behavior | |
| 1. **First Load**: You should see a welcome screen with: | |
| - Title: "🔬 Agent Observatory" | |
| - Info message: "👈 Select a run and task from the sidebar" | |
| - Feature list | |
| - Quick start guide | |
| 2. **After Selecting Run**: The sidebar should show: | |
| - Current Context card with run details | |
| - Task dropdown populated with available tasks | |
| - Artifact status pills | |
| 3. **After Selecting Task**: The main content should show: | |
| - Mission Summary tab (default) | |
| - Hero header with gradient background | |
| - Executive summary card | |
| - KPI cards | |
| - Execution flow visualization | |
| ### Debug Mode | |
| To see more detailed logs: | |
| ```bash | |
| streamlit run src/data_agent_baseline/observatory/app.py \ | |
| --server.port 8501 \ | |
| --logger.level=debug | |
| ``` | |
| ### Getting Help | |
| If issues persist: | |
| 1. Check the Streamlit logs in the terminal | |
| 2. Check browser console (F12) for JavaScript errors | |
| 3. Verify all dependencies are installed: `uv sync` | |
| 4. Try the minimal test app: `streamlit run test_streamlit_minimal.py --server.port 8503` | |
| ### Known Limitations | |
| - First load may take 1-2 seconds for run discovery | |
| - Large trace files (>10MB) may take longer to parse | |
| - Some older runs may lack full metadata (gracefully degraded) | |
| - CSS styling only applies after Mission Summary tab is viewed | |
| ### Performance Tips | |
| - Discovery is O(n) in number of runs — startup may be slower with 500+ runs | |
| - Task loading includes trace parsing — may take 2-3 seconds for large traces | |
| - Session state caching avoids re-loading on page interactions | |
| - Switching between tasks reloads data — switching between tabs does not | |