diff --git a/PBS/Tech/Projects/pbs-memory-dashboard.md b/PBS/Tech/Projects/pbs-memory-dashboard.md new file mode 100644 index 0000000..62d3902 --- /dev/null +++ b/PBS/Tech/Projects/pbs-memory-dashboard.md @@ -0,0 +1,123 @@ +--- +project: pbs-memory-dashboard +type: tech-setup +status: active +tags: + - pbs + - docker + - streamlit + - flask + - automation + - production +created: 2026-04-05 +updated: 2026-04-05 +path: PBS/Tech/Projects/ +--- + + +# PBS Memory Dashboard - Streamlit Spec + +## Overview + +Add a memory monitoring page to the existing PBS Streamlit dashboard +(running inside pbs-api container). The page parses the host memory log +file mounted into the container and renders interactive charts showing +per-container memory usage over time. + +--- + +## Data Source + +**Log file path inside container:** +/var/log/pbs-monitoring/container-memory.log + +**Log format (one line per 5-minute interval):** +2026-04-05 18:20:01 UTC | n8n:331.8MiB / 3.824GiB gitea:90.55MiB / 3.824GiB +pbs-api:63.91MiB / 512MiB wordpress:501.6MiB / 1.953GiB traefik:43.43MiB / +3.824GiB portainer:14.03MiB / 2GiB redis:12.4MiB / 640MiB +wordpress_phpmyadmin:61.03MiB / 3.824GiB wordpress_mysql:419.9MiB / 768MiB +wpcron:8.371MiB / 3.824GiB uptime-kuma:100.7MiB / 3.824GiB + +**Parsing notes:** +- Split on " | " to get timestamp and container data +- Timestamp format: "%Y-%m-%d %H:%M:%S UTC" +- Each container entry format: name:usedMiB / limitGiB (or MiB) +- Convert all memory values to MiB for consistency: + - If value ends in MiB: use as-is + - If value ends in GiB: multiply by 1024 +- Calculate usage percentage: (used / limit) * 100 + +**Known containers to parse:** +n8n, gitea, pbs-api, wordpress, traefik, portainer, redis, +wordpress_phpmyadmin, wordpress_mysql, wpcron, uptime-kuma + +--- + +## Page Layout + +### Section 1: Summary Cards (top of page) +- One metric card per container showing: + - Current memory usage (MiB) + - Memory limit (MiB) + - Usage percentage + - Color code: green 80% +- Special attention containers (tighter limits): + - wordpress: limit 1.953GiB (2000MiB) + - wordpress_mysql: limit 768MiB + - redis: limit 640MiB + - pbs-api: limit 512MiB + +### Section 2: Time Series Chart +- Multi-line Plotly chart showing memory usage % over time +- X axis: timestamp +- Y axis: memory usage percentage (0-100%) +- One line per container, with legend +- Add horizontal reference lines at 50% (yellow) and 80% (red) +- Default time range: last 24 hours +- Add a time range selector: 6h, 24h, 7d, All + +### Section 3: Per-Container Drill Down +- Selectbox to choose a single container +- Show used MiB over time (not percentage) for that container +- Show a horizontal line at the memory limit for that container + +### Section 4: Raw Data Table +- Collapsible expander section +- Show the parsed DataFrame with columns: + timestamp, container, used_mib, limit_mib, usage_pct +- Allow sorting by column + +--- + +## Sidebar Controls +- Time range selector (6h, 24h, 7d, All) — drives Sections 2 and 3 +- Multi-select for containers to show/hide in the time series chart +- Auto-refresh toggle (refresh every 5 minutes using st.rerun) + +--- + +## Dependencies to Add (if not already present) +- plotly +- pandas + +Both should be installed in the existing UV environment. + +--- + +## File Location +Add as a new page in the existing Streamlit multipage structure. +Suggested filename: pages/memory_dashboard.py + +--- + +## Notes for Agent +- The log file is read-only mounted at the path above +- Parse the entire file fresh on each page load (file is not large) +- Use st.cache_data with a short TTL (300 seconds) to avoid re-parsing on +every widget interaction +- Handle missing or malformed log lines gracefully with try/except +- The auto-refresh should only trigger if the toggle is enabled in the +sidebar + + +...sent from Jenny & Travis \ No newline at end of file