---
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