tpu-top 0.1.3

TPU Monitoring Dashboard

TPU-TOP

A modern, terminal-based monitoring dashboard for Google Cloud TPUs, designed to give you real-time visibility into your machine's performance.

GitHub Repository | PyPI Project

Project Overview

tpu-top provides a visual, interactive TUI (Terminal User Interface) to monitor system and TPU resources. It is specifically tailored for high-performance computing environments like GKE (Google Kubernetes Engine) where deep learning models are trained on TPUs.

Key Features

• Responsive Layout: Automatically switches between 2x2 grid and 1x4 list for graphs based on terminal height.
• Priority-Based Rendering: Dynamically shrinks or drops panels (Processes panel shrinks first) to fit severe vertical constraints.
• Device Status Table: Detailed per-device breakdown showing duty cycle and memory usage. Compact 1-line layout for single-core TPUs (v6e) and multi-line for multi-core (v7).
• Process Monitor: Lists active processes, prioritized by TPU processes (sorted by TPU index) and then CPU processes (sorted by memory usage).
• Google Brand Styling: Color-coded graphs using Google's signature color palette (Blue, Red, Yellow, Green).
• Version Awareness: Displays tpu-top, libtpu, and tpu-info versions directly in the header alongside detected TPU generation.

Installation

From PyPI (Recommended)

pip install tpu-top

From Source

You can also install tpu-top directly from the source directory.

Prerequisites

Ensure you have Python 3.12+ and access to a Cloud TPU environment. The tool relies on tpu-info to communicate with the TPU driver.

Standard Source Install

Navigate to the project root directory and run:

pip install .

Developer Install

If you are making modifications and want them to reflect immediately:

pip install -e .

How to Use

Once installed, you can launch the dashboard from anywhere in your terminal:

tpu-top

Environment Variables

• TPU_TOP_MOCK=1: Force mock mode for testing on machines without physical TPUs.
• TPU_TOP_ITERATIONS=N: Run for exactly N refresh cycles and exit (useful for automated tests).

Running Tests

To validate changes, run the unit tests:

python -m unittest test_main.py

(Note: If testing inside a GKE container, ensure dependencies are installed in your target environment).