spanner

README

🔧 spanner 🔧

spanner is a tool for easy job managment on HPC like referencing by name, logging, logging into nodes.

Works across Slurm and PBSPro.

Easy installation using Mamba

Install MambaForge on your cluster. In case you don't have internet access there, you can use mitten (https://github.com/unkaktus/mitten).

Then, install spanner itself:

mamba install -c https://mamba.unkaktus.art spanner

Installation using Go

1. Install MambaForge on your cluster. In case you don't have internet access there, you can use mitten (https://github.com/unkaktus/mitten).

2. Install Go

mamba install go

1. Install spanner:

go install github.com/unkaktus/spanner/cmd/spanner@latest

1. Add $HOME/go/bin into your $PATH into your .bashrc:

export PATH="$HOME/go/bin:$PATH"

Manual building

1. Install Go (https://go.dev)

2. Build spanner for Linux:

git clone https://github.com/unkaktus/spanner
cd spanner/cmd/spanner
env GOOS=linux GOARCH=amd64 go build

1. scp the spanner binary to your favorite supercomp and add it to your $PATH.

Example uses

List jobs

$ spanner list
╭───────────────────────┬─────────┬───────┬─────────────────────────┬───────╮
│         NAME          │  STATE  │ QUEUE │          TIME           │ NODES │
├───────────────────────┼─────────┼───────┼─────────────────────────┼───────┤
│ Compare_Apples        │ R [0]   │ small │ [8%] 2h0m41s/24h0m0s    │     8 │
│ Compare_Oranges       │ Q [0]   │ small │ [0%] 0s/20h0m0s         │     2 │
│ Compare_Bananas       │ F [9]   │ small │ [0%] 0s/20h0m0s         │    16 │
╰───────────────────────┴─────────┴───────┴─────────────────────────┴───────╯

Logs

Open full logs in $EDITOR (defauts to vim):

$ spanner logs Compare_Apples

Follow the log tail of a job:

$ spanner logs -f Compare_Apples

Shell

To connect to the shell on the job nodes, you first need to start your job binary via spanner tent:

[mpirun -n 16] spanner tent ./exe/binary

Then, to connect to the shell of the node 1 of running job Compare_Apples:

$ spanner shell Compare_Apples 1
node123$

Stopping jobs

Cancel job Compare_Apples:

$ spanner cancel Compare_Apples

Portable jobs

Start a portable job using compare_apples.begin file and configuration file data.csv for the run:

$ spanner begin -f compare_apples.begin data.csv

Remote commands

Do all above without logging manually to the cluster:

$ spanner on supercomp list

$ spanner on supercomp shell compare_apples

This requires to have spanner to be installed and added to the PATH there.

Port forwarding

Forward a port to the node of a job:

$ spanner port-forward -p 11111 -m supercomp compare_apples

Documentation

Index

• func Begin(b BatchSystem, beginFilename, configFilename string, dryRun bool) error
• func ListJobs(bs BatchSystem, request ListRequest) error
• func Logs(b BatchSystem, jobName string, outputType string) error
• func Logtail(b BatchSystem, jobName, outputType string, nLines int) error
• func On(machine string, cmdline []string) error
• func PortForward(machine, jobName string, port, nodeID int) error
• func Shell(hostname string) error
• func Tent(bs BatchSystem, cmdline []string, mergeOutput, noCommand bool) (err error)
• type BatchSystem
• type Job
  • func LatestJob(bs BatchSystem) (*Job, error)
• type ListRequest

Functions

func Begin

func Begin(b BatchSystem, beginFilename, configFilename string, dryRun bool) error

func ListJobs

func ListJobs(bs BatchSystem, request ListRequest) error

func Logs

func Logs(b BatchSystem, jobName string, outputType string) error

func Logtail

func Logtail(b BatchSystem, jobName, outputType string, nLines int) error

func On

func On(machine string, cmdline []string) error

func PortForward

func PortForward(machine, jobName string, port, nodeID int) error

func Shell

func Shell(hostname string) error

func Tent

func Tent(bs BatchSystem, cmdline []string, mergeOutput, noCommand bool) (err error)

Types

type BatchSystem

type BatchSystem interface {
	ListJobs(all bool) ([]Job, error)
	Shell(jobName string, nodeID int) error
	Cancel(jobName string) error
	TentVariables() tent.Variables
	JobData(batchsystem.Job) (string, error)
	Submit(jobData string) error
}

type Job

type Job struct {
	Name              string
	ID                string
	Queue             string
	State             string
	ExitCode          int
	CreationTime      time.Time
	Nodes             []string
	NodeNumber        int
	CPUNumber         int
	CPUTime           time.Duration
	Walltime          time.Duration
	RequestedWalltime time.Duration
	OutputFile        string
	ErrorFile         string
	WorkingDirectory  string
}

func LatestJob

func LatestJob(bs BatchSystem) (*Job, error)

type ListRequest

type ListRequest struct {
	All             bool
	Full            bool
	MachineReadable bool
	State           string
}