Conversation
…zation This commit introduces a pre-built Grafana dashboard that visualizes all Prometheus metrics exposed by the /metrics endpoint. The dashboard provides real-time monitoring and historical visualization of machine status, health, connectivity, and usage patterns. Dashboard Features: - System Status: Server uptime, user/fob counts with trends, machine connectivity (5min check-in), lockout status overview - Machine Usage: Real-time relay states, RFID presence, oops button monitoring, relay state timeline, time-since-checkin tracking - Machine Health: WiFi signal strength (% and dB), ESP32 temperature, controller uptime with log scale - Usage Analytics: Current session durations, 24h usage distribution, known user presence indicators - Machine Details: Per-machine drill-down with selectable variable Key Design Decisions: - Logarithmic scales on uptime and check-in graphs to handle machines with vastly different value ranges (some run for weeks, others reboot frequently) - Gray background for normal machine states, red for problems (oops button) following "quiet good news, loud bad news" principle - Time-since-checkin visualization with color-coded thresholds (green <60s, yellow 1-5min, orange 5-10min, red >10min) for connectivity health monitoring - 24-hour default view with 5-second auto-refresh - Removed current draw panels as feature not currently implemented Files Added: - docs/source/grafana-dashboard.json: Complete dashboard definition with 29 panels organized into 5 sections - docs/source/grafana-dashboard.md: Comprehensive documentation covering all panels, metrics, design decisions, modification guides, and troubleshooting Files Modified: - docs/source/admin.rst: Added Grafana Dashboard section with features overview, import instructions, and embedded JSON using literalinclude directive for automatic doc updates Dashboard Configuration: - UID: dm-mac-dashboard - Default time range: 24 hours (now-24h to now) - Refresh rate: 5 seconds - Description: GitHub URL for source reference - Template variables: $machine selector for detailed views The dashboard JSON is embedded in the Sphinx documentation so it stays in sync with the actual file, and includes complete inline documentation for future development work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
…oard
This commit adds a display_name label to all machine-based Prometheus metrics,
in addition to the existing machine_name label. The display_name uses the
machine's alias if configured, otherwise falls back to the machine name. This
provides human-friendly names in dashboards and queries while preserving the
technical machine_name for filtering and querying.
Changes to Prometheus Metrics (src/dm_mac/views/prometheus.py):
- Added display_name label to all 19 machine-specific metrics
- Both machine_name and display_name labels are now present on all metrics
- Used m.display_name property which returns alias if set, otherwise name
- Labels are alphabetically sorted: display_name, machine_name
Test Updates (tests/views/test_prometheus.py):
- Updated all expected metric outputs to include both labels
- Metal Mill machine shows display_name="Metal Mill" (uses alias)
- Other machines show display_name equal to machine_name (no alias)
- LED metrics updated to include display_name in addition to led_attribute
Documentation Updates (docs/source/admin.rst):
- Updated all metric examples to show both labels
- Examples now reflect the display_name label in output
- Metal Mill consistently shows display_name="Metal Mill"
Grafana Dashboard Updates (docs/source/grafana-dashboard.json):
- Changed all legendFormat from {{machine_name}} to {{display_name}}
- Updated template variable query to use display_name
- Dashboard now shows human-friendly names (aliases) in legends and labels
- Machine selector dropdown uses display_name for better UX
Dashboard Documentation (docs/source/grafana-dashboard.md):
- Updated metrics table to show both labels for machine metrics
- Updated template variable description
- Clarified that display_name uses alias if present
Benefits:
- Dashboards show human-friendly "Metal Mill" instead of "metal-mill"
- Preserves machine_name for programmatic filtering/querying
- Backward compatible - both labels available for PromQL queries
- Consistent with existing display_name property from PR #69
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a comprehensive Grafana dashboard for visualizing system metrics and enhances Prometheus metrics with human-friendly display names.
Changes
1. Grafana Dashboard (
docs/source/grafana-dashboard.json)Dashboard Features:
2. Prometheus Metrics Enhancement (
src/dm_mac/views/prometheus.py)display_namelabel to all 19 machine-based metricsmachine_namelabel for backward compatibilitydisplay_nameuses machine alias if configured, otherwise falls back to machine name3. Documentation
docs/source/admin.rst: Added Grafana Dashboard section with features overview, import instructions, and embedded JSONdocs/source/grafana-dashboard.md: Comprehensive 400+ line reference document covering:4. Test Updates (
tests/views/test_prometheus.py)display_nameDashboard Design Highlights
Logarithmic Scales
Used on Machine Controller Uptime and Time Since Last Check-In to handle machines with vastly different value ranges (some run for weeks, others reboot frequently). Makes proportional changes visible across all machines.
Color Coding
Time-Since-Checkin Graph
New visualization showing seconds since last machine check-in with:
Benefits
✅ Real-time visual monitoring of all machine states
✅ Historical trend analysis for capacity planning
✅ Quick identification of connectivity and health issues
✅ Human-friendly names (aliases) in dashboard legends
✅ Backward compatible - both labels available for filtering/querying
✅ Comprehensive documentation for future development
Testing
Screenshots
Dashboard includes visualization of:
Related
Builds on PR #69 which added the
display_nameproperty to the Machine model.