License Server Usage Logging

Your Sentinel RMS License Manager can be configured to log usage, which can help with load analysis and problem diagnosis. This page provides information on setting up logging. Full details can be found in the Sentinel RMS System Administrators Guide which can be downloaded from the KBC downloads site. You can use the WlmAdmin tool to monitor current license usage.

What gets logged

KBC software like Petro-SIM works by checking out licenses when you start the program and open cases and returning licenses when you close cases and exit the program. Petro-SIM embodies a number of licensed features and each feature has a maximum allowed number of users. Each time you check out a license to a feature, you reduce the available number of licenses or seats for other users. Ultimately if all seats are in use, check out requests by further users will be denied.

The basic logging mechanism records:

  • License issues, when they are checked out by programs like Petro-SIM
  • License releases, when they are returned by programs
  • License denials, when licenses are not granted because all seats are in use

Information is logged to a text file which you can analyse using lsusage.

Activating logging

Logging is inactive by default and is started up by setting options flags read by the License Manager on start-up. There are three methods which in order of priority are setting through system services (method 1), setting in the registry (method 2) and through an environment variable (method 3). Options set through system services (method 1) are temporary; the remaining two methods are permanent. All three methods set the same information.

If full file pathnames are not specified while configuring the License Manager options, the files will be created under the /System32 directory by default.

Logging Variables

Option Description
-l usage-log-file Specifies the name and location of the License Manager’s usage log file, which enables usage logging. By default, usage logging is disabled.
-f trace-log-file Specifies the name and location of the trace file.
-tr <level> Sets the tracing level which can help diagnose conditions causing errors on the license server. It should not normally be necessary to use this option. Trace <level> values are:
  • Trace errors (4) - traces errors encountered during communication with the license server.
  • Trace functions (2) - traces the major licensing functions called during application key lifetime.
  • Trace license keys (1) - traces invalid license codes
  • Trace all (7) - traces all three levels.

Determine the <level> you want by adding the appropriate traces levels together.

-z <file-size> The maximum size of the usage and trace file log (if enabled). The size can be specified in bytes,kilobytes, or megabytes. For instance, -z 2000 means 2000 bytes, -z 2k means 2 kilobytes, -z 2m means 2 megabytes. The default value is 1 megabyte.
-x Disables automatic backup of the usage and trace log files in case of overflow. The License Manager will stop writing further records to the file.

By default, when the log file reaches its maximum size the contents of the log file are moved into a new file that has the same name as the original log file but has two numeric digits appended to its name. For example, if the original log file is named lserv.log, the first backup file will be named lserv.log.00. The next time a backup file is created, the new file will use the next available backup number (for example, lserv.log.01).The maximum number of backup files is 99; you can move the existing backup log files to another directory and the License Manager will begin again with 00.

If clients are connected to the license server when the back-up file is created, dummy records are created for any pending transactions in the backup file; corresponding dummy records are created in the new file. The dummy records are identified by the user name LM_SERVER.

If the -x option is specified, the file will not be backed up on overflow.

-u reservation-file Specifies the name and location of the License Manager’s reservation file, which is used to reserve licenses to named users or groups of users.

The License Manager recognises other options as described in its System Administrators Guide.

Example

Suppose you wanted to activate logging to a file C:\Logs\MyUsage.log, setting a maximum size of 2 Megabytes. The options would be:

-l C:\Logs\MyUsage.log -z 2m

We recommend that uyou avoid spaces in path and file names because these can cause problems with command strings. You set these options using one of the three following methods.

Setting Variables Method 1 - Using the Windows System Services Console

On a supported Windows system, use the following steps:

  1. From the Start menu, point to Settings > Control Panel.
  2. Double-click Administrative Tools.
  3. Double-click Services.
  4. In the Services window, locate Sentinel RMS License Manager and double-click it.
  5. Stop the License Manager service (if running already).
  6. Set the parameter(s) in Start Parameters. For example, -l myusage.log will cause myusage.log to be created containing all the license server usage information (such as, the license server start, shut-down, license request, and license release).
  7. Start the License Manager after providing the settings. See the following screenshot for an example:

Please note that changes you make in this way are not remembered when the server or service next restarts. Please use either method 2 or 3 to make permanent changes.

Setting Variables Method 2 - Using the System Registry (Command-line Options)

In the Windows Registry Editor, create/update the value of CommandLineOpts under the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Rainbow Technologies\SentinelLM\CurrentVersion. (Note: on 64-bit systems you may find this key under HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node instead of directly under SOFTWARE).

See the screenshot below for an example:

You create a new variable by right clicking in the right-hand pane. Select New > String Value and then rename the variable to CommandLineOpts. Double-click on the variable name to edit its value.

You will have to shutdown and restart the License Manager before these variables take effect.

Setting Variables Method 3 - Using the LSERVOPTS Environment Variable

Environment variables are usually set using the Control Panel > System > Advanced > Environment Variables dialog box. You will usually need administrator privileges to change these settings. For license server options you need to create a LSERVOPTS System variable that has the command string value you want.

For example:

You will have to shutdown and restart the License Manager before these variables take effect.

Further details

Please refer to the Sentinel RMS System Administrators Guide for more information on the understanding and analysing log files. You can obtain this log file from downloads.