sshare

List Slurm share information

$ sshare

$ sshare --[parsable|parsable2|json|yaml]

$ sshare [[-o|--format]] [format_string]

$ sshare [[-u|--users]] [user_id_1,user_id_2,...]

sshare [OPTIONS...]

-a, --all
    Display all associations, including those with zero usage or shares.

-A account, --account=account
    Display only associations for the specified account(s).

--clusters=cluster_list
    Only display data for the specified Slurm cluster(s).

--federation
    Show information from all configured federated clusters.

-l, --long
    Display more detailed information in a wider format.

--noheader
    Do not print a header line in the output.

--nodelay
    Do not delay display (useful for interactive sessions where data might be updated rapidly).

-P, --parsable
    Output in a colon-separated parsable format, suitable for scripting.

-q, --quiet
    Do not display any error messages.

--raw
    Display raw data (e.g., microseconds for time) instead of scaled values.

-s, --sort
    Sort the output by specified field(s).

-U user, --user=user
    Display only associations for the specified user(s).

-u, --usage
    Include information on historical usage for accounts and users.

-V, --version
    Print version information and exit.

-v, --verbose
    Print detailed debug information, increasing verbosity level.

The sshare command is a Slurm workload manager utility designed to display information about fair-share trees and resource usage for various Slurm associations (accounts, users, clusters, QOS). It provides a crucial insight into how computing resources are allocated and consumed in a fair-share enabled Slurm cluster.

Administrators and users can leverage sshare to monitor current and historical resource utilization, debug fair-share related issues, and understand their effective share of cluster resources based on defined policies and past usage. It can present data in a raw, human-readable, or parsable format, making it versatile for scripting and reporting.

The sshare command relies on the Slurm database (slurmdbd) for historical usage data. If slurmdbd is not running or properly configured, fair-share information might be incomplete or unavailable.

Fair-share calculations are complex and can be influenced by numerous factors, including `GrpTRES`, `QOS`, `UsageFactor`, and `PreemptModes`. The displayed 'FairShare' value represents an idealized share, and actual resource access depends on job priority, cluster load, and scheduling policies.

Permissions are also critical; users typically only have access to view their own association data, while Slurm administrators can view all associations.

In Slurm, fair-share scheduling aims to distribute computing resources proportionally among users or groups over time, based on their allocated shares and historical resource consumption. An association's 'Effective Usage' is compared against its 'Normalized Shares' to determine its fair-share factor, which then influences job priority. sshare helps visualize these key metrics.

Common columns in sshare output include:
Account: The Slurm account name.
User: The user associated with the usage.
RawShares: The configured share for the association.
NormShares: Normalized shares after inheritance and adjustments.
RawUsage: Raw historical usage, often in 'billable TRES' units.
EffectvUsage: Effective historical usage, typically exponentially decaying.
FairShare: The calculated fair-share factor, reflecting an account/user's current priority based on their usage relative to their share. A value of 1.0 indicates usage is proportional to shares.

The sshare command is an integral part of the Slurm Workload Manager suite, which was first released in 2002. As Slurm evolved to support more sophisticated scheduling policies, especially fair-share scheduling, tools like sshare became essential. Its development paralleled the increasing complexity and adoption of fair-share algorithms in High-Performance Computing (HPC) environments, providing administrators and users with transparency into how resources are being shared and utilized according to defined policies. It has seen continuous updates to reflect new Slurm features and improve reporting capabilities.

sbatch(1), srun(1), squeue(1), sinfo(1), sacct(1), sstat(1), slurm.conf(5), slurmdbd(8)