PulseBar - RDS Monitor

A macOS menu bar app for monitoring AWS RDS instances with real-time health metrics and alerts.

Features

📊 At-a-glance Monitoring: CPU, connections, sessions, and storage for every RDS instance, right in the menu bar
📈 Detail Dashboard: Click any database for a popup with six time-series charts (CPU, Memory, Storage) over the last 1 day / 7 days / 30 days — sized to fit the content, no scrolling
🔍 Performance Insights: Top SQL queries, users, and hosts by average active sessions (when PI is enabled)
🔎 Query Drill-down: Click any Top Query to open a dedicated window with its load over time, the individual SQL statements behind the digest (expand any to its full SQL), and the users/hosts that ran it — the same flow as the RDS console's Top SQL view
🧬 Replica Awareness: Read replicas are nested under their primary, with replica lag
🔗 Open in AWS Console: One-click deep link to any instance in the RDS console
⚡ Auto-refresh: Menu-bar metrics update automatically (configurable: 1–60 min)
🔔 Smart Alerts: macOS notifications when metrics exceed a configurable threshold (default 50%), plus an always-visible in-menu alert banner
⚙️ Settings: Adjust alert threshold and refresh interval from the menu
🎨 Color-coded Status: Green (<50%), Yellow (50-75%), Red (>75%)
🔐 AWS Integration: Uses your existing ~/.aws/credentials and ~/.aws/config
🌍 Multi-region/Profile: Switch between AWS profiles and regions easily

Metrics Tracked

In the menu bar, for each RDS instance:

Metric	Source	Description
CPU Utilization	CloudWatch `CPUUtilization`	Current CPU usage percentage
Connections	`DatabaseConnections / max_connections × 100`	Percentage of connection pool used
Sessions	CloudWatch `DBLoad` (falls back to `DatabaseConnections`)	Average active sessions
Storage	`(AllocatedStorage - FreeStorageSpace) / AllocatedStorage`	Percentage of disk space used

In the detail dashboard (click a database), six charts grouped by type:

Group	Charts
CPU	`CPUUtilization`, `DBLoad` (avg active sessions)
Memory	`FreeableMemory`, `SwapUsage`
Storage	`FreeStorageSpace`, `ReadIOPS` + `WriteIOPS`

Requirements

macOS 13.0 or later
Swift 5.9+
AWS credentials configured at ~/.aws/credentials
IAM permissions:
- rds:DescribeDBInstances
- cloudwatch:GetMetricData
- pi:DescribeDimensionKeys (optional — for the Top Queries/Users/Hosts panels)
- pi:GetResourceMetrics (optional — for the query drill-down load chart)
- pi:GetDimensionKeyDetails (optional — to expand a statement to its full SQL)

Installation

Option 1: Download Pre-built Release

Go to the Releases page
Download the latest PulseBar-vX.X.X-macOS.zip

Unzip and move to Applications:

unzip PulseBar-vX.X.X-macOS.zip
mv PulseBar.app /Applications/

First launch (app is unsigned, so macOS will block it):
- Right-click PulseBar.app → Open → Click Open in the dialog
- Or run: xattr -cr /Applications/PulseBar.app

Option 2: Build from Source

# Clone the repository
git clone <repository-url>
cd PulseBar

# Build and install to /Applications
make install

Option 3: Build and Run Locally

# Run in debug mode
make run

# Or build release binary
make build

Note: When running via make run (without app bundle), macOS notifications are disabled. Use make install for full functionality.

AWS Credentials Setup

Ensure you have AWS credentials configured:

# ~/.aws/credentials
[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

[production]
aws_access_key_id = PROD_ACCESS_KEY
aws_secret_access_key = PROD_SECRET_KEY

# ~/.aws/config
[default]
region = us-west-2

[profile production]
region = us-east-1

Required IAM Permissions

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "rds:DescribeDBInstances",
      "cloudwatch:GetMetricData",
      "pi:DescribeDimensionKeys",
      "pi:GetResourceMetrics",
      "pi:GetDimensionKeyDetails"
    ],
    "Resource": "*"
  }]
}

Only rds:DescribeDBInstances and cloudwatch:GetMetricData are strictly required. The pi:* actions power the Performance Insights panels and the query drill-down (pi:DescribeDimensionKeys for the Top lists and statement breakdown, pi:GetResourceMetrics for the per-query load chart, pi:GetDimensionKeyDetails for full SQL text) — PulseBar degrades gracefully when any are missing.

Usage

Launch PulseBar from Applications or run make run
Click the chart icon in your menu bar
Select your AWS profile and region
View at-a-glance metrics for all RDS instances
Hover an instance and choose 📊 Open Details… to open the full dashboard with charts and Performance Insights
In the dashboard, click any Top Query to drill into its load over time, individual SQL statements, and the users/hosts that ran it

Menu Options

Profile Selector: Switch between AWS profiles
Region Selector: Change AWS region (us-east-1, us-west-2, eu-west-1, etc.)
Refresh Now: Manual refresh (⌘R)
Instance List: Click any instance for details
Quit: Exit the application (⌘Q)

Understanding the Display

🟢 my-database-prod          # Green = all metrics healthy (<50%)
   📊 Open Details…          # Opens the charts + Performance Insights dashboard
   postgres - db.r5.large    # Engine and instance class
   🟢 CPU: 12.5%             # CPU utilization
   🟢 Connections: 23.1%     # Connection pool usage
   Sessions: 1.42 avg active # Average active sessions (DBLoad)
   🔴 Storage: 78.2%         # Storage used (red = >75%)
   Activity: 14 connections  # Raw connection count

Color Coding:

🟢 Green: < 50% (healthy)
🟡 Yellow: 50-75% (warning)
🔴 Red: > 75% (critical)
⚪ Gray: N/A (data unavailable)

Status Messages:

⏳ Loading... - Fetching data from AWS
⚠️ AWS credentials not found - Missing ~/.aws/credentials file
🔐 Invalid credentials - Credentials expired or invalid
📭 No RDS instances found - No databases in the selected region

Alert Behavior

Notifications are sent when any metric exceeds the configured threshold (default 50%, set in ⚙️ Settings):

Alerts are deduplicated (won't spam for the same condition)
New notifications sent if:
- Different metrics breach thresholds
- Instance recovers and breaches again
- 15+ minutes since last alert for same condition

Example notification:

⚠️ RDS Alert: production-db
CPU: 72%
Connections: 61%

Note: System notifications are most reliable from an installed, signed app bundle (make install). For local builds, PulseBar falls back to a legacy notification path and always shows an alert banner at the top of the menu, so breaching instances are visible regardless of notification permissions.

Architecture

Timer (configurable interval)
   ↓
Load AWS Profile/Credentials
   ↓
DescribeDBInstances (RDS API)
   ↓
GetMetricData (CloudWatch API) — latest scalar values
   ↓
Metric Calculations
   ↓
Menu UI Update + Alert Engine (notifications + in-menu banner)

Click "Open Details…"
   ↓
GetMetricData (1d/7d/30d range)  +  DescribeDimensionKeys (Performance Insights)
   ↓
SwiftUI + Charts dashboard (NSHostingView in a floating NSWindow, sized to fit)

Click a Top Query
   ↓
GetResourceMetrics (load over time, filtered to the digest)
   +  DescribeDimensionKeys (db.sql statements behind the digest, plus users/hosts)
   +  GetDimensionKeyDetails (full SQL text, on demand)
   ↓
Query drill-down window (its own floating NSWindow)

Project Structure

PulseBar/
├── Sources/
│   ├── main.swift                          # App entry point
│   ├── AppDelegate.swift                   # Menu bar UI & coordination
│   ├── AWSCredentialsReader.swift          # Reads ~/.aws files
│   ├── RDSMonitoringService.swift          # AWS SDK integration (RDS, CloudWatch, PI)
│   ├── AlertManager.swift                  # Notification logic
│   ├── Settings.swift                      # User preferences (threshold, interval)
│   ├── DatabaseDetailWindowController.swift # Detail window + view model (auto-sizes to fit)
│   ├── MetricsDashboardView.swift          # SwiftUI + Charts dashboard
│   ├── QueryDetailWindowController.swift   # Per-query drill-down window + view model
│   ├── QueryDetailView.swift               # SwiftUI view for the query drill-down
│   └── Models.swift                        # Data structures
├── Assets/
│   └── screenshot.png                      # App screenshot
├── Icons/
│   └── *.png                               # App icons (16-1024px)
├── .github/
│   ├── ISSUE_TEMPLATE/                      # Bug report & feature request templates
│   ├── PULL_REQUEST_TEMPLATE.md            # PR template
│   └── workflows/
│       ├── pr-validation.yml               # PR build checks
│       └── release.yml                     # Auto-build on release
├── Package.swift                     # Swift Package Manager config
├── Info.plist                        # App metadata
├── Makefile                          # Build commands
├── README.md                         # This file
├── CONTRIBUTING.md                   # Contribution guidelines
├── CODE_OF_CONDUCT.md                # Community standards
├── SECURITY.md                       # Security policy
├── LICENSE                           # MIT License
└── agents.md                         # Developer/AI agent guide

Development

Build Commands

make run      # Debug build and run
make build    # Release build (.build/release/PulseBar)
make clean    # Clean build artifacts
make install  # Install to /Applications
make help     # Show all commands

Dependencies

aws-sdk-swift v0.40.0+ (AWSRDS, AWSCloudWatch, AWSPI)
SwiftUI and Charts (system frameworks, macOS 13+) for the detail dashboard

Dependencies are managed via Swift Package Manager and will be automatically resolved on build.

CI/CD

This project uses GitHub Actions for:

PR Validation: Builds and validates code on every pull request
Release Build: Automatically builds and attaches binaries when a GitHub release is published

See .github/workflows/ for details.

Limitations

Basic max_connections estimation (not querying parameter groups)
Performance Insights panels and the query drill-down require PI to be enabled on the instance and the pi:* permissions listed above
Performance Insights retains data for the past 7 days, so the query drill-down's 30-day range is clamped to that window
Single account only (no multi-account aggregation)
Read-only monitoring (cannot modify RDS instances)
System notifications are most reliable from a signed, installed app bundle (an in-menu alert banner always works as a fallback)

Troubleshooting

"App is damaged" or "Can't be opened"

The app is unsigned, so macOS Gatekeeper blocks it. Fix with one of these:

Option 1: Right-click the app → Open → Click Open in the dialog

Option 2: Run in terminal:

xattr -cr /Applications/PulseBar.app

"AWS credentials not found"

The app can't find ~/.aws/credentials. Set up AWS credentials:

# Option 1: Use AWS CLI
aws configure

# Option 2: Create manually
mkdir -p ~/.aws
cat > ~/.aws/credentials << EOF
[default]
aws_access_key_id = YOUR_KEY
aws_secret_access_key = YOUR_SECRET
EOF

"Invalid credentials" / "Profile not found"

Verify the selected profile exists in ~/.aws/credentials
If using temporary credentials (SSO, assumed role), refresh them
Check credentials haven't expired

"Permission denied"

Verify your IAM user/role has these permissions:

rds:DescribeDBInstances
cloudwatch:GetMetricData
pi:DescribeDimensionKeys, pi:GetResourceMetrics, pi:GetDimensionKeyDetails (only for Performance Insights panels and the query drill-down)

Storage shows "N/A"

CloudWatch may not have recent data. The app queries a 1-hour window; if no data exists, it shows N/A.

Sessions or Performance Insights show "No data"

DBLoad and the Top Queries/Users/Hosts panels require Performance Insights to be enabled on the instance. When it's off, the Sessions row falls back to the raw connection count and the dashboard panels show a notice.

Notifications not appearing

Ensure you're running the installed app (/Applications/PulseBar.app), not swift run
Check System Settings → Notifications → PulseBar
Ensure notifications are enabled
Restart the app if needed

Even when system notifications are blocked, PulseBar shows an alert banner at the top of the menu listing any instances that are breaching thresholds — so you never miss an alert.

High CPU/memory usage during first run

The first build downloads and compiles AWS SDK dependencies (~200 MB). Subsequent runs will be fast.

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please read our Contributing Guidelines before getting started.

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

For architecture and technical details, see agents.md.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github		.github
Assets		Assets
Icons		Icons
Sources		Sources
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Info.plist		Info.plist
LICENSE		LICENSE
Makefile		Makefile
Package.resolved		Package.resolved
Package.swift		Package.swift
README.md		README.md
SECURITY.md		SECURITY.md
agents.md		agents.md

Folders and files

Latest commit

History

Repository files navigation

PulseBar - RDS Monitor

Features

Metrics Tracked

Requirements

Installation

Option 1: Download Pre-built Release

Option 2: Build from Source

Option 3: Build and Run Locally

AWS Credentials Setup

Required IAM Permissions

Usage

Menu Options

Understanding the Display

Alert Behavior

Architecture

Project Structure

Development

Build Commands

Dependencies

CI/CD

Limitations

Troubleshooting

"App is damaged" or "Can't be opened"

"AWS credentials not found"

"Invalid credentials" / "Profile not found"

"Permission denied"

Storage shows "N/A"

Sessions or Performance Insights show "No data"

Notifications not appearing

High CPU/memory usage during first run

License

Contributing

Roadmap

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages