ts-topy

A monitoring tool for Teraslice distributed computing clusters, built on Python with Textual.

Overview

This is a rewrite of teraslice-top in Python, designed to provide better scalability and UX for monitoring Teraslice clusters with many jobs.

Installation

# Install using uv (recommended for CLI tools)
uv tool install ts-topy

# Or from PyPI
pip install ts-topy

# Or using pipx
pipx install ts-topy

Usage

# Select from or add cluster to ~/.teraslice/aliases.yaml
ts-topy

# Specify custom URL
ts-topy https://teraslice.example.com:8000

# Set refresh interval (default: 5s)
ts-topy http://localhost:5678 --interval 5
ts-topy http://localhost:5678 -i 5

# Set request timeout (default: 10s)
ts-topy http://localhost:5678 --request-timeout 30

# All options
ts-topy https://teraslice.example.com:8000 -i 5 --request-timeout 30

Features

• Real-time monitoring of Teraslice cluster state
• Three-pane display showing:
  • Execution Contexts
  • Controllers
  • Jobs
• Global search/filter across all data
• Auto-refresh with configurable intervals
• Terminal UI built with Textual

Technology Stack

• Python 3.10+
• uv - Python project and package manager
• Textual - Terminal UI framework
• httpx - Async HTTP client
• Pydantic - Data validation and models
• Typer - CLI interface

Development

# Install dependencies
uv sync

# Run the application
uv run ts-topy

Mock Server

For development and testing without a real Teraslice cluster, you can use the built-in mock server:

# Install mock server dependencies
uv sync --extra mock

# Start the mock server
uv run ts-topy mock-server

# In another terminal, monitor the mock server
uv run ts-topy http://localhost:5678

See MOCK_SERVER.md for detailed documentation on the mock server, including all available endpoints, options, and mock data characteristics.

Releasing

This project uses GitHub Actions for automated releases to PyPI. To create a new release:

1. Bump the version using the bump script:

   # For a patch release (bug fixes)
   uv run scripts/bump_version.py patch
   
   # For a minor release (new features)
   uv run scripts/bump_version.py minor
   
   # For a major release (breaking changes)
   uv run scripts/bump_version.py major
   
   # Or set a specific version
   uv run scripts/bump_version.py --set 1.2.3
   

2. Review and commit the changes:

   git diff  # Review the version change
   git add pyproject.toml
   git commit -m "Bump version to X.Y.Z"
   

3. Create and push a git tag:

   git tag vX.Y.Z
   git push origin main --tags
   

4. GitHub Actions will automatically:

   • Build the package
   • Create a GitHub release
   • Publish to PyPI

5. Verify the release:

   • Check the GitHub releases page
   • Verify on PyPI

Manual Release (if needed)

If you need to build and publish manually:

# Build the package
uv build

# Publish to PyPI (requires PyPI credentials)
uv publish

License

MIT