.. _reportlog-format: ##################### Reportlog File Format ##################### The RLM servers create a reportlog in three formats, selectable by the License Administrator. The 3 formats are "std", "small", and "detailed". Note that prior to RLM v9.3 there was no "detailed" format on Windows; specifying "detailed" would produce a standard report output. Starting in RLM v9.3, the detailed report will be produced, but all fractional seconds fields will be 0. The formats differ only in the contents of the checkout and check-in records, as described below. Common to all formats are the classes of data logged, and the data for all except check-in and checkout records. The reportlog format has a version number in the start record. All data described applies to all versions of the reportlog, except where indicated. The data is: * authentication data * check-in * checkout * dequeue * dynamic reservation created/removed (added in RLM v12.2) * isv-specific data * license denial * license in use (added in RLM/reportlog v10.0) * log file start * log file end (can correspond to a switch to a new logfile) * meter transaction data (added in RLM v9.3) * periodic timestamps * queue * roam extend * server shutdown * server time jumped * server reread of license/option file * support for a product (feature) - one for each license pool at log file start time * temporary license creation/removal (added in v14.1 – **RLM Cloud servers only**) .. note:: In every reportlog entry which contains a username or a hostname, the field is presented without quotes. However, if the corresponding value is empty, a pair of double-quotes ("") will be placed in the reportlog where the username or hostname would be. A reportlog consists of the following data: * log file start records * one PRODUCT support line for each supported product * one license in use record for each currently-checked-out license * all license activity data, including checkouts, check-ins, AUTH records, etc. * one license in use record for each currently-checked-out license * optional SWITCH line * END line * final AUTH line The format of the data logged is described in the following sections. ------ ******************* Authentication data ******************* All formats: AUTH section *signature* This line specifies the authentication signature (*signature*) for the preceding data in the file. If any of the data since the last AUTH line is modified, the authentication value will no longer be correct. This would typically be used by an ISV if they are using the report log data for post-use billing. The ISV can run a utility in order to verify the authentication records in a report log. Report writers can (and should) ignore this line. BADAUTH (x errors, y sessions, z authentication sections) When rlmanon processes a reportlog with AUTH errors, it rewrites the file with all bad AUTH records, and places this line in each section. Prior to RLM v12.3, rlmanon simply stopped processing when a bad AUTH section was encountered. In v12.3, the entire report log will be processed, but all sections will have bad AUTH sections, allowing you to process the anonymized report log but not verify the integrity of the data in it. ------ ******** check-in ******** **"standard" format:** IN *why product version user host "isv_def" count cur_use cur_resuse server_handle* mm/dd hh:mm:ss **"detailed" format:** IN *why product version user host "isv_def" count cur_use cur_resuse server_handle* mm/dd hh:mm:ss.tenths_of_msec **"small" format:** IN *why count server_handle* hh:mm The *server_handle* parameter is a hex number. All other numbers are decimal. The *isv_def* field contains the value of the optional ISV-defined field. The *why* parameter is one of: .. list-table:: :header-rows: 1 * - *why* value - Reason * - 1 - "Normal" check-in by application * - 2 - Application exited, automatic check-in * - 3 - License removed by (rlmremove) utility * - 4 - License removed by server after timeout * - 5 - License hold/minimum checkout period expired * - 6 - Client requested license dequeue * - 7 - Portable hostid removed * - 8 - Failed host back up * - 9 - Server lost its transferred licenses * - 10 - Meter ran out of count during a periodic decrement * - 11 - Client failed to send heartbeat within “promise” interval. * - 12 - Temporary License expired (**RLM Cloud only**) * - 13 - Temporary license returned (**RLM Cloud only**) .. note:: *why* value 12 is new in RLM v14.1, on RLM Cloud only. The *cur_use* and *cur_resuse* fields indicate the current number of free licenses in use and reservations in use after this check-in. The *ver* parameter will be the version requested, not the version of the license which satisfied the request. To find the version of the license that satisfied the request, check the version field in the matching checkout request referenced by “server_handle”. .. note:: On Windows, *tenths_of_msec* will always be 0. ------ ******** checkout ******** **"standard" format:** OUT product version pool# user host "isv_def" count cur_use cur_resuse server_handle share_handle process_id "project" "requested product" "requested version" mm/dd hh:mm:ss **"detailed" format:** OUT *product version pool# user host "isv_def" count cur_use cur_resuse server_handle share_handle* *process_id "project" "requested product" "requested version"* mm/dd hh:mm:ss.tenths_of_msec *"client_machine_os_info" "application argv0"* roam_days roam_handle client-ip-address **"small" format:** OUT *product version user host "isv_def" count server_handle share_handle* hh:mm .. note:: The *project* field will contain the contents, if any, of the RLM_PROJECT environment variable of the application that checked out the license. This project name has a maximum of 32 characters. The *isv_def* field contains the value of the optional ISV-defined field. The *cur_use* and *cur_resuse* fields indicate the current number of free licenses in use and reservations in use after this checkout. The *server_handle, share_handle,* and *process_id* parameters are hex numbers. All other numbers are decimal. The *share_handle* field contains the value of the handle of a shared license. .. note:: The *share_handle* is the handle of the first license that was checked out in this group of shared licenses. It is possible (and perhaps even likely) that the handle associated with the group will change if the first license is checked in before other shared licenses are checked in. In this case, new checkouts will specify a *share_handle* of a different license in the group of shared licenses. The *requested product* and *requested version* fields represent the requested product and version in the application's checkout call. In the case of a token-based license, the product (or products) actually checked out will differ, and *requested product* and *requested version* provide what the application actually requested. The *process_id* field is the PID of the process requesting the license. The PID will be -1 (ffffffff), when the server logs a roaming “checkout” at startup time. The *client_machine_os_info* field is a combination of the platform type and OS version running on the client machine. This string is a maximum of 41 bytes long, and is in the format: *"rlm_platform_name os_version"* For example: "x64_w42 5.1" - a windows system running Windows XP. The *application argv0* field is the argv[0] of the product requesting the license. The *roam_days* field is the (hex) number of days for which the license will roam PLUS 1. This will appear on the initial checkout of a roaming license as well as on the subsequent checkout when the server checks out an already-roaming license. Beginning in rlm v11.1, roam_days is one greater than it had been in prior versions, so a value of 2 means a license roaming for 1 day (i.e., RLM_ROAM set to 1), meaning until the end of tomorrow. On Windows, *tenths_of_msec* will always be 0. The *roam_handle* field is the server handle (in hex) of a roaming license re-checkout. This field will be non-zero when the server checks out an already-roaming license (as it does when starting up). The client-ip-address is new in reportlog v14.1. It is of the form a.b.c.d If the client's IP address is unknown, it will appear as 0.0.0.0. ------ ******* dequeue ******* **"standard" format:** DEQUE *why product version user host "isv_def" count server_handle* mm/dd hh:mm:ss **"detailed" format:** DEQUE *why product version user host "isv_def" count server_handle* mm/dd hh:mm:ss.tenths_of_msec **"small" format:** DEQUE *why count server_handle* hh:mm The *server_handle* parameter is a hex number. All other numbers are decimal. On Windows, *tenths_of_msec* will always be 0. .. note:: The dequeue record is identical to the check-in record except the keyword is "DEQUE" rather than "IN". A dequeue record is generated on all other servers when a client is granted a license on one server. ------ ******************* dynamic reservation ******************* **All formats:** DYNRES [create | remove] *user host license-pool count “string”* mm/dd hh:mm:ss All numbers are decimal. *string* is the identifier used to create the reservation. The DYNRES record is new in v12.2. ------ ***************** isv-specific data ***************** **All formats:** log mm/dd hh:mm:ss isv-specific-data-here Individual ISVs can log unformatted data to the report log. This data appears in a "log" record. ------ ************** license denial ************** **"standard" and "small" formats:** DENY *product version user host "isv_def" count why last_attempt pid* mm/dd hh:mm **"detailed" format:** DENY *product version user host "isv_def" count why last_attempt pid* mm/dd hh:mm:ss.tenths_of_msec The *why* parameter is an RLM_LICENSE error status return (RLM_EL_xxxx) as documented in :ref:`isv-status-values`. The *last_attempt* parameter is 0 if the application will attempt another checkout, or non-zero if this is the last attempt it will make to check the license out. Thus, denials with *last_attempt* set to 0 are not "true" denials of the license to the application, they are simply denials of the license at this license server. A report writer should only report application license denials when *last_attempt* is set to a non-zero value. The *pid* field is the process's PID, in hex. The *pid* field is new in reportlog v11.3. The *isv_def* field contains the value of the optional ISV-defined field. On Windows, *tenths_of_msec* will always be 0. ------ ************** license in use ************** **All formats:** INUSE *product version pool# user host "isv_def" count server_handle share_handle process_id* mm/dd hh:mm:ss The *isv_def* field contains the value of the optional ISV-defined field. The *server_handle* and *process_id* parameters are hex numbers. All other numbers are decimal. The *process_id* field is the PID of the process requesting the license. License in use records are new in RLM v10.0 and appear both at the beginning and the end of the report log if any licenses are in use at that time. The *share_handle* field contains the value of the handle of a shared license. This field is new in reportlog v12.2. ------ ************** log file start ************** **All formats:** * SWITCH from old-reportlog-name (new in v14.0, not authenticated) * RLM Report Log Format *d*, version *x.y authentication flag* * REPROCESSED with rlmanon vx.y * ISV: , RLM version a.b BLc * * START *hostname* mm/dd/yyyy hh:mm * TIMEZONE minutes-west-of-UTC daylight rules # readable version of data * LICENSE FILE *filename* The *d* in the first line is the format: 0 for "std", 1 for "small", and 2 for "detailed" *x.y* is the reportlog version. Reportlog v1.0 corresponds to RLM version 1.0. reportlog v1.1 corresponds to RLM v1.1. The *authentication flag* is either blank (no authentication) or the string ", **authenticated**". All report logs are authenticated. The second line will be present if the *rlmanon* utility was used to anonymize the reportlog data. The version of rlmanon corresponds to the RLM version. *rlmanon* first appeared in RLM v4.0, however while this was added in RLM v4.0, this line can appear in any reportlog version, since rlmanon can process any version of reportlog. Note that this line can be repeated if multiple runs of rlmanon were made on the same log file. The third line displays the ISV name, and the RLM software version of the ISV server (a.b BLc, BL means "Build"). In general, numeric data is in decimal format. The 3 exceptions to this are *server_handle*, *share_handle*, and *process_id* parameters which are always hex numbers. The TIMEZONE line is new in RLM v12.3 This represents the server's timezone data: the first number is the minutes west of UTC time; the second number indicates whether daylight savings rules ever apply in this timezone. The data after the # is a human-readable version of the timezone information. There will be one LICENSE FILE line(s) for each license file which the server is processing. Note that the “SWITCH from” line is not included in the report authentication. ------ ************ log file end ************ **All formats:** SWITCH to *filename* (if an rlmswitch was done) END mm/dd/yyyy hh:mm ------ *************** meter decrement *************** **All formats:** METER_DEC *license_handle meter_counter amount_decremented* mm/dd hh:mm:ss[.tenths_of_msec] A *meter decrement* record will immediately follow a checkout record for a metered license. In addition, an additional *meter decrement* record will appear periodically when the meter is decremented for this product. The *license handle* is a hex value; both *meter counter* and *amount* *decremented* are decimal. The format is the same for all reportlog types, with the exception of the time - in the detailed reportlog format, tenths of milliseconds are added. ------ ****************** periodic timestamp ****************** **All formats:** mm/dd/yyyy hh:mm Timestamps are performed by the ISV servers every night just after midnight. Timestamps are added to the log file every 30 minutes. ------ ***** queue ***** **"standard" format:** QUE *product version user host "isv_def" count server_handle "project" "requested product"* *"requested version" mm/dd hh:mm:ss* **"detailed" format:** QUE *product version user host "isv_def" count server_handle "project" "requested product"* *"requested version"* mm/dd hh:mm:ss.tenths_of_msec **"small" format:** QUE *product version user host "isv_def" count server_handle* hh:mm The *server_handle* parameter is a hex number. All other numbers are decimal. The *project* field will contain the contents, if any, of the *RLM_PROJECT* environment variable of the application that checked out the license. This project name has a maximum of 32 characters. The *isv_def* field contains the value of the optional ISV-defined field. On Windows, *tenths_of_msec* will always be 0. If the queued license becomes available, a checkout record will be logged with the same handle. If the client abandons the checkout, however, no other records will be logged. ------ *********** roam extend *********** The roam extend record has only a single format, for all 3 reportlog formats: ROAM_EXTEND *product version pool# user host "isv_def" #days_extended server_handle process_id* mm/dd hh:mm:ss The *isv_def* field contains the value of the optional ISV-defined field. The *#days_extended* parameter is the # of days which the roam was extended. So, if a license was originally roaming for 6 days, then extended to 10 days, this parameter will be 4, independent of which day the extension was done. The *server_handle* and *process_id* parameters are hex numbers. All other numbers are decimal. The *process_id* field is the PID of the process requesting the license. Note that if the pid is -1 (ffffffff), this means that the roam was extended by the RLM web interface when the client was no longer connected to the server. Roam extend records are new in RLM v10.0. ------ *************** server shutdown *************** **All formats:** SHUTDOWN *user host* mm/dd hh:mm:ss ------ **************** server time jump **************** **All formats:** TIMEJUMP [+ | -]minutes mm/dd hh:mm:ss The ISV server logs this when the time changes by more than 15 minutes on subsequent passes thru its main loop. The main loop executes whenever there is a message to process, but not less frequently than once/minute. ------ ************************************ server reread of license/option file ************************************ **All formats:** REREAD *user host* mm/dd hh:mm:ss ------ ********************* support for a product ********************* There will be one record per license pool for each product served. These lines come immediately after a START or REREAD record. Note that there is not a one-to-one correspondence between the **support** records and LICENSE lines in the license file. **All formats:** PRODUCT *name version pool# count #reservations soft_limit "hostid" "contract" "customer" "issuer"* *"line_item" "options" share max_share type named_user_count meter_type meter_counter* *meter_initial_decrement meter_period meter_period_decrement* * *count* is the number of free licenses (i.e., non-reserved licenses) * *#reservations* is the number of reserved licenses (not generally available). * *pool#* is an internal server pool identifier. This number appears in checkout records in some formats. * *line_item* is the contents of the product's _line_item field, used for mapping license product names to actual purchased products. * *meter_type* is always 0 in RLM v9.3. Other values may be defined in later versions. A non-zero value in meter_counter indicates a metered license. * *meter_counter* is the counter which is used for this product. * *meter_initial_decrement* is the amount to be decremented from the meter when a license is checked out. * *meter_period* is the number of minutes before an additional decrement is performed (0 means no periodic decrements) * *meter_period_dec* is the amount to be decremented from the meter each meter_period minutes. ------ ********************************** Temporary license creation/removal ********************************** **All formats:** TEMP [create | remove | restart | expired] *product version license-pool user host “isv_def”* *expdate exptime server_handle* mm/dd hh:mm:ss The *server_handle* is a hex number. All other parameters are strings. * *server_handle* is the handle of the associated checkout. Temporary licenses are created after a successful checkout. * *expdate* is the expiration date (local time on the server) of the temporary license. * *exptime* is the expiration time (local time on the license server) of the temporary license. On a server restart, there will be a *TEMP* restart record with (possibly) a different license-pool value if the server's licenses have been modified before the restart. This is not a new temporary license, it is essentially a checkout of the same temporary license which was created earlier. When a temporary license is refreshed, a new *TEMP create* record will be logged, with the same time as the original *TEMP create* record (or INUSE record, if the server preformed a reread). This new record does not represent an additional checkout, however the *expdate* and *exptime* fields will be updated. For example, a server had a temporary license and performed a reread: Before the reread, a temp license was created that expired at 15:55: .. code-block:: text TEMP create test2 2.0 2 matt zippy "" 2020-05-19 15:55 41 05/19 15:45:43 After the reread, the in-use temp license is logged, then later refreshed to 15:58: .. code-block:: text INUSE test2 2.0 2 matt zippy "" 1 41 41 4a07 05/19 15:45:43 TEMP create test2 2.0 2 matt zippy "" 2020-05-19 15:58 41 05/19 15:45:43 The TEMP record is new in v14.1 and appears on RLM Cloud servers only. ------ ******************************** Reportlog version change history ******************************** .. list-table:: :header-rows: 1 * - V14.1 reportlog changes * - The OUT record in detailed format now includes the client's IP address * - The TEMP_CREATED record is new (RLM Cloud servers only) * - The check-in why values 12 and 13 are new (RLM Cloud servers only) .. list-table:: :header-rows: 1 * - V14.0 reportlog changes * - SWITCH from old-reportlog added to header .. list-table:: :header-rows: 1 * - V12.3 reportlog changes * - The TIMEZONE record is added to the header information. * - The BADAUTH record is added by rlmanon when processing logs with AUTH errors. .. list-table:: :header-rows: 1 * - V12.2 reportlog changes * - The share handle is added to INUSE records * - The DYNRES record is added. .. list-table:: :header-rows: 1 * - V12.1 reportlog changes * - The Server Time Jump (TIMEJUMP) record is added. .. list-table:: :header-rows: 1 * - V11.3 reportlog changes * - The DENY records now include the process's PID. .. list-table:: :header-rows: 1 * - V11.1 reportlog changes * - roam_days is now one greater than prior versions (and one greater than the value of * - RLM_ROAM). roam_days == 2 now means roaming until midnight tomorrow. .. list-table:: :header-rows: 1 * - v10.0 reportlog changes * - All logfiles will now log all licenses currently in use both at the start and the end of the reportlog, with the new "INUSE" record. * - The ROAM_EXTEND record is added. .. list-table:: :header-rows: 1 * - v9.3 reportlog changes * - Windows systems will now produce a detailed reportlog, however, all fractional seconds fields will be 0. * - meter decrement records added. * - metering parameters added to the support record * - The logfile is timestamped every 30 minutes .. list-table:: :header-rows: 1 * - v9.0 reportlog changes * - roam days and roam handle added to the OUT record for detailed format. * - All fields which have a username or a hostname will now contain only an empty pair of double-quotes ("") if the corresponding value is empty. This only happens when rlm cannot determine the username or hostname on the system using the standard system calls. .. list-table:: :header-rows: 1 * - v8.0 reportlog changes * - client machine OS version added to the OUT record for detailed format. * - application argv[0] added to the OUT record for detailed format. .. list-table:: :header-rows: 1 * - v5.0 reportlog changes * - requested product and requested version added to QUE record for std and detailed formats. * - requested product and requested version will always be empty strings in OUT records that result from a de-queueing of a previously queued request. * - options, share, max_share, type, and named_user_count added to PRODUCT support record * - Portable hostid removed - status 7 - added to checkin reasons. .. list-table:: :header-rows: 1 * - v4.0 reportlog changes * - REPROCESSED line added for rlmanon. Note that this line can appear in any version reportlog, since rlmanon can process all reportlog versions. Report writers can ignore this line, it is in the file for informational purposes only. * - "detailed" format added to DENIAL records to add seconds and fractional seconds. * - REREAD END records were not generated prior to v4.0. This record is removed. * - New denial status -45 (RLM_EL_NOT_NAMED_USER) added * - All report logs are authenticated. .. list-table:: :header-rows: 1 * - v3.0 reportlog changes * - NOTE: the v3.0 reportlog is incorrectly logged as v2.0 in the "RLM Report Log" line. The version in the ISV line will correctly indicate that it is a v3.0 logfile. * - line_item added to PRODUCT records * - ", authenticated" added to the end of the 'RLM Report Log' (first) record if this reportlog is authenticated * - AUTH records added (for authenticated reportlogs) .. list-table:: :header-rows: 1 * - v2.0 reportlog changes * - LICENSE FILE line added in header section * - isv-specific data ("log" records) added * - cur_use and cur_resuse fields added to IN records (standard and detailed formats) * - process_id, requested_product, and requested_version added to OUT records (standard and detailed formats) * - hostid and pool# added to PRODUCT records