blstat

Displays dynamic license information.

Synopsis

blstat [-s] [-S] [-D service_domain_name | "service_domain_name ..."] [-P][-t token_name | "token_name ..."] [-o alpha | total | avail] [-g "feature_group ..."] [-slots]

blstat [-a] [-c token_name] [-G] [-Lp ls_project_name | "ls_project_name ..."]

blstat [-D service_domain_name | "service_domain_name ..."] [-t token_name | "token_name ..."] [-f "field_name[:[-][output_width]] ... [delimiter='character']" ] [-a] [-alloc] [-cname] [-noheader] [-x] [-X] [-R "res_req"] [host_name ... | host_group ... | compute_unit ...]

blstat [-Lp ls_project_name | "ls_project_name ..."] [-f "field_name[:[-][output_width]] ... [delimiter='character']" ] [-a] [-alloc] [-cname] [-noheader] [-x] [-X] [-R "res_req"] [host_name ... | host_group ... | compute_unit ...]

blstat [-h | -V]

Description

Displays license usage statistics for LSF License Scheduler.

By default, shows information about all licenses and all clusters.

Options for cluster mode and project mode

-S

Displays information on the license servers that are associated with license features.

-s

Displays license usage of the LSF and non-LSF workloads. Workload distributions are defined by the WORKLOAD_DISTRIBUTION parameter in the lsf.licensescheduler file. The blstat command marks any distribution policy violations with an asterisk (*) at the beginning of the line.

-D service_domain_name | "service_domain_name ..."

Shows information only about specified service domains. Use spaces to separate multiple names, and enclose names in quotation marks.

-f output_format_string

Sets the customized output format.

Specify which blstat fields (or aliases instead of the full field names), in which order, and with what width to display.
Specify only the blstat field name or alias to set its output to unlimited width and left justification.
Specify the colon (:) without a width to set the output width to the recommended width for that field.
Specify the colon (:) with a width to set the maximum number of characters to display for the field. When the value exceeds this width, blstat truncates the output.
Specify a hyphen (-) to set right justification when blstat displays the output for the specific field. If not specified, the default is to set left justification.
Use delimiter= to set the delimiting character to display between different headers and fields. This delimiter must be a single character. By default, the delimiter is a space.

Output customization applies only to the blstat command with no options, and to output for blstat with the following options: -Lp, -D, -t. The -f option does not work with any other blstat option.

The following are the field names used to specify the blstat fields to display, recommended width, aliases you can use instead of field names, the applicable LSF License Scheduler modes, and a brief description of the field:

Table 1. Output fields for blstat
Field name	Width	Alias	Mode	Description
service_domain_name	19	sd_name	all	Name of the service domain
service_domain_others	9	sd_others		Total number of "others" tokens in the service domain
service_domain_lsf_total	12	sd_lsf_total		Total number of tokens that LSF can use from the service domain
service_domain_alloc	8	sd_alloc	cluster mode	Total number of allocated tokens from the service domain
service_domain_use	7	sd_use	cluster mode	Total number of used tokens from the service domain
service_domain_inuse	8	sd_inuse	project mode	Total number of tokens in use from the service domain
service_domain_reserve	7	sd_rsv		Total number of reserved tokens from the service domain
service_domain_free	7	sd_free		Total number of free tokens from the service domain
project_name	15	proj_name		Name of the project
project_share	7	proj_share		Number of shares for the project
project_own	7	proj_own		Number of tokens that are owned by the project
project_inuse	7	proj_inuse		Number of tokens that are in use by the project
project_reserve	7	proj_rsv		Number of tokens that are reserved by the project
project_free	7	proj_free		Number of free tokens for the project
project_demand	8	proj_demand		Number of tokens that are demanded by the project
project_limit	7	proj_limit		The project limit
project_non_share	11	proj_non_share		Number of non-shared tokens for the project
cluster_name	15	cl_name	all	Name of the cluster
cluster_share	7	cl_share	cluster mode	Number of shares in the cluster
cluster_alloc	7	cl_alloc	all	Number of tokens that are allocated to the cluster
cluster_target	8	cl_target	all	Target number of tokens for the cluster
cluster_inuse	7	cl_inuse	all	Number of tokens that are in use in the cluster
cluster_reserve	7	cl_rsv		Number of tokens that are reserved in the cluster
cluster_free	7	cl_free		Number of free tokens in the cluster
cluster_over	7	cl_over	all	Number of overused tokens in the cluster
cluster_demand	8	cl_demand	all	Demand of the cluster
cluster_peak	7	cl_peak	cluster mode	Peak number of used tokens in the cluster
cluster_buffer	8	cl_buff	cluster mode	Allocate buffer in the cluster
cluster_acum_use	10	cl_acum_use	project mode	Accumulated number of used tokens in the cluster
cluster_scaled_acum	13	cl_scaled_acum		Scaled number of accumulated used tokens in the cluster
cluster_avail	7	cl_avail		Number of available tokens in the cluster
feature_name	18	feat_name	all	Name of the feature
feature_mode	20	feat_mode		Feature mode
feature_lm_license_name	17	feat_lm_lic_name		Name of the license feature in the FlexNet server

Note: Field names and aliases are not case-sensitive. Valid values for the output width are any positive integer 1 - 4096.

-g feature_group ...

When FEATURE_GROUP is configured for a group of license features in the lsf.licensescheduler file, shows information about features that are configured in the FEATURE_LIST parameter for specified feature groups. You can specify more than one feature group.

When you specify feature names with the -t option, features in the FEATURE_LIST value that is defined by the -t option and feature groups are both displayed.

Feature groups that are listed but not defined in the lsf.licensescheduler file are ignored.

-slots

Displays how many slots are currently used by LSF License Scheduler jobs (Current job slots in use) and the peak number of slots in use (Peak job slots used.

-o alpha | total | avail

Sorts license feature information alphabetically by total licenses, or by available licenses.

alpha: Features are listed in descending alphabetical order.
total: Features are sorted by the descending order of the sum of licenses that are allocated to LSF workload from all the service domains that are configured to supply licenses to the feature. Licenses that are borrowed by non-LSF workload are not included in this amount.
avail: Features are sorted by descending order of licenses available, including free tokens.

-P

Displays percentage values for INUSE and RESERVE. The percentage value represents the number of used and reserved tokens that the project has, compared to total number of licenses.

-t token_name | "token_name ..."

Shows only information about specified license tokens. Use spaces to separate multiple names, and enclose the names in quotation marks.

-h

Prints command usage to stderr and exits.

-V

Prints the release version to stderr and exits.

Options for project mode only

-a

Displays each project group’s accumulated value of licenses. The license token dispatch order is based on the sort order, which is based on the scaled accumulate value of each project. The lower the value, the sooner the license token is dispatched to that project.

-c token_name

Displays cross cluster information for tokens.

In project mode, the information is sorted by the value of the SCALED_ACUM parameter. The first cluster that is listed receives tokens first.

Information that is displayed includes token usage, reserved tokens, free tokens, demand for tokens, accumulated value of tokens, and scaled accumulate value of tokens in each cluster.

For fast dispatch project mode, also displays the actual and ideal number of tokens that are allocated to the cluster:

TARGET: The ideal number of licenses that are allocated to the cluster.
OVER: The number of licenses that are checked out by RUN jobs in the cluster under the license projects in excess of the rusage value.
FREE: The number of license that is allocated to the cluster but not used.
DEMAND: The number of tokens that are required by the cluster under the license project.

-G

Displays dynamic hierarchical license information.

The blstat -G command also works with the -t option to display only hierarchical information for the specified feature names.

-Lp ls_project_name | "ls_project_name ..."

Shows project description for specified non-hierarchical projects. Use spaces to separate multiple names and enclose names in quotation marks.

If project group paths are enabled (PROJECT_GROUP_PATH=Y parameter in the lsf.licensescheduler file), the blstat -Lp command displays the license projects that are associated with the specified project for all features. The blstat -Lp -t command displays the associated license projects for the specified feature. If the parameter is disabled, only the specified project is displayed.

Output

Information is organized first by license feature, then by service domain. For each combination of license and service domain, LSF License Scheduler displays a line of summary information followed by rows of license project or cluster information.

In each group of statistics, numbers and percentages refer only to licenses of the specified license feature that can be checked out from FlexNet license server hosts in the specified service domain.

Cluster mode summary output

FEATURE: The license name. This name appears only once for each feature.
SERVICE_DOMAIN: The name of the service domain that provided the license.
TOTAL_TOKENS: The number of licenses from this service domain that is reserved for LSF License Scheduler jobs.
TOTAL_ALLOC: The number of licenses from this service domain that are allocated to clusters by LSF License Scheduler.
In most cases TOTAL_ALLOC is equal to TOTAL_USE, however, when there are licenses counted under OTHERS or when tokens are reclaimed, TOTAL_ALLOC might be less than TOTAL_TOKENS.
TOTAL_USE: The number of licenses in use by LSF License Scheduler projects, which are determined by totaling all INUSE, RESERVE, and OVER values.
OTHERS: The number of licenses that are checked out by applications outside of LSF License Scheduler.

Cluster output for cluster mode

For each cluster that is configured to use the license, the blstat command displays the following information.

CLUSTER: The cluster name.
SHARE: The percentage of licenses that are assigned to the license project by the LSF License Scheduler administrator. The share determines how many licenses the project is entitled to when projects compete for licenses. This information is static, and for a LAN service domain is always 100%.
The percentage is calculated to one decimal place by using the share assignment in the lsf.licensescheduler file.
ALLOC: The number of licenses that are currently allocated to the cluster by the bld daemon.
TARGET: The ideal number of licenses that are allocated to the cluster. Normally, this amount is the same as the ALLOC field, but the values might temporarily be different. For example, when a license is reclaimed, where one cluster is using more than its allocation, another cluster is prevented from getting its ideal amount.
INUSE: The number of licenses that are checked out by jobs in the cluster.
RESERVE: The number of licenses that are reserved in the service domain for jobs that are running in the cluster. This value is the difference between the job rusage and the number of checked out licenses attributed to the job by LSF License Scheduler.
If the same license is available from both LAN and WAN service domains in cluster mode, LSF License Scheduler expects jobs to try to obtain the license from the LAN first. The administrator must make sure that applications behave in this manner, by using the FlexNet environment variables and LM_LICENSE_FILE.
OVER: The amount of license check-outs exceeding rusage, summed over all jobs.
PEAK: By default, the maximum of INUSE+RESERVE+OVER observed over the past 5 minutes. The observation period is set by the PEAK_INUSE_PERIOD parameter in either the Parameters or Feature section.
PEAK is used in scheduling to estimate the cluster’s capacity to use licenses in this service domain.
BUFFER: The optional allocation buffer that is configured in the ALLOC_BUFFER parameter of the Feature section for WAN service domains. When defined, dynamic license token allocation is enabled.
FREE: The number of licenses the cluster has free. The license tokens are allocated to the license project by LSF License Scheduler, but the licenses are not reserved and are not yet checked out from the FlexNet license manager.
DEMAND: Numeric value that indicates the number of tokens that are required by each cluster.

Project mode summary output

FEATURE

The license name. This name appears only once for each feature.

SERVICE_DOMAIN

The name of the service domain that provided the license.

TOTAL_INUSE

The number of licenses in use by LSF License Scheduler projects. Represents licenses in use that are checked out from the FlexNet license manager.

TOTAL_RESERVE

The number of licenses that are reserved for LSF License Scheduler projects. Represents licenses that are reserved and are not yet checked out from the FlexNet license manager.

TOTAL_FREE

The number of free licenses that are available to LSF License Scheduler projects. Represents licenses that are not reserved or in use.

OTHERS

The number of licenses that are checked out by users who are not submitting their jobs to LSF License Scheduler projects.

By default, in project mode these licenses are not being managed by LSF License Scheduler policies.

(Project mode only) To enforce license distribution policies for these license features, configure the ENABLE_DYNAMIC_RUSAGE=Y parameter in the Feature section for those features in the lsf.licensescheduler file.

Workload output for both modes

LSF_USE: The total number of licenses in use by LSF License Scheduler projects in the LSF workload.
LSF_DESERVE: The total number of licenses that are assigned to LSF License Scheduler projects in the LSF workload.
LSF_FREE: The total number of free licenses available to LSF License Scheduler projects in the LSF workload.
NON_LSF_USE: The total number of licenses in use by projects in the non-LSF workload.
NON_LSF_DESERVE: The total number of licenses that are assigned to projects in the non-LSF workload.
NON_LSF_FREE: The total number of free licenses available to projects in the non-LSF workload.

Project output for project mode

For each project that is configured to use the license, the blstat command displays the following information.

PROJECT: The LSF License Scheduler project name.
SHARE: The percentage of licenses that are assigned to the license project by the LSF License Scheduler administrator. The share value determines how many licenses the project is entitled to when projects compete for licenses. This information is static.
The percentage is calculated to one decimal place by using the share assignment in the lsf.licensescheduler file.
LIMITS: The maximum number of licenses that the hierarchical project group member project can use at any one time.
OWN: Numeric value that indicates the number of tokens that are owned by each project.
INUSE: The number of licenses in use by the license project. Licenses in use are checked out from the FlexNet license manager.
RESERVE: The number of licenses that are reserved for the license project. The corresponding job is running, but its license is not yet checked out from the FlexNet license manager.
FREE: The number of licenses the license project has free. The license tokens are allocated to the license project by LSF License Scheduler, but the licenses are not reserved and are not yet checked out from the FlexNet license manager.
DEMAND: Numeric value that indicates the number of tokens that are required by each project.
NON_SHARED: The number of non-shared licenses that belong to the license project. The license tokens that are allocated to non-shared distribution are scheduled before the tokens allocated to shared distribution.
DESCRIPTION: Description of the project.
ACUM_USE: The number of tokens that are accumulated by each consumer at run time. It is the number of licenses that are assigned to a consumer for a specific feature.
SCALED_ACUM: The number of tokens that are accumulated by each consumer at run time, divided by the SHARE value. LSF License Scheduler uses this value to schedule the tokens for each project.

Cross cluster token output for project mode

For each project that is configured to use the license, the blstat -c command displays the following information.

PROJECT: The LSF License Scheduler project name.
CLUSTER: The name of a cluster that uses the project.
INUSE: The number of licenses in use by the license project. Licenses in use are checked out from the FlexNet license manager.
RESERVE: The number of licenses that are reserved for the license project. The corresponding job is running, but its license is not yet checked out from the FlexNet license manager.
FREE: The number of licenses the license project has free. The license tokens are allocated to the license project by LSF License Scheduler, but the licenses are not reserved and are not yet checked out from the FlexNet license manager.
NEED: The total number of tokens that are required by pending jobs (rusage).
ACUM_USE: The number of tokens that are accumulated by each consumer at run time. It is the number of licenses that are assigned to a consumer for a specific feature.
SCALED_ACUM: The number of tokens that are accumulated by each consumer at run time, divided by the SHARE value. LSF License Scheduler uses this value to schedule the tokens for each project.

Cross cluster token output for fast dispatch project mode

For each project in fast dispatch project mode that is configured to use the license, blstat -c displays the following information.

PROJECT: The LSF License Scheduler project name.
CLUSTER: The name of a cluster that uses the project.
ALLOC: The actual number of licenses that are currently allocated to the cluster. It is possible that the sum of licenses in the INUSE, RESERVE, and OVER fields are larger than the ALLOC field. In this case, the number of tokens that the cluster occupies will eventually decrease towards the ALLOC value after the job finishes.
The percentage is calculated to one decimal place by using the share assignment in the lsf.licensescheduler file.
TARGET: The ideal number of licenses that are allocated to the cluster. Normally, this amount is the same as the ALLOC field, but the values might temporarily be different. For example, a license is reclaimed, where one cluster is using more than its allocation, which prevents another cluster from getting its ideal amount.
INUSE: The number of licenses in use by the cluster under the license project. Licenses in use are checked out from the FlexNet license manager.
RESERVE: The number of licenses that are reserved by jobs in the cluster under the license project. The corresponding job is running, but its license is not yet checked out from the FlexNet license manager. The INUSE and RESERVE fields add up to the rusage of RUN jobs in the cluster.
OVER: The number of licenses that are checked out by RUN jobs in the cluster under the license project in excess of the rusage value.
FREE: The number of licenses that the cluster under the license project has free. The license tokens are allocated to the license project by LSF License Scheduler, but the licenses are not reserved and are not yet checked out from the FlexNet license manager.
DEMAND: Numeric value reported from the cluster, which indicates the number of tokens that are required by the cluster under the license project.

Project group output for project mode

SHARE_INFO_FOR: The root member and name of the hierarchical project group. The project information that is displayed after this title shows the information specific to this particular project group. If this root member is itself a member of another project group, the relationship is displayed as follows:
/root_name/member_name/...
PROJECT/GROUP: The members of the hierarchical group, which is listed by group or project name.

-slots output

Displays the following information:

Current job slots in use: The total number of slots currently being used by LSF License Scheduler jobs, including taskman jobs.
Peak job slots used: The peak number of slots in use since the last time LSF License Scheduler was restarted.

Sample output

For example, the blstat command has the following output for a cluster mode feature:

blstat -t f1000
FEATURE: f1000            
 SERVICE_DOMAIN: Lan12
 TOTAL_TOKENS: 1000 TOTAL_ALLOC: 967  TOTAL_USE: 655  OTHERS: 25  
  CLUSTER     SHARE   ALLOC TARGET INUSE RESERVE OVER  PEAK  BUFFER FREE  DEMAND
  clusterA     66.7 %  647  15     0     655     0     658   100    0     7452 
  clusterB     33.3 %  320  15     0     0       0     0     -      320   0    
 SERVICE_DOMAIN: Lan99
 TOTAL_TOKENS: 2000 TOTAL_ALLOC: 2000 TOTAL_USE: 0    OTHERS: 0   
  CLUSTER     SHARE   ALLOC TARGET INUSE RESERVE OVER  PEAK  BUFFER FREE  DEMAND
  clusterA     25.0 %  500  15     0     0       0     0     100    500   0    
  clusterB     25.0 %  500  15     0     0       0     0     100    500   0    
  clusterC     25.0 %  500  15     0     0       0     0     -      500   0    
  clusterD     25.0 %  500  15     0     0       0     0     -      500   0

For example, for a project mode feature with a group distribution configuration the blstat command shows the locality of the hspice feature that is configured for various sites:

blstat
FEATURE: hspice
 SERVICE_DOMAIN: SD3 SD4
 TOTAL_INUSE: 0    TOTAL_RESERVE: 0    TOTAL_FREE: 22   OTHERS: 0
  PROJECT                 SHARE   OWN  INUSE RESERVE FREE   DEMAND 
  Lp1                     50.0 %   3     1    0        0     11
  Lp2                     50.0 %   1     3    0        0     11
FEATURE: hspice@clusterA
 SERVICE_DOMAIN: SD1
 TOTAL_INUSE: 0    TOTAL_RESERVE: 0    TOTAL_FREE: 25   OTHERS: 0
  PROJECT                 SHARE   OWN  INUSE RESERVE FREE   DEMAND 
  Lp1                     50.0 %   4     0    0      12       3
  Lp2                     50.0 %   5     0    0      13       1
FEATURE: hspice@siteB
 TOTAL_INUSE: 0    TOTAL_RESERVE: 0    TOTAL_FREE: 65   OTHERS: 0
  PROJECT                 SHARE   OWN  INUSE RESERVE FREE   DEMAND 
  Lp1                     50.0 %   4     0    0      32       2
  Lp2                     50.0 %   5     0    0      33       6

For example, for a project mode feature, the blstat -c command displays the following information:

blstat -c f50
FEATURE: f50
PROJECT         CLUSTER        INUSE   RESERVE   FREE   NEED   ACUM_USE   SCALED_ACUM   AVAIL
myProj2         interactive    0       0         9      0      0.0        0.0           9
                clusterA       0       0         8      0      0.0        0.0           0
                clusterB       0       0         8      0      0.0        0.0           0
default         interactive    0       0         9      0      0.0        0.0           9
                clusterA       0       0         8      0      0.0        0.0           0
                clusterB       0       0         8      0      0.0        0.0           0

For example, for a fast dispatch project mode feature, the blstat -c command displays the following information:

blstat -c f100
FEATURE: f100
PROJECT     CLUSTER         ALLOC TARGET INUSE  RESERVE OVER  FREE  DEMAND
myProj1     interactive     4     4      0      0       0     4     0
            clusterA        3     3      0      0       0     3     0
            clusterB        3     3      0      0       0     3     0
myProj2     interactive     30    30     0      0       0     30    0
            clusterA        30    30     0      0       0     30    0
            clusterB        30    30     0      0       0     30    0