Open the Table of Contents

You are here: About the RMS License Manager > License Manager Usage Logs

# License Manager Usage Logs

The License Manager can record all license requests and releases in the usage log file. Refer to the following sections for details:

Contents of the Usage Log

The name and location of the usage file is set by the License Manager startup options. The License Manager records all license requests and releases in this file. Usage reports can be generated using lsusage.

Element | Description
--- | ---
Server-LFE | Customer-defined log file encryption level as specified by the License Manager -lfe option. See Encrypting License Manager Log File Entries.
License-LFE | Vendor-defined log file encryption level. If this is non-zero, it overrides the Server-LFE.
Date | The date and time at which the usage log entry is made in the format: Day-of-week Month Date Time (hh:mm:ss) Year
Time-stamp | The time stamp at which the usage log entry is made.
Feature | Product feature name.
Ver | Product version name.
Trans | The transaction types are categorized and described below: Explicit Entries: 0 - A license is issued. 1 - A license is denied. 2 - The License Manager has released the issued key for which no update was received from client application. 3 - A queued key is issued and the client is placed in a queue. When the license would be available (after other clients release any token), this client may get that license. 4 - The queuing request failed. 5 - The queuing request succeeded, however, instead of obtaining a queued key the client receives the normal key and is not placed in the queue. 6 - A queued license is converted to an actual license. This happens when the client obtains the license that was released by some other client (and a queued client may call the VLSgetQueuedClient API to get the key). Thereafter, the client is removed from the queue. 7 - A queued license key that was issued earlier is released as it could not be converted into an actual license key (non-queued key) after a certain time period. 8 - A commuter license is checked out. 9 - A commuter license is checked in. Implicit Entries: 10 - Implicit license release entry when the License Manager performs cleanup of in use keys before shutdown. 11 - Implicit license release entry when the License Manager reclaims tokens after the key lifetime period has expired. 12 - Implicit license release entry when any of the following transactions takes place: License A is released at midnight when license switches to License B. Or, the license is released after actual revocation takes place for a deferred revocation case. Or, License A is released when License B is dynamically added. 13 - Implicit license release entry when the usage log file is changed under any of the following scenarios: When the backup usage log file is created (in case of overflow), a license release entry in the backup log file. When the log file is changed by calling the VLSchangeUsageLogFileName API, a license release entry in the previous log file. 14 - Implicit license request entry under the scenarios when update calls are converted into request. For example: When clients are running and the heartbeat message is sent after the License Manager restart When heartbeat messages are sent after the key lifetime expiration 15 - Implicit license request entry under any of the following scenarios: When the backup usage log file is created (in case of overflow), a license request entry in the new log file. When the log file is changed by calling the VLSchangeUsageLogFileName API, a license request entry in the new log file. 16 - Implicit release entries in the usage log file of the follower server, when the original leader comes back after going down (in the case of redundant License Manager setup).
Numkeys | The number of licenses in use after the current request/release. (Encrypted if encryption level is set to 3 or 4.)
Keylife | For how long (in seconds) the license was in use. Only applicable in a license release entry.
User | The user name of the application associated with the entry. This element can be logged anonymously if the anonymous logging option is set.
Host | The host name of the application associated with the entry. This element can be logged anonymously if the anonymous logging option is set.
LSver | The version of the License Manager.
Currency | The number of licenses handled during the transaction. (Encrypted if encryption level is set to 3 or 4.)
Comment | The data passed in by the vendor's licensed application. This element can be logged anonymously if the License Manager anonymous logging option is set and vendor has allowed anonymization of comments in the licensed application. The comment can be fully or partially anonymized depending on the vendor's implementation.

The information is recorded in the log file one entry per line in the following format. A typical entry might appear as:

    # Startup Sentinel RMS License Manager v8.5.3 Tue Jul 31 12:59:12 2012  1343719752 MACHINE1 1 4292

    2 3 ODA= Tue Jul 31 13:00:20 2012  1343719820 f1 v1 0 1 0 jsmith MACHINE1 8.5.3 1 my_log_comment - - - - - 0 - - - MA== 918458 MTM0NDYzODI3OA==

    # Shutdown Sentinel RMS License Manager v8.5.3 Tue Jul 31 13:01:33 2012  1343719893 4292 Mg== 682513

If the License Manager is started with extended log option, an entry in the log file might appear as:

    # Startup Sentinel RMS License Manager v8.5.3 Mon Sep 10 15:35:06 2012  1347271506 MACHINE1 120 3836 v1.0

    2 3 ODA= Mon Sep 10 15:35:06 2012  1347271506 f1 v1  15 1 0 jsmith MACHINE1 8.5.3 1 my_log_comment - - - - - 0 - - - MA== 151321 MTM0NzQyMjgyNw==

    # Shutdown Sentinel RMS License Manager v8.5.3 Mon Sep 10 15:35:06 2012  1347271506  3836 Mg== 1992393

The table below describes the various fields of the first entry reading from left to right:

Fields in Plain Log | Fields in Extended Log | Description
--- | --- | ---
# Startup Sentinel RMS License Manager v8.5.3 Tue Jul 31 12:59:12 2012 1343719752 MACHINE1 1 4292 | # Startup Sentinel RMS License Manager v8.5.3 Mon Sep 10 15:35:06 2012 1347271506 MACHINE1 120 3836 v1.0 | License Manager's startup messages. The v1.0 value (at the end of the extended log startup message) in the extended log record represents the version of the extended usage log format. Here 1.0 corresponds to the RMS v8.5.3 Windows release, in which the extended log option is introduced. The timestamp in the startup message represents the time when usage logging has started in the file. Here 1 and 120 (appearing after the machine names ‘Machine1’) are the session IDs for each entry, respectively. This session ID represents each session in between the startup and the shutdown message. It reflects the continuity of the sessions between different License Manager restarts. Therefore, if the usage log file name is changed to another name (using the -l option) while re-starting the License Manager, it starts logging with a new (incremented) session ID in the new log file.
2 | 2 | (Server-LFE) Customer-defined log file encryption level. 2 is the default level for encrypting log file entries (see description below in the next section).
3 | 3 | (License-LFE) Vendor-defined log file encryption level. 3 means that vendor has allowed encryption of usage data. Transaction data will be readable other than license usage data can be displayed by lsusage. The log file encryption level 3 will override any level set by the customer.
Tue Jul 31 13:00:20 2012 | Mon Sep 10 15:35:06 2012 | (Date) Date and time at which the license transaction was made.
1343719820 | 1347271506 | (Time-stamp) Time-stamp of the transaction record. This timestamp represents the time of creation of the log entry.
f1 v1 | f1 v1 | (Feature/Ver) Feature name a and 2 version for the first license. 4 is both the feature name and version for the second license.
0 | 15 | (Trans) The transaction ID. 0 denotes that a license was granted. 15 denotes an implicit license request entry as per the scenario described in the transaction ID #15 above.
1 | 1 | (Numkeys) 1 token was in use after the request.
0 | 0 | (Keylife) Only applicable for a license release.
jsmith | jsmith | (User) The user requesting the license.
MACHINE1 | MACHINE1 | (Host) The host name of the computer on which the license request was made.
8.5.3 | 8.5.3 | (LSver) The License Manager version.
1 | 1 | (Currency) The number of license requested for that key. Only 1 license was handled in both the transactions.
my_log_comment | my_log_comment | The log comment specified by the vendor.
# Shutdown Sentinel RMS License Manager v8.5.3 Tue Jul 31 13:01:33 2012 1343719893 4292 Mg== 682513 | # Shutdown Sentinel RMS License Manager v8.5.3 Mon Sep 10 15:35:06 2012 1347271506 3836 Mg== 1992393 | License Manager's shutdown messages.

If the Sentinel RMS usage log file contains characters that are not 7-bit ASCII (for example, if a user name contains multi-byte characters such as Japanese Kanji characters), those characters will not be viewable when looking directly at the log file. However, if you use the lsusage -c option to create CSV-format output from the log file, you will be able to view the multi-byte characters if you view the CSV-format file with an appropriate text editor on an operating system that displays the multi-byte language. Also, when anonymous usage logging option is enabled, that multi byte user and host names will be logged anonymously.
You can also create Microsoft Access reports from the CSV-format file that can be viewed on a computer using the appropriate multi-byte operating system. (For information on creating reports from log file CSV-format output, see Creating License Manager Use Reports)

Managing the Size of the Usage Log File

Sentinel RMS writes records to the log file until it reaches its maximum size. If you don’t have much disk space, you can restrict the size of the log. The maximum number of usage log files created by the License Manager is 100 files and the default value for maximum size is 50,00000 bytes (approximately 4.76MB).

The default maximum size can be changed using the -z option in the LSERVOPTS environment variable or at command-line. Once the maximum size is reached, the contents of the current log file will be saved into a backup file unless the no-backup -x option has been used in the LSERVOPTS environment variable or at command line. If -x has been selected, the License Manager will simply stop logging when the maximum size is reached. For information on the License Manager -x and -z options and for more detail on how log file backups are created, see License Manager - Commonly Used Variables. Though it is best to use the -z option to specify the maximum size limit for the log file and to leave automatic backup of log file enabled. Under some cases, as a part of your payment arrangement with your vendor, your vendor may recommend you to not use the -x option to stop log file backups.

If disk space is not an issue, you may want to set the maximum size of your log file fairly high to minimize the number of backup files created. For a site with a 2 megabyte log file limit and no other License Manager options, LSERVOPTS would just be set to -z 2m.

### RECOMMENDATION:

Please note the following recommendation regarding the management and backup of the License Manager usage log files. Suppose you have set the maximum size as 2 MB. While creating logs, if the size reaches 2 MB, the License Manager starts adding suffix at the end of the usage file name as 00, 01.. till 99, Example: lserv.log.00, lserv.log.01, lserv.log.02...lserv.log.99. Once this limit reaches, the License Manager starts generating the same log file name series and overwrites the existing usage files. Example: the log file creation will begin from lserv.log.00.....lserv.log.99; after reaching lserv.log.99, the License Manager would again start logging from lserv.log.00—hence overwriting the previous lserv.log.00. In order to preserve the log files, write a script that should first backup the 1st 100 log files. Once the limit of 100 is reached, these log files (lserv.log.00 to lserv.log.99) should be backed to another location and must be deleted from the original location.

Encrypting Log File Entries

For security reasons, you may wish to encrypt part or all of a license transaction record in the License Manager log file. To set the encryption level, use the -lfe License Manager startup option, with any of the following levels:

Encryption Level | Description
--- | ---
1 | Allows no encryption. Transaction data will be logged for this license code with no encryption.
2 | No encryption, tags each record with checksum. Transaction data will be readable by the customer, but tampering with or deleting an entry can be detected if the appropriate usage utility (lsusage) is run on the log file.
3 | Encrypt usage only. Transaction data will be readable by the customer except for license usage data (which will be encrypted), but tampering with or deleting an entry can be detected if the appropriate usage utility (lsusage or vusage) is run on the log file.
4 | Encrypt entire record. All transaction data for the license code will be encrypted. Tampering with or deleting an entry will not be prevented, but can be detected if the appropriate usage utility (lsusage) is run on the log file.

The vendor can also set the encryption level in the license, between 1 to 4. The vendor's setting will always override any level specified by you (see the possible scenarios in the examples below). As a result, all entries for that license code will be encrypted to the level set by vendor, regardless of your encryption level settings. You may only set the encryption level of transaction records for license codes for which your vendor has allowed user-defined encryption.
Few examples of log encryption levels:

- Vendor = Not set, System administrator = 1-4, Conclusion = 1
- Vendor = 0, System administrator = Not set, Conclusion = 2
- Vendor = 0, System administrator = 1-4, Conclusion = 1-4 as set by the administrator
- Vendor = 1-4, System administrator = 1-4, Conclusion = As set by the vendor
- Vendor = 1-4 System administrator = Not set, Conclusion = As set by the vendor

To learn more about lsusage, we recommend you to read through lsusage - Display the Usage Log File.