MATHEMATICA TUTORIAL

Monitoring MathLM

What Is MonitorLM?

MonitorLM gives information on the total number of licenses available and checked out, the fully qualified domain name and username of those who have them checked out, and so on. MonitorLM can send output to the terminal, open a web browser, or write to a file. The output for MonitorLM is customizable by means of a configuration file. MonitorLM automatically supports IPv4 and IPv6 environments.

Starting MonitorLM

To start MonitorLM, change directory to the location in which MathLM is installed, and type .\monitorlm servername (on Windows) or ./monitorlm servername (on Linux or Mac OS X). The first argument of the monitorlm command specifies the name of the license server running MathLM. If you do not specify a server name explicitly, the local machine name is chosen as the default.

MonitorLM Command-Line Options

The following options are available using the monitorlm command. The syntax for specifying an option is monitorlm

-file file	specify file to which output should be directed
-format f	specify the format for the output of MonitorLM
-localtime	specify that all time references are in local time instead of GMT
-template file	specify the template file for the output of MonitorLM

monitorlm command-line options.

If -file is not set, MonitorLM will write to stdout.

The three possible output formats in -format are as follows:

text	send output in text format to stdout (default on Linux)
html	send output in HTML format and launch a web browser (default on Windows and Mac OS X)
cgi	send output in HTML format to stdout

-format output formats.

The cgi format is used when MonitorLM is launched directly by a web browser.

This shows what the output of MonitorLM looks like, with -format set to text.

Online help is available at
http://reference.wolfram.com/network

MathLM Version 8.0 
MathLM Server hostname.domain.com 
Date : Thursday, October 17 2010 21:11:59 
    
License Usage Summary:

                            License    Total    Total
Program                        Class    in Use    Authorized
------------------------------------------------------

Mathematica                    A        2        20
MathKernel                    A        4        40


Sub Mathematica                A        0        80
Sub MathKernel                A        0        80

Licenses in Use:

                            License
Program            Version        Class    Username    Hostname            Duration
----------------------------------------------------------------------------
Mathematica        7.0            A        username    client1.domain.com    08:49
Mathematica        8.0            A        username    client2.domain.com    06:33
MathKernel        7.0            A        username    client1.domain.com    08:44
MathKernel        8.0            A        username    client2.domain.com    06:52
MathKernel        8.0            A        username    client2.domain.com    06:52
MathKernel        8.0            A        username    client2.domain.com    06:30

This shows what the output of MonitorLM looks like in a web browser, with -format set to html.

Note that when -format is set to cgi, the output of MonitorLM is sent to stdout in HTML format. This shows what that output looks like when displayed in a web browser.

Customizing the Output of MonitorLM

You can customize the content and format of the output from MonitorLM by editing a template file. This is a plain text file, which can contain the following types of elements.

Constant tags—These tags represent data that is static during the execution of MonitorLM and license independent, such as the current date. Each of these tag names has the prefix CONST.

Variable tags—These tags act as wrappers to constant tags. They are useful in defining the format for data to be output in series, such as a table of current MathLM users. They are useful for improving readability of the template file. Each of these tag names has the prefix VAR.

Process-dependent tags—The value of these tags depends upon which Mathematica process is being displayed and includes data like the process owner's username and IP address. Each of these tag names has the prefix PROC.

Repeated tags—These tags serve as placeholders for information regarding an unknown number of licenses. They are the only tags whose size is not predetermined. Only the checkout lines are repeated, and there is one checkout line per license. Each of these tag names has the prefix REP.

Text wrappers—This is the text that a user can wrap around the tags, for presentation and formatting.

Each tag in the template file has the form %var#, where

var represents a variable whose value is provided by the server.

# is a number defining a specific format for the display of the variable var.

In addition to the %var# commands, the template file can also include plain text such as brackets, dashes, quotation marks, and arbitrary comments. The text can be used to include comments and separators in the server messages for formatting purposes. All text included in the string appears literally in the server message with the following two exceptions: use %q to include a double quote ("), and use %% to include a percentage sign (%).

Predefined Constant Tags

Here are two tables of constant tag names that can be included in the template file along with the numeric values for their possible formats.

Date Constant Tags

The following are Date Constant Tags for MonitorLM.

Tag Name	Possible Values	Description
%CONST_DATE_D#	[1...31]	day of month
%CONST_DATE_W#	1 - Numeric [ 1 ... 7 ] 2 - Abbreviated [ Sun ... Sat ] 3 - Verbose [ Sunday ... Saturday ]	day of week
%CONST_DATE_M#	1 - Numeric [ 1 ... 12 ] 2 - Abbreviated [ Jan ... Dec ] 3 - Verbose [ January ... December ]	month
%CONST_DATE_Y#	1 - Two-digit [ 10 ] 2 - Four-digit [ 2010 ]	year
%CONST_DATE_T#	1 - Twelve-hour [ 10:20:15 ]	time

MonitorLM Date Constant Tags.

Server and Process Constant Tags

The following are Server and Process Constant Tags for MonitorLM.

Tag Name	Description
%CONST_SERVER_IP	MathLM IP address
%CONST_SERVER_HOST	MathLM hostname
%CONST_SERVER_DOMAIN	MathLM domain
%CONST_SERVER_FQDN	MathLM fully qualified domain name
%CONST_SERVER_VERSION	MathLM version
%CONST_CA_FE_AUTHORIZED	number of class A front ends authorized
%CONST_CA_SUB_FE_AUTHORIZED	number of class A sub-front end processes authorized
%CONST_CB_FE_AUTHORIZED	number of class B front ends authorized
%CONST_CB_SUB_FE_AUTHORIZED	number of class B sub-front end processes authorized
%CONST_TOTAL_FE_AUTHORIZED	total number of front ends authorized
%CONST_TOTAL_SUB_FE_AUTHORIZED	total number of sub-front end processes authorized
%CONST_CA_KE_AUTHORIZED	number of class A kernels authorized
%CONST_CA_SUB_KE_AUTHORIZED	number of class A sub-kernels processes authorized
%CONST_CB_KE_AUTHORIZED	number of class B kernels authorized
%CONST_CB_SUB_KE_AUTHORIZED	number of class B sub-kernel processes authorized
%CONST_TOTAL_KE_AUTHORIZED	total number of kernels authorized
%CONST_TOTAL_SUB_KE_AUTHORIZED	total number of sub-kernel processes authorized
%CONST_CA_FE_AVAILABLE	number of class A front ends available
%CONST_CA_SUB_FE_AVAILABLE	number of class A sub-front end processes available
%CONST_CB_FE_AVAILABLE	number of class B front ends available
%CONST_CB_SUB_FE_AVAILABLE	number of class B sub-front end processes available
%CONST_TOTAL_FE_AVAILABLE	total number of front ends available
%CONST_TOTAL_SUB_FE_AVAILABLE	total number of sub-front end processes available
%CONST_CA_KE_AVAILABLE	number of class A kernels available
%CONST_CA_SUB_KE_AVAILABLE	number of class A sub-kernel processes available
%CONST_CB_KE_AVAILABLE	number of class B kernels available
%CONST_CB_SUB_KE_AVAILABLE	number of class B sub-kernels processes available
%CONST_TOTAL_KE_AVAILABLE	total number of kernels available
%CONST_TOTAL_SUB_KE_AVAILABLE	total number of sub-kernel processes available
%CONST_CA_FE_OUT	number of class A front ends in use
%CONST_CA_SUB_FE_OUT	number of class A sub-front end processes in use
%CONST_CB_FE_OUT	number of class B front ends in use
%CONST_CB_SUB_FE_OUT	number of class B sub-front end processes in use
%CONST_TOTAL_FE_OUT	total number of front ends in use
%CONST_TOTAL_SUB_FE_OUT	total number of sub-front end processes in use
%CONST_CA_KE_OUT	number of class A kernels in use
%CONST_CA_SUB_KE_OUT	number of class A sub-kernel processes in use
%CONST_CB_KE_OUT	number of class B kernels in use
%CONST_CB_SUB_KE_OUT	number of class B sub-kernel processes in use
%CONST_TOTAL_KE_OUT	total number of kernels in use
%CONST_TOTAL_SUB_KE_OUT	total number of sub-kernels processes in use

MonitorLM Server and Process Constant Tags.

Customizable Variable Tags

The following are Customizable Variable Tags for MonitorLM.

Tag Name	Possible Values	Description
%VAR_DATE_AMPM	"A.M." "P.M."	text to use for a.m. and p.m. when displaying time
%VAR_MPROCESS	"Mathematica" "MathKernel" "SubMathematica" "SubMathKernel"	title for Mathematica processes; the first string in quotes is the front end title, the second is the kernel title, the third is the sub-front end process title, and the fourth is the sub-kernel process title
%VAR_LIC_CLASS	"Class A" "Class B"	labels for each license class
%VAR_CA_AUTHORIZED_HEADER	"Class A Authorized \t Front End \t Kernel"	header for number of authorized class A licenses; use with the predefined constant tags %CONST_CA_FE_AUTHORIZED and %CONST_CA_KE_AUTHORIZED
%VAR_CA_SUB_AUTHORIZED_HEADER	"Class A Authorized \t Front End \t Kernel"	header for number of authorized class A sub-process licenses; use with the predefined constant tags %CONST_CA SUB_FE_AUTHORIZED and %CONST_CA SUB_KE_AUTHORIZED
%VAR_CB_AUTHORIZED_HEADER	"Class B Authorized \t Front End \t Kernel"	header for number of authorized class B licenses; use with the predefined constant tags %CONST_CB_FE_AUTHORIZED and %CONST_CB_KE_AUTHORIZED
%VAR_CB_SUB_AUTHORIZED_HEADER	"Class B Authorized \t Front End \t Kernel"	header for number of authorized class B sub-process licenses; use with the predefined constant tags %CONST_CB_SUB FE_AUTHORIZED and %CONST_CB_SUB KE_AUTHORIZED
%VAR_TOTAL_AUTHORIZED_HEADER	"Total Authorized \t Front End \t Kernel"	header for total number of authorized licenses; use with the predefined constant tags %CONST_TOTAL_FE_AUTHORIZED and %CONST_TOTAL_KE_AUTHORIZED
%VAR_TOTAL_SUB_AUTHORIZED_HEADER	"Total Authorized \t Front End \t Kernel"	header for total number of authorized sub-process licenses; use with the predefined constant tags %CONST_TOTAL_SUB FE_AUTHORIZED and %CONST_TOTAL_SUB KE_AUTHORIZED
%VAR_CA_CHECKEDOUT_HEADER	"Class A Licenses in Use\nUsername \t Hostname \t Program \t Slot # \t Duration"	header for information about class A licenses in use; use with the repeated tag %REP_CA_CHECKOUT_LINE
%VAR_CA_SUB_CHECKEDOUT_HEADER	"Class A Licenses in Use\nUsername \t Hostname \t Program \t Slot # \t Duration"	header for information about class A sub-process licenses in use; use with the repeated tag %REP_CA_CHECKOUT_LINE
%VAR_CB_CHECKEDOUT_HEADER	"Class B Licenses in Use\nUsername \t Hostname \t Program \t Slot # \t Duration"	header for information about class B licenses in use; use with the repeated tag %REP_CB_CHECKOUT_LINE
%VAR_CB_SUB_CHECKEDOUT_HEADER	"Class B Licenses in Use\nUsername \t Hostname \t Program \t Slot # \t Duration"	header for information about class B sub-process licenses in use; use with the repeated tag %REP_CB_SUB_CHECKOUT_LINE
%VAR_CHECKEDOUT_HEADER	"Licenses in Use\nUsername \t Hostname \t Program \t License Class \t Slot # \t Duration"	header for information about all licenses in use; use with the repeated tag %REP_GENERAL_CHECKOUT_LINE
%VAR_SUB_CHECKEDOUT_HEADER	"Licenses in Use\nUsername \t Hostname \t Program \t License Class \t Slot # \t Duration"	header for information about all sub-process licenses in use; use with the repeated tag %REP_GENERAL_SUB CHECKOUT_LINE

MonitorLM Customizable Variable Tags.

Note: The strings provided in this section are examples of possible values, not default settings. To use these tags, you must define them in your template.

Process-Dependent Tags

The following are Process-Dependent Tags for MonitorLM.

Tag Name	Description
%PROC_UID	user ID of Mathematica process owner
%PROC_USER	username of Mathematica process owner
%PROC_IP	IP address of machine using Mathematica process
%PROC_HOST	hostname of machine using Mathematica process
%PROC_DOMAIN	domain of machine using Mathematica process
%PROC_FQDN	fully qualified domain name of machine using Mathematica process
%PROC_SLOTNUM	slot number of Mathematica process
%PROC_VERSION	version of client
%PROC_DURATION	time client has been running

MonitorLM Process-Dependent Tags.

Repeated Tags

The following are Repeated Tags for MonitorLM.

Tag Name	Possible Values	Description
%REP_CA_CHECKOUT_LINE	"%PROC_USER \t %PROC_HOST \t %VAR_MPROCESS \t %PROC_SLOTNUM \t %PROC_DURATION\n"	Class A checkout line. This specifies the format of each line in the table or block that lists the class A processes in use. Corresponds to the customizable variable tag %VAR_CA_CHECKEDOUT_HEADER.
%REP_CA_SUB_CHECKOUT_LINE	"%PROC_USER \t %PROC_HOST \t %VAR_MPROCESS \t %PROC_SLOTNUM \t %PROC_DURATION\n"	Class A sub-process checkout line. This specifies the format of each line in the table or block that lists the class A sub-processes in use. Corresponds to the customizable variable tag %VAR_CA_SUB_CHECKEDOUT_HEADER.
%REP_CB_CHECKOUT_LINE	"%PROC_USER \t %PROC_HOST \t %VAR_MPROCESS \t %PROC_SLOTNUM \t %PROC_DURATION\n"	Class B checkout line. This specifies the format of each line in the table or block that lists the class B processes in use. Corresponds to the customizable variable tag %VAR_CB_CHECKEDOUT_HEADER.
%REP_CB_SUB_CHECKOUT_LINE	"%PROC_USER \t %PROC_HOST \t %VAR_MPROCESS \t %PROC_SLOTNUM \t %PROC_DURATION\n"	Class B sub-process checkout line. This specifies the format of each line in the table or block that lists the class B sub-processes in use. Corresponds to the customizable variable tag %VAR_CB_SUB_CHECKEDOUT_HEADER.
%REP_GENERAL_CHECKOUT_LINE	"%PROC_USER \t %PROC_HOST \t %VAR_MPROCESS \t %VAR_LIC_CLASS \t %PROC_SLOTNUM \t %PROC_DURATION\n"	General checkout line. Use this if you do not want to separate classes. Corresponds to the customizable variable tag %VAR_CHECKEDOUT_HEADER.
%REP_GENERAL_SUB_CHECKOUT_LINE	"%PROC_USER \t %PROC_HOST \t %VAR_MPROCESS \t %VAR_LIC_CLASS \t %PROC_SLOTNUM \t %PROC_DURATION\n"	General sub-process checkout line. Use this if you do not want to separate classes. Corresponds to the customizable variable tag %VAR_SUB_CHECKEDOUT_HEADER.

MonitorLM Repeated Tags.

Note: The strings provided in this section are examples of possible values, not default settings. To use these tags, you must define them in your template.

Note: In the template file, the text wrappers and tags that make up the output to MonitorLM must follow a line containing only the keyword %TEXT with no whitespace before or after it. Definitions for customized variable tags must precede the %TEXT line. If no variable tags are customized, the %TEXT line can be the first line of the file.

Samples and Behavior

Here is a simple text file that shows only the number of processes authorized, available, and in use. This example does not need to define any variable definition tags.

%TEXT
Time/Date : [%CONST_DATE_T2] [%CONST_DATE_M3 %CONST_DATE_D, %CONST_DATE_Y2]
Front End Processes Authorized: %CONST_TOTAL_FE_AUTHORIZED
Kernel Processes Authorized: %CONST_TOTAL_KE_AUTHORIZED
Front End Processes Available: %CONST_TOTAL_FE_AVAILABLE
Kernel Processes Available: %CONST_TOTAL_KE_AVAILABLE
Front End Processes In Use: %CONST_TOTAL_FE_OUT
Kernel Processes In Use: %CONST_TOTAL_KE_OUT

The resulting output has the form shown here.

Time/Date : [00:05:26] [October 20, 2010]
Front End Processes Authorized: 5
Kernel Processes Authorized: 5
Front End Processes Available: 4
Kernel Processes Available: 4
Front End Processes In Use: 1
Kernel Processes In Use: 1

Here is a slightly more sophisticated example. It is identical to the preceding example except that it also lists the processes in use and customizes variable tags.

# Begin variable tag definitions
%VAR_MPROCESS = "FE" "KE" "SFE" "SKE"
%VAR_TOTAL_CHECKEDOUT_HEADER = "Slot\t Program\t User\t Host\n"
%REP_GENERAL_CHECKOUT_LINE = "%PROC_SLOTNUM\t %VAR_MPROCESS\t %PROC_USER\t %PROC_HOST\n"

%TEXT
Time/Date : [%CONST_DATE_T2] [%CONST_DATE_M3 %CONST_DATE_D, %CONST_DATE_Y2]
Front End Processes Authorized: %CONST_TOTAL_FE_AUTHORIZED
Kernel Processes Authorized: %CONST_TOTAL_KE_AUTHORIZED
Front End Processes Available: %CONST_TOTAL_FE_AVAILABLE
Kernel Processes Available: %CONST_TOTAL_KE_AVAILABLE
Front End Processes In Use: %CONST_TOTAL_FE_OUT
Kernel Processes In Use: %CONST_TOTAL_KE_OUT 

%VAR_TOTAL_CHECKEDOUT_HEADER
%REP_GENERAL_CHECKOUT_LINE

The resulting output has the form shown here.

Time/Date : [00:05:26] [October 20, 2010]
Front End Processes Authorized: 5
Kernel Processes Authorized: 5
Front End Processes Available: 4
Kernel Processes Available: 4
Front End Processes In Use: 1
Kernel Processes In Use: 1

Slot    Program   User       Host
6       FE        username   hostname
1       KE        username   hostname

The following example demonstrates HTML output. This is useful, for example, if you want to view the MonitorLM output in a web browser.

%VAR_MPROCESS = "FE" "KE" "SFE" "SKE"
%VAR_TOTAL_CHECKEDOUT_HEADER = "<TR><TD><B>Slot</B></TD> <TD><B>Program</B></TD> <TD><B>User</B></TD> <TD><B>FQDN</B></TD> </TR>\n"
%REP_GENERAL_CHECKOUT_LINE = "<TR> <TD>%PROC_SLOTNUM</TD> <TD>%VAR_MPROCESS</TD> <TD>%PROC_USER</TD> <TD>%PROC_FQDN</TD> </TR>\n"

%TEXT
<HTML>
<HEAD> <TITLE> MathLM Status </TITLE> </HEAD>
<BODY>
<TABLE BORDER=1 CELLPADDING=5>
<TR><TD COLSPAN=2><B>MathLM Server</B></TD> <TD COLSPAN=2><B>%CONST_SERVER_FQDN</B></TD> </TR>
<TR><TD COLSPAN=2>Time/Date</TD> <TD COLSPAN=2>[%CONST_DATE_T2] [%CONST_DATE_M3 %CONST_DATE_D, %CONST_DATE_Y2]</TD> </TR>
<TR><TD COLSPAN=2>Authorized</TD> <TD>%CONST_TOTAL_FE_AUTHORIZED</TD> <TD>%CONST_TOTAL_KE_AUTHORIZED</TD></TR>
<TR><TD COLSPAN=2>Available</TD> <TD>%CONST_TOTAL_FE_AVAILABLE</TD> <TD>%CONST_TOTAL_KE_AVAILABLE</TD></TR>
<TR><TD COLSPAN=2>In Use</TD> <TD>%CONST_TOTAL_FE_OUT</TD> <TD>%CONST_TOTAL_KE_OUT</TD></TR>
 
%VAR_TOTAL_CHECKEDOUT_HEADER
%REP_GENERAL_CHECKOUT_LINE

</TABLE>
</BODY>
</HTML>

The resulting output has the form shown here.