Frequently Asked Questions

Common questions and troubleshooting tips for the Minimal Status Panel plugin.

šŸš€ Installation & Setup

Q: The plugin doesnā€™t appear in my Grafana installation

A: Check these common issues:

  1. Plugin directory: Ensure files are in the correct location: 
    ls /var/lib/grafana/plugins/minimal-status-panel/
# Should show: plugin.json, module.js, README.md, etc.
  2. Grafana restart: Always restart Grafana after plugin installation: 
    sudo systemctl restart grafana-server
  3. File permissions: Ensure Grafana can read the plugin files: 
    sudo chown -R grafana:grafana /var/lib/grafana/plugins/minimal-status-panel
  4. Grafana logs: Check for plugin loading errors: 
    sudo journalctl -u grafana-server -f

Q: I get ā€œPlugin not foundā€ errors

A: This usually indicates:

šŸ“Š Data & Queries

Q: The panel shows ā€œNo status data availableā€

A: This is the most common issue. Check:

  1. Query returns data: Use Query Inspector to verify your query returns results
  2. Required labels: Ensure your metrics have an instance label
  3. Metric name: The plugin looks for probe_success by default
  4. Data source: Verify your Prometheus data source is working

Debug steps:

# Test this query in Grafana Explore:
probe_success
# Should return metrics with instance labels

Q: Why do my services show as ā€œUnknownā€?

A: The plugin determines status from the probe_success metric value:

Check your Blackbox Exporter configuration and ensure itā€™s returning proper 1/0 values.

Q: Heartbeat bars are not showing real data

A: The plugin uses time-series data from your query. If you see uniform patterns, it means:

Q: How do I monitor non-HTTP services?

A: The plugin works with any Prometheus metric that has:

Examples:

# TCP port monitoring
probe_success{job="blackbox",module="tcp_connect"}

# Custom health checks
up{job="my-service"}

# Database connectivity
mysql_up{instance="db-server"}

šŸŽØ Display & Configuration

Q: Service names are too long/ugly

A: Use the Custom Service Names feature:

{
  "https://very-long-api-endpoint.company.com:8080/health": "API Service",
  "10.0.1.100:3306": "Database",
  "monitoring-system.internal.company.com": "Monitoring"
}

Q: How do I hide URLs from public displays?

A: In the panel options:

Q: The panel takes up too much space

A: Try these space-saving options:

Q: Colors donā€™t match my theme

A: The plugin automatically adapts to Grafanaā€™s light/dark themes. For custom colors:

āš” Performance & Optimization

Q: The panel is slow with many services

A: Optimize performance with:

  1. Reduce Max Items: Lower to 10-20 services per panel
  2. Increase Refresh Interval: Use 60+ seconds for overview dashboards
  3. Limit Time Range: Shorter ranges load faster
  4. Split Panels: Use multiple panels instead of one large panel
  5. Optimize Queries: Use specific label selectors

Q: Auto-refresh is too frequent/not working

A:

Q: Memory usage is high

A: The plugin limits heartbeat data to 50 points per service. High memory usage usually indicates:

šŸ”§ Advanced Configuration

Q: Can I use custom metrics instead of probe_success?

A: Yes! The plugin works with any metric that:

Example with custom metrics:

my_service_healthy{instance="service-name"}

Q: How do I group services by environment?

A: Use Prometheus label selectors:

# Production only
probe_success{environment="production"}

# Multiple environments
probe_success{environment=~"production|staging"}

Create separate panels for each environment group.

Q: Can I change the heartbeat bar size/color?

A: The heartbeat bars automatically:

Currently, these are not user-configurable, but may be added in future versions.

Q: How do I set up alerts with the status panel?

A: The panel is for visualization only. Set up Grafana alerts separately:

# Alert when service is down
probe_success == 0

# Alert on slow response
probe_duration_seconds > 5

The panel and alerts complement each other perfectly.

šŸ” Troubleshooting

Q: Data shows in Query Inspector but not in panel

A: Check:

  1. Instance labels: Ensure metrics have instance labels
  2. Custom names JSON: Verify JSON syntax is valid
  3. Max items setting: You might have hit the limit
  4. Time range: Ensure data exists in the selected range

Q: Tooltips on heartbeat bars donā€™t work

A: This usually indicates:

Q: Panel shows old data after updates

A: Try:

  1. Manual refresh: Click dashboard refresh button
  2. Clear browser cache: Force refresh (Ctrl+F5)
  3. Check data source cache: May need to be cleared
  4. Verify time range: Ensure it includes recent data

Q: Services appear and disappear randomly

A: This typically means:

šŸ› Known Issues & Limitations

Q: What are the current limitations?

A: Known limitations include:

  1. Maximum services: Performance degrades with 100+ services
  2. Heartbeat resolution: Limited to 50 data points
  3. Custom colors: Limited theme customization options
  4. Mobile optimization: Some display modes work better than others
  5. Historical data: Depends on Prometheus retention settings

Q: Are there any browser compatibility issues?

A: The plugin works best with:

Q: What about Grafana version compatibility?

A:

šŸ†˜ Getting Help

Q: Where can I report bugs or request features?

A:

Q: How can I contribute?

A: Contributions welcome!

Q: Is commercial support available?

A: This is an open-source project. Community support is available through:

Q: Can I modify the plugin for my needs?

A: Absolutely! The plugin is MIT licensed:

šŸ“š Additional Resources

Still need help? Create an issue on GitHub with: