A terminal-based monitoring tool for Amazon FSx file systems. Displays storage utilization, performance metrics, and cost information in real-time with smooth gradient progress bars.
- Real-time monitoring of all FSx file system types (Lustre, Windows, ONTAP, OpenZFS)
- Storage utilization with smooth gradient progress bars (green → yellow → orange → red)
- CloudWatch metrics (throughput, IOPS, CPU utilization)
- Estimated monthly costs with itemized breakdowns (storage, throughput, IOPS, capacity pool)
- Pricing coverage across 36 AWS regions for all FSx types
- Detail views with volume-level metrics (ONTAP/OpenZFS) and MDS CPU breakdown (Lustre)
- S3 access point visibility on ONTAP/OpenZFS volumes with drill-down to alias / VPC / lifecycle
- Filtering by type and name
- Sorting by various fields (name, capacity, utilization, cost, creation time)
- Keyboard navigation with vim-style controls
- Pagination for large datasets
- Python 3.10+
- AWS credentials configured (via environment, profile, or IAM role)
- IAM permissions:
fsx:DescribeFileSystemsfsx:DescribeVolumesfsx:DescribeS3AccessPointAttachments(optional; enables S3 access point column/drill-down for ONTAP/OpenZFS volumes)cloudwatch:GetMetricDatacloudwatch:ListMetricsec2:DescribeSubnets(optional; resolves subnet IDs to AZ names in the detail view)
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install fsx-viewer
uv tool install git+https://github.com/aws-samples/sample-fsx-viewer.git# Install uv (if not already installed)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Install fsx-viewer
uv tool install git+https://github.com/aws-samples/sample-fsx-viewer.gituv tool uninstall fsx-viewer# Clone the repository
git clone https://github.com/aws-samples/sample-fsx-viewer.git
cd sample-fsx-viewer
# Install dependencies (includes dev dependencies like pytest, hypothesis)
uv sync
# Run from source
uv run fsx-viewer --region us-east-1# Run the viewer
fsx-viewer --region us-east-1
# View a specific file system in detail
fsx-viewer --region us-east-1 --file-system-id fs-0123456789abcdef0-r, --region REGION AWS region (required)
-p, --profile PROFILE AWS profile name
-t, --type TYPE Filter summary view by type: LUSTRE, WINDOWS, ONTAP, OPENZFS
-f, --file-system-id ID Show detail view for specific file system
-n, --name-filter FILTER Filter by name (substring match)
-s, --sort SORT Sort field and order (e.g., 'capacity=dsc')
--refresh-interval SECS File system refresh interval (default: 300)
--metric-interval SECS Metrics refresh interval (default: 60)
--disable-pricing Hide cost information
--style COLORS Progress bar colors (good,ok,bad)
-v, --version Show version
Note: --type and --file-system-id are mutually exclusive. Use --type to filter the summary view, or --file-system-id to go directly to a detail view.
Summary view:
name=asc/name=dsc- Sort by nametype=asc/type=dsc- Sort by file system typecapacity=asc/capacity=dsc- Sort by storage capacityutilization=asc/utilization=dsc- Sort by utilization percentagecost=asc/cost=dsc- Sort by monthly costcreation=asc/creation=dsc- Sort by creation time (default: dsc)
Detail view (ONTAP/OpenZFS volumes):
name=asc/name=dsc- Sort by volume namecapacity=asc/capacity=dsc- Sort by volume capacityutilization=asc/utilization=dsc- Sort by volume utilizationiops=asc/iops=dsc- Sort by total IOPSthroughput=asc/throughput=dsc- Sort by total throughput
# View all file systems in eu-west-1
fsx-viewer --region eu-west-1
# Filter to only ONTAP file systems
fsx-viewer --region us-east-1 --type ONTAP
# View details for a specific file system
fsx-viewer --region us-east-1 --file-system-id fs-0123456789abcdef0
# Sort by capacity descending
fsx-viewer --region us-east-1 --sort capacity=dsc
# Use a specific AWS profile
fsx-viewer --region us-east-1 --profile myprofileDisplays all file systems with:
- File system ID and name
- Type (LUSTRE, WINDOWS, ONTAP, OPENZFS)
- Storage capacity with utilization bar
- CPU utilization (where available)
- Throughput (MiB/s)
- IOPS
- Estimated monthly cost
Press Enter on a file system to view its details.
ONTAP Detail View:
- File system overview (capacity, throughput, IOPS, CPU)
- Itemized monthly cost breakdown (SSD storage, capacity pool, throughput, IOPS)
- Volume table with per-volume metrics from CloudWatch:
- StorageUsed / StorageCapacity
- Read/Write IOPS
- Read/Write throughput (MiB/s)
- S3 access point count (
-,1,2, …); pressEnteron a selected volume to drill into a panel showing each access point's name, alias, lifecycle, and VPC scope
OpenZFS Detail View:
- File system overview
- Volume table with:
- Used capacity / Quota (or file system capacity if no quota)
- Read/Write IOPS
- Read/Write throughput (MiB/s)
- S3 access point count + drill-down (same as ONTAP)
Lustre Detail View:
- File system overview
- MDS (Metadata Server) table with CPU utilization per server
Windows Detail View:
- File system metrics table (capacity, CPU, throughput, IOPS)
| Key | Action |
|---|---|
j or ↓ |
Move selection down |
k or ↑ |
Move selection up |
Enter |
View details for selected file system |
c |
SSH to selected FSx for ONTAP file system via EC2 Instance Connect |
h or ← |
Previous page |
l or → |
Next page |
q or Esc |
Quit |
| Key | Action |
|---|---|
j or ↓ |
Select next volume (ONTAP/OpenZFS) |
k or ↑ |
Select previous volume (ONTAP/OpenZFS) |
Enter |
Open volume details (ONTAP/OpenZFS) |
h or ← |
Previous page (volumes / MDS servers / APs) |
l or → |
Next page |
Esc |
Return to volume list (when viewing volume details); otherwise quit |
q |
Return to summary view (or exit volume details) |
Create ~/.fsx-viewer for default settings:
region=us-east-1
profile=default
refresh-interval=300
metric-interval=60
sort=capacity=dsc
disable-pricing=false
style=green,yellow,red
Configuration precedence: CLI args > environment variables > config file > defaults
The tool is optimized for minimal API calls:
- Batched CloudWatch queries (single API call for all file systems/volumes)
- Shared boto3 session across clients
- Cached MDS server discovery for Lustre
- Progressive UI updates (shows data as it arrives)
This project was inspired by eks-node-viewer, a terminal-based tool for visualizing Kubernetes node usage. The architectural patterns (controller/model/view separation, progress bar rendering, keyboard navigation) were adapted for FSx file system monitoring.
Apache 2.0
See ATTRIBUTION.md for third-party software licenses.