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.

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. Refer to Encrypting License Manager Log File Entries.

License-LFE

Vendor defined log file encryption level. If this is non-zero, it overrides the Server-LFE.
Reserved This field is meant for internal use.

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 transaction took place.

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 licensed application released the license token (when the release API is called).

>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.

>17 - Explicit request entry of a shared license token

>18 - Explicit release entry of a shared license token

>19 - Active session is terminated and license token is released

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.

When the License Manager is not started with the extended log option, LM_SERVER appears in the user name.

When the License Manager is started with the extended log option, the actual user name appears in the user name field of each dummy record.

If clients are connected to the License Manager when the backup file is created, dummy records are created only for in-use license tokens in the backup file (not for the tokens whose key lifetime has expired). Correspondingly, their dummy records are created in the new file. The dummy entries are differentiated from rest of the entries using specific transaction IDs (13 and 15).

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 software vendor's licensed application.

This element can be logged anonymously if both the following conditions are met:

>The software vendor has allowed anonymization of comments in the licensed application.

>The system administrator has set the License Manager anonymous logging option.

The comment can be fully or partially anonymized depending on the software vendor's implementation.

When the user does not set usage log data, the comment field contains a hyphen (-).
Queue key ID

When license queuing is enabled, this value denotes the queue key ID—a unique identifier of the queued key. Otherwise, it contains a hyphen as below.

Absolute position When license queuing is enabled, this value denotes the position of the queued client in the queue. Otherwise, it contains a hyphen as shown below.
Group position When the system administrator has created a group reservation file and license queuing is enabled, this value denotes the position of the queued client in its group. Otherwise, it contains a hyphen as shown below.
Group name When the system administrator has created a group reservation file and the queued key is granted from the reserved group, the group name (as specified in reservation file) will appear. Otherwise, it contains a hyphen as below.
Queue length When license queuing is enabled, this value denotes the queue length—the total number of clients existing in the queue at that particular time. Otherwise, it contains a hyphen as below.
Capacity Flag

0 - When capacity licensing is not used by the software vendor.

1 - When capacity licensing is used by the software vendor.
License capacity When capacity licensing is used by the software vendor, this field contains license capacity. Otherwise, it contains a hyphen as below.
Team capacity When capacity licensing is used by the software vendor, this field contains team capacity. Otherwise, it contains a hyphen as below.
User capacity When capacity licensing is used by the software vendor, this field contains user capacity. Otherwise, it contains a hyphen as below.
Client ID

A 16-byte value that uniquely identifies each client request and is logged using the following transactions types (defined above): 0, 2, 10, 11, 12, 13, 14, 15, 16, 17, and 18. Using the client ID, each request log entry can be mapped with the corresponding release log entry.

Also note the following behavior:

>The client ID is present in usage logs only when the extended log option is used.

>The client ID will not be maintained for commuter and queued clients. In such cases, a hyphen will be logged instead of the client ID.

>For clients prior to Sentinel RMS v8.5.5, the client ID in the case of transaction ID 14 will not be maintained, instead a fresh client ID will be assigned.
Record number Encrypted record number.
Readable checksum Readable checksum of the record.
Encrypted checksum Encrypted cumulative checksum.

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.6.0.0036 Mon Aug 25 15:36:23 2014  1408961183 Machine1 197 1708
2 1 ODA= Mon Aug 25 15:36:27 2014  1408961187 f1 v1 0 1 0 JSmith Machine1 8.6.0.0036 1 request_comment - - - - - 0 - - - MA== 3724690 MTQxMjY4NTg3Nw==
# Shutdown Sentinel RMS License Manager v8.6.0.0036 Mon Aug 25 15:36:43 2014  1408961203 Machine1 1708 Mg== 532318

 

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

# # Startup Sentinel RMS License Manager v8.6.0.0036 Mon Aug 25 15:22:34 2014  1408960354 Machine1  25 5976 v2.0 437875
2 1 ODA= Mon Aug 25 15:27:55 2014  1408960675 f1 v1 15 1 0 JSmith Machine1 8.6.0.0036 1 request_comment - - - - - 0 - - - 3fd76b52b2d23b445e5a1e253068b3f1 MA== 295147 NzMzMDI0
Shutdown Sentinel RMS License Manager v8.6.0.0036 Mon Aug 25 15:28:48 2014  1408960728 Machine1 5976 Ng== 642326 OTc1MjUx

The following table 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.6.0.0036 Mon Aug 25 15:36:23 2014 1408961183 Machine1 197 1708

# Startup Sentinel RMS License Manager v8.6.0.0036 Mon Aug 25 15:22:34 2014 1408960354 Machine1 25 5976 v2.0 437875

License Manager's startup messages.

>The v2.0 value (at the end of the extended log startup message) represents the version of the extended usage log format.

>The 437875 value (last value in the extended log startup message) represents the checksum of the startup entry.

>The timestamp in the startup message represents the time when usage logging has started in the file.

>Here 197 and 25are the session IDs for each startup entry. This session ID represents a complete session in between the consecutive startup and the shutdown message. It reflects the continuity of the sessions for usage logs and is incremented when the License Manager restarts or when a usage log backup is created. However, the maximum limit of the session ID is 4,294,967,295 and beyond this it will be reset to 0.

2

 2

(Server-LFE) Customer-defined log file encryption level.

2 is the default level for encrypting log file entries.

1

 1

(License-LFE) Vendor-defined log file encryption level.

NOTE   The log file encryption level set by the software vendor will override any level set by the system administrator.
ODA= ODA= This field is meant for internal use only.

Mon Aug 25 15:36:27 2014

 Mon Aug 25 15:27:55 2014

(Date and Time). 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

1408961187

 1408960675 (Timestamp). The time stamp at which the transaction took place

f1 v1

 f1 v1

(Feature/Version). Feature name f1 and version v1

0

 15

(Trans). Implicit license request entry

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.6.0.0036

 8.6.0.0036

(LSver). The License Manager version.

1

 1

(Currency). The number of license requested for that key. Only one license was handled in both the transactions.
request_comment request_comment The log comment specified by the software vendor.
- -

(The hyphen shown in the example record).

When license queuing is enabled, this value denotes the queue key ID. Otherwise, it contains a hyphen as here.

- - When license queuing is enabled, this value denotes the absolute position. Otherwise, it contains a hyphen as here.
- - When license queuing is enabled, this value denotes the group position. Otherwise, it contains a hyphen as here.
- - When license queuing is enabled, this value denotes the group name. Otherwise, it contains a hyphen as here.
- - When license queuing is enabled, this value denotes the queue length. Otherwise, it contains a hyphen as here.
0 0

0 - When capacity licensing is not used by the software vendor.

1 - When capacity licensing is used by the software vendor.
- - When capacity licensing is used by the software vendor, this field contains license capacity. Else, it contains a hyphen as here.
- - When capacity licensing is used by the software vendor, this field contains team capacity. Else, it contains a hyphen as here.
- - When capacity licensing is used by the software vendor, this field contains user capacity. Else, it contains a hyphen as here.
- 3fd76b52b2d23b445e5a1e253068b3f1 The client ID for the request. The same client ID will appear in the case of the corresponding token release entry.
MA== MA== Encrypted record number
3724690 295147 Readable checksum of the record
MTQxMjY4NTg3Nw== NzMzMDI0 Encrypted cumulative checksum
# Shutdown Sentinel RMS License Manager v8.6.0.0036 Mon Aug 25 15:36:43 2014 1408961203 Machine1 1708 Mg== 532318 # Shutdown Sentinel RMS License Manager v8.6.0.0036 Mon Aug 25 15:28:48 2014 1408960728 Machine1 5976 Ng== 642326 OTc1MjUx

License Manager's shutdown messages.

 

NOTE   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.

Sentinel RMS License Manager writes records into the log file until it reaches its maximum size. If you do not have enough disk space, you can restrict the size of the log. 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 the 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 explicitly used. If -x has been selected, the License Manager will simply stop logging when the maximum size is reached.

Although, 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 software vendor, your software vendor may recommend you to avoid using the -x option to stop log file backups.

By default, when the automatic backup of log file is left enabled, the contents of the log file are moved into a new file in the case of overflow. The new file has the same name as the original log file but has few 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 allowed are:

>10000 for the usage log files. So, for example, if the log file name is lserv.log then the first usage log files will be lserv.log.00, up to lserv.log.9999.

>10000 for the trace log files. So, for example, if the log file name is trace.log then the first trace log files will be trace.log.00, up to trace.log.9999.

Once these limits are reached, the existing files will be overwritten sequentially, beginning from lserv.log.00. So, if the License Manager shuts down while it has overwritten some intermediate file numbers (for example, lserv.log.12) and is started again, then it will start overwriting from lserv.log.00 onwards and not lserv.log.13.

If disk space is not an issue, you can go ahead and set the default maximum size of your log file fairly high to minimize the number of backup files created. For example, if you want to have 2 megabyte as the log file limit and no other License Manager options; LSERVOPTS would just be set to -z 2m.

Recommendation

Although, the number of backup log files allowed seem sufficient to accommodate log data on a given day, still it is recommended that you devise a routine procedure to move the backup files to another location and avoid overwriting them. This can particularly be helpful for usage log files where License Manager performance may degrade if many backup files are existing.

Example: Let us assume that you have set the maximum size of the log file as 2 MB. While creating trace logs, if the size reaches 2 MB, the License Manager starts adding suffix at the end of the trace file name as 00, 01.. till 9999, Example: lserv.log.00, lserv.log.01, lserv.log.02...lserv.log.9999. Once this limit is reached, the License Manager starts generating the same log file name series and overwrites the existing trace files.

Example: The log file creation will begin from lserv.log.00.....lserv.log.9999; after reaching lserv.log.9999, 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 10000 log files. Once the limit of 10000 is reached, these log files (lserv.log.00 to lserv.log.9999) should be backed up to another location and deleted from the original location. 

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 software vendor can also set the encryption level in the license, between 1 to 4. The software vendor's setting will always override any level specified by you (refer to the possible scenarios in the examples mentioned below). As a result, all entries for that license code will be encrypted to the level set by software vendor, regardless of your encryption level settings. You may only set the encryption level of transaction records for license codes for which your software vendor has allowed user-defined encryption.

Some examples of log encryption levels are as follows:

>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 software vendor

>Vendor = 1-4 System administrator = Not set, Conclusion = As set by the software vendor

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