Understanding The bank-info Command

Overview

The bank-info command provides a comprehensive view of fairshare and resource allocation information for banks and users within the flux-accounting database. It displays normalized shares, usage statistics, and fairshare values in a hierarchical tree structure that reflects the organization of banks and their associations.

This command serves multiple purposes:

  • Quick status checks: View current resource allocation and usage at a glance

  • Hierarchy visualization: Understand the relationship between banks and users

  • Resource analysis: Compare allocated shares versus actual usage

Unlike flux-account-view-bank(1) and flux-account-view-user(1) which display detailed database attributes, bank-info focuses specifically on share distribution and usage metrics that may affect job scheduling priorities.

Command Execution

When called without options, bank-info displays information for the current association. To view the entire database hierarchy, pass the -t flag along with the name of the root bank:

$ flux account bank-info -t root
Name                     Shares  Norm Shares   Norm Usage   Level FS
root                          1     1.000000     1.000000        inf
A                             1     0.333333     0.000000         --
  user1                       1     0.166667     0.000000      0.500
  user2                       1     0.166667     0.000000      0.500
B                             1     0.333333     0.000000         --
  user3                       1     0.333333     0.000000      0.500
C                             1     0.333333     0.000000         --
  user1                       1     0.333333     0.000000      0.500

Understanding the Output

The output columns provide different perspectives on resource allocation and usage:

In the example above, the normalized shares calculation proceeds as follows:

  • root has a normalized shares value of 1.0 (by definition, this represents a 100% share of all resources)

  • Banks A, B, and C each have 1 share out of 3 total sibling shares, so each gets \(1/3 * 1.0 = 0.333333\) normalized shares

  • user1 in bank A has 1 share out of 2 total shares in that bank, so they get \(1/2 * 0.333333 = 0.166667\) normalized shares

  • user3 in bank B is the only user, so they get \(1/1 * 0.333333 = 0.33333\) normalized shares

Name

The bank or username, where the level of indentation represents hierarchical depth within the tree structure. Associations are indented one additional space beyond their parent bank.

Shares

The raw share allocation assigned to this bank or user within its parent.

Normalized Shares

Normalized shares represent each entity's fraction of total root resources by multiplying share proportions up the bank tree. The calculation propagates from parent to child:

\[\text{S}_{normalized_{node}} = \frac{\text{shares}_{node}}{\text{shares}_{node+siblings}} \times \text{S}_{normalized_{parent}}\]

The root bank always has normalized shares of 1.0. Each child's normalized shares are computed by taking its fraction of siblings' shares and multiplying by its parent's normalized shares. This multiplicative calculation ensures that normalized shares always sum to the parent's normalized shares and represent the entity's portion of the root allocation.

Usage

Total job usage accumulated by this entity (displayed only with --verbose). For associations, this is their individual usage. For banks, this is the sum of all usage by users within that bank.

Norm Usage

Normalized usage represents this entity's proportion of total system usage. Calculated as:

\[\text{Usage}_{normalized_{node}} = \frac{\text{Usage}_{node}}{\text{Usage}_{root}}\]
Level FS

The fair-share value for the association. For more details on fairshare calculation, see Fair-Share Calculation.

Examples

Monitoring resource consumption

We can compare allocated shares against actual usage to identify over-consuming or under-utilizing associations:

$ flux account bank-info -t root -v
Name                      Shares  Norm Shares        Usage   Norm Usage  Level FS
root                           1     1.000000      10000.0     1.000000       inf
 A                             7     0.700000       8500.0     0.850000        --
  user1                        3     0.300000       5000.0     0.500000     0.333
  user2                        4     0.400000       3500.0     0.350000     0.667
 B                             3     0.300000       1500.0     0.150000        --
  user3                        1     0.300000       1500.0     0.150000     1.000

In this example, bank A has 7 shares out of 10 total, giving it 70% of root resources (0.7 normalized shares), and users within it are responsible for 85% of the system's total usage.

Within bank A, user1 has 3 shares out of 7, so it has \(3/7 \times 0.7 = 0.3\) (30% of root resources) normalized shares, and is responsible for 50% of the system's total usage. Similarly, user2 gets \(4/7 * 0.7 = 0.4\) (40% of root resources) normalized shares.

Bank B has 3 shares out of 10 total, giving it 0.3 normalized shares, and its sole user user3 is responsible for 15% of the system's total usage.

Analyzing hierarchical share distribution

Shares cascade through multiple levels of banks all the way down to users:

$ flux account bank-info -t root
Name                      Shares  Norm Shares   Norm Usage  Level FS
root                           1     1.000000     0.000000       inf
 A                           100     0.500000     0.000000        --
  Aa                          60     0.300000     0.000000        --
   user1                       1     0.100000     0.000000     0.500
   user2                       2     0.200000     0.000000     0.500
  Ab                          40     0.200000     0.000000        --
   user3                       1     0.200000     0.000000     0.500
 B                           100     0.500000     0.000000        --
  user4                        1     0.500000     0.000000     0.500

This multi-level hierarchy demonstrates how normalized shares propagate down the tree:

  • Banks A and B each have 100 shares out of 200 total, so they each get: \(100/200 * 1.0 = 0.5\) normalized shares

  • Bank Aa has 60 shares out of 100 within A, so it gets: \(60/100 * 0.5 = 0.3\) normalized shares

  • Bank Ab has 40 shares out of 100 within A, so it gets: \(40/100 * 0.5 = 0.2\) normalized shares

  • user1 has 1 share out of 3 total user shares in Aa, so they get: \(1/3 * 0.3 = 0.1\) normalized shares

  • user2 has 2 shares out of 3 total user shares in Aa, so they get: \(2/3 * 0.3 = 0.2\) normalized shares

  • user3 is the only user in Ab, so they get: \(1/1 * 0.2 = 0.2\) normalized shares

  • user4 is the only user in B, so they get: \(1/1 * 0.5 = 0.5\) normalized shares

Each entity's normalized shares represent its fraction of total root resources.

See Also

Fair-Share Calculation, Job Priorities, Flux Accounting Database Administration