Skip to content

Troubleshooting

Jump to bottom
Alex-CloudOps edited this page Mar 8, 2026 · 1 revision

Troubleshooting

Common issues, error messages, and their resolutions for observability-dashboard.

Installation Issues

pip install fails with permission error

Error:

ERROR: Could not install packages due to an OSError

Resolution: Ensure your virtual environment is activated:

venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

Runtime Issues

Dashboard runs but produces no output

Symptoms: Terminal returns to prompt immediately with no pipeline stages printed

Resolution:

  1. Verify you are running from the project root:
   cd observability-dashboard
   python main.py
  1. Verify main.py contains the correct pipeline orchestration code
  2. Verify the if __name__ == "__main__": block is present in main.py

ModuleNotFoundError

Error:

ModuleNotFoundError: No module named 'dashboard.aggregator'

Resolution: Verify all files in the dashboard/ folder are named correctly:

dir dashboard

Expected files:

  • __init__.py
  • aggregator.py
  • exporter.py
  • summary.py
  • transformer.py

Exports not generated

Symptoms: Dashboard runs but exports/ folder is empty

Resolution:

  1. Verify exports/ directory exists:
   dir exports
  1. If missing, create it:
   mkdir exports
  1. Verify export paths in config.ini match your directory structure:
   [exports]
   summary_file = exports/dashboard_summary.json
   csv_file = exports/dashboard_export.csv
   powerbi_file = exports/powerbi_dataset.json

Dashboard always shows sample data

Symptoms: Metrics never change despite running other portfolio repos

Resolution: The dashboard falls back to sample data when live data files are not present in data/.

To use live data:

  1. Copy output files from each portfolio repo into data/:
    • cloud-telemetry-agent output → data/telemetry.json
    • synthetic-uptime-monitor/logs/report.json → data/uptime.json
    • incident-alert-pipeline/data/incidents.json → data/incidents.json
    • log-intelligence-engine/logs/output/report.json → data/log_intelligence.json
  2. Re-run the dashboard:
   python main.py

Ecosystem health always CRITICAL

Symptoms: Health status never improves despite resolving issues

Common Causes:

Open CRITICAL incidents: The most common cause. Check data/incidents.json for open CRITICAL incidents:

from pipeline.incident_manager import get_open_incidents
open_incidents = get_open_incidents()

Close resolved incidents to clear CRITICAL status.

Stale data files: The data/ files haven't been refreshed with latest outputs from portfolio repos. Copy fresh data files and re-run.

Sample data driving CRITICAL: The built-in sample data includes 3 open CRITICAL incidents by design. Replace with live data to see accurate health status.

Component health score unexpected

Symptoms: A component shows CRITICAL when you expect HEALTHY

Resolution: Review the transformation thresholds in transformer.py:

def _score_telemetry_health(metrics):
    cpu = metrics.get('cpu_percent', 0)
    memory = metrics.get('memory_percent', 0)
    disk = metrics.get('disk_percent', 0)

    if cpu >= 95 or memory >= 95 or disk >= 95:
        return 'CRITICAL'
    elif cpu >= 85 or memory >= 90 or disk >= 90:
        return 'DEGRADED'
    return 'HEALTHY'

Adjust thresholds if your environment has different baseline expectations.

Power BI Issues

Power BI won't load powerbi_dataset.json

Resolution:

  1. Verify the file exists in exports/:
   dir exports
  1. Verify the JSON is valid:
   python -c "import json; json.load(open('exports/powerbi_dataset.json')); print('JSON valid')"
  1. In Power BI use Get Data → JSON — not Text/CSV

Power BI data not refreshing

Resolution:

  1. Run the dashboard to generate fresh exports:
   python main.py
  1. In Power BI Desktop click Refresh in the Home ribbon
  2. If Power BI cached the old file path — re-import via Get Data → JSON

Power BI shows nested fields unexpectedly

Resolution: Some fields in powerbi_dataset.json are nested objects. In Power BI:

  1. Click the expand icon next to nested fields in the query editor
  2. Select the specific fields you want to flatten
  3. Click OK to expand into columns

Data Issues

CSV export has incorrect values

Resolution: The CSV is generated directly from transformed data. If values look wrong:

  1. Check exports/dashboard_summary.json for the same values
  2. If summary is also wrong, the issue is in transformer.py
  3. Verify the source data files in data/ contain expected values

data/ files not found warning

Symptoms:

Input directory not found: data/telemetry.json

Resolution: This is expected behavior — the aggregator falls back to sample data automatically. No action required unless you want live data.

To suppress: copy live data files from portfolio repos into data/.

Git & GitHub Issues

git push fails — password rejected

Resolution: GitHub requires a Personal Access Token:

  1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Generate new token with repo scope
  3. Use token as password when git prompts

⚠️ Never share your Personal Access Token in chat, email, or any public forum.

Clone this wiki locally