Skip to content
HomeStar Docs

Monitor System Health

This guide helps you understand the admin dashboard, interpret health indicators, and troubleshoot common issues.

Admin Dashboard

Understanding the Dashboard

Section titled “Understanding the Dashboard”

The admin dashboard provides at-a-glance system health monitoring.

Quick Health Check

Section titled “Quick Health Check”

When you open the dashboard, check these four key metrics:

Active Users

Currently logged in users

Normal: 5-50 during business hours Alert: >100 (possible attack) or 0 (authentication issue)

Total Listings

Properties in the system

Normal: Steady growth or stable Alert: Sudden drop (data loss?) or spike (duplicate import?)

API Health

External service status

Normal: Green (healthy) Alert: Yellow (degraded) or Red (down)

Sync Status

MLS data freshness

Normal: <6 hours ago Alert: >24 hours (sync failure)

Interpreting Health Indicators

Section titled “Interpreting Health Indicators”

MLS Connection

Section titled “MLS Connection”

Green Normal Operation

The system is successfully syncing with MLSGrid.

What it means:

  • Recent API calls succeeded
  • Authentication is valid
  • Data is being updated

No action needed.

Yellow Degraded

The connection is experiencing issues but still functional.

What it means:

  • Slow API responses (>2 seconds)
  • Intermittent failures (<10% error rate)
  • Partial data updates

Actions:

  1. Check the Recent Activity log for API errors
  2. Test MLSGrid API manually using your API key
  3. Review rate limit status (may be throttled)
  4. If persistent, schedule a manual sync during off-hours

Red Connection Failed

The system cannot communicate with MLSGrid.

What it means:

  • Authentication failure (invalid/expired API key)
  • Network connectivity issue
  • MLSGrid service outage

Actions:

  1. Click View Logs to see the specific error
  2. Verify your MLSGrid API key is valid and active
  3. Test network connectivity: curl https://api.mlsgrid.com/v1/Property
  4. Check MLSGrid status page for outages
  5. If authentication failed, update the API key in system settings

Search Index

Section titled “Search Index”

Green Up to Date

Semantic search is fully functional.

What it means:

  • Vision extraction jobs are completing successfully
  • Embeddings are current
  • Search results include recent listings

No action needed.

Yellow Outdated

Embeddings need to be regenerated.

What it means:

  • New properties added but not yet indexed
  • Vision extraction job pending or in progress
  • Search may miss recent listings

Actions:

  1. Navigate to Admin → Vision
  2. Check if an extraction job is already running
  3. If not, click Start Extraction to process unindexed properties
  4. Monitor job progress

Red Ollama Unreachable

The vision extraction system is offline.

What it means:

  • Ollama server is down or unreachable
  • Vision model not loaded
  • No embeddings being generated

Actions:

  1. Check Ollama server status: curl http://ollama-server:11434/api/version
  2. Verify the Ollama service is running
  3. Test model availability: ollama list
  4. If down, restart the Ollama service
  5. Re-run vision extraction once Ollama is back online

API Services

Section titled “API Services”

Green All Services Operational

All integrations are responding normally.

No action needed.

Yellow Non-Critical Service Degraded

A non-essential integration is experiencing issues.

Examples:

  • Analytics service slow
  • Email notifications delayed
  • Third-party API throttling

Actions:

  1. Check Recent Activity → Errors Only for details
  2. Determine if the service is critical for current operations
  3. If non-critical, monitor and allow time for recovery
  4. If persistent, contact the service provider

Red Critical Service Down

An essential integration is offline.

Examples:

  • Keycloak (authentication) unreachable
  • Database connection lost
  • Ollama (embeddings) offline

Actions:

  1. Immediate: Check the service status directly
  2. Authentication issues: Verify Keycloak is running and accessible
  3. Database issues: Check database server health and connections
  4. Embeddings issues: Restart Ollama and verify model availability
  5. Escalate: If you cannot resolve, contact system administrator or infrastructure team

Storage

Section titled “Storage”

Green Plenty of Space

Disk usage is under 70%.

No action needed.

Yellow Storage Warning

Disk usage is 70-90%.

Actions:

  1. Navigate to Admin → Data Management
  2. Review database size and record counts
  3. Check for large log files
  4. Consider cleaning up old data:
    • Export and archive old tour requests
    • Clear outdated suggestions
    • Remove old vision extraction job logs
  5. Plan for storage expansion if growth is ongoing

Red Storage Critical

Disk usage exceeds 90%.

Actions:

  1. Immediate: Stop non-critical processes (vision extraction, large data imports)
  2. Identify largest directories: du -h --max-depth=1 /data | sort -h
  3. Clear temporary files and logs
  4. Export and delete old data (with backups)
  5. Urgent: Expand storage capacity
  6. Monitor closely to prevent disk full errors

Investigating Problems

Section titled “Investigating Problems”

Using Recent Activity Logs

Section titled “Using Recent Activity Logs”

Navigate to Dashboard → Recent Activity to diagnose issues.

Filtering for Errors

Section titled “Filtering for Errors”
  1. Click the Activity Type dropdown
  2. Select Errors Only
  3. Review the error messages and timestamps
  4. Click on an error for full details (stack trace, request data)

Common Error Patterns

Section titled “Common Error Patterns”
Error TypePossible CauseNext Steps
401 UnauthorizedAPI key expired or revokedRegenerate API key
429 Too Many RequestsRate limit exceededReduce request frequency
500 Internal Server ErrorApplication bug or dependency failureCheck logs, report to developers
503 Service UnavailableService overloaded or maintenanceWait and retry, check service status

Correlating Events

Section titled “Correlating Events”

When investigating an issue:

  1. Note the timestamp of the problem
  2. Filter Recent Activity to that time range
  3. Look for related events:
    • User login before error (user-triggered issue?)
    • Data modification before failure (bad data?)
    • API call spike before slowdown (load issue?)
  4. Expand the time window to see if the pattern repeats

Quick Actions

Section titled “Quick Actions”

Common administrative tasks accessible from the dashboard:

User Management

Section titled “User Management”

When to use: New team member needs access, or account needs deactivation

  1. Click User Management
  2. Select Add User or find existing user
  3. Configure role (Admin, Broker, Agent)
  4. Assign to brokerage (if applicable)
  5. Save changes

Data Sync

Section titled “Data Sync”

When to use: MLS data is stale (>6 hours) or you need the latest listings immediately

  1. Click Trigger Manual Sync
  2. Confirm the action (may take several minutes)
  3. Monitor Sync Status for completion
  4. Verify Total Listings increased (if new properties were added)

System Settings

Section titled “System Settings”

When to use: Adjusting feature flags, API keys, or configuration

  1. Click System Settings
  2. Navigate to the relevant section
  3. Make your changes carefully (these affect all users)
  4. Save and test the change in a non-production environment first

View Logs

Section titled “View Logs”

When to use: Investigating errors, debugging issues, or auditing activity

  1. Click View Logs
  2. Select log type:
    • Application Logs — Backend errors and warnings
    • Access Logs — HTTP requests and responses
    • Audit Logs — User actions and data changes
  3. Filter by time range and severity
  4. Download logs for offline analysis if needed

Troubleshooting Workflows

Section titled “Troubleshooting Workflows”

User Reports “I Can’t Log In”

Section titled “User Reports “I Can’t Log In””
  1. Check Active Users — Are others logged in? (System-wide issue vs. user-specific)
  2. Review Recent Activity → User Events — Any failed login attempts for this user?
  3. Check API Services → Keycloak — Is authentication service healthy?
  4. Test login yourself with a test account
  5. If Keycloak is down, restart the service
  6. If user-specific, verify their account is active and not locked

Search Results Are Outdated

Section titled “Search Results Are Outdated”
  1. Check Sync Status — When was the last MLS data sync?
  2. If stale, trigger a Manual Sync
  3. Check Search Index health — Are embeddings up to date?
  4. If outdated, navigate to Admin → Vision and start an extraction job
  5. Monitor both sync and extraction jobs to completion
  6. Test search again once both are complete

Dashboard Shows High Error Rate

Section titled “Dashboard Shows High Error Rate”
  1. Filter Recent Activity → Errors Only
  2. Identify the most common error type
  3. Check if errors are concentrated:
    • Single user — User-specific issue (bad workflow, permissions)
    • Single endpoint — Service issue (API down, bug)
    • Across the board — System-wide issue (overload, network)
  4. Address the root cause based on concentration
  5. Monitor error rate after fix to confirm resolution
Section titled “Related Documentation”