Prism Logging and Log Files

PDF

Prism includes several log files that can assist with monitoring and troubleshooting.
This topic has information about:

• How Logging Works
• Log Levels
• Viewing log files
• PrismLogging.ini settings
• Using alternate log directory
• Plugin-specific log files
• Using API to filter by log file type, log entry type, date range, or files with errors
• Developer info (Log method call syntax)

How Logging Works
All log settings are stored in PrismLogging.ini. This file is created in the ProgramData\RetailPro\Server\Conf folder during Prism installation, version 1.14.7 or later. The PrismLogging.ini file stores two levels of settings: global and service-specific.
When first installed, PrismLogging.ini will have only a [global] section with default log settings for all log keys. The [global] section settings are used by all services and apps using the Logger unless a different setting has been entered in the PrismLogging.ini file for the service. The global values can be edited, or specific service settings can be added & edited, manually or by using Web TTK.
Updating global log settings with Prism Web TechToolkit
Global settings can be viewed and edited in Services tool in the "Prism Stack" section.
Changes to global settings only update the global settings and do not overwrite an existing setting for any service.  At this time there is no feature to set all services to the same log setting using a 'global update' process. The global setting will apply to any service or app that does not have the same setting specified in its section.
Changing a global setting to the same value as may be specified for a service will not remove the service's Key / Value pair as would a similar update to the service's setting. This bit of cleanup may be added in a future release.

To edit global log settings, in Tech Toolkit > Services, locate the Prism Stack and click the arrow to expand the service.
Click the Settings icon.

Make any needed changes to the log settings and then click the check mark button.

Updating Service-specific log settings with Prism Web TechToolkit
Updates to the settings for a service are made in the Services tool. The LOG settings are displayed grouped with the service's other INI settings, as they were in native Desktop TTK, even though the LOG settings are maintained not in the service's INI but in a separate PrismLogging.ini. This grouping provides consistency with past UI displays and for ease of use - rather than separating LOG settings in a separate web form.
When a change is made to a service's log setting, if that change is different than the existing global setting, Web TTK will create a section for the service in PrismLogging.ini if it does not exist and write the Key / Value pair to the section. The section name for an app or service in the PrismLogging.ini is the base file name of the binary that is using the Logger. So, if a log setting in the service's section differs from the global setting, the service will use the specific setting entered for the service.
If the change being made is the same as the existing global setting, the Key / Value pair in the service's section will be removed since the global value will automatically apply without a setting for the service. In general, PrismLogging.ini will only contain the global settings and services' exceptions to them when using Web TTK for updates. There are some instances where there could be some duplication of a service setting with the global value.
To update service-specific log settings:
In Tech Toolkit > Services, locate the desired service and click the arrow.
Click the Settings icon.

Make any needed changes to the log settings and then click the check mark button.

 
When a change is made to a service's log setting, if that change is different than the existing global setting, Web TTK will create a section for the service in PrismLogging.ini if it does not exist and write the Key / Value pair to the section.
Note: For PrismMQService, there will be entries for PrismMQ, producer, and consumer.

 Log Levels
The Log Level determines the level of detail captured by logs. Log levels range from 1 to 4, with 1 being the least amount of detail and 4 being the most detail. To change the logging level, edit the Prism Stack element in the Services area of Tech Toolkit.
The following logging levels are supported:

The following table lists the available log entry types and usage notes.

View Logs
The Prism Tech Toolkit includes a Logs tool that makes it easy to view log files.
Log in to the Tech Toolkit and click the Logs tab on the top menu.
A separate log-in is required for viewing logs. The default username/password is "loguser/loguser".
After successful login a list of recent logs is displayed.
Scroll the list to locate the desired log and then click on the hyperlink to display the log.
Note: You can copy the contents of the log to a text editor like Notepad++ if you want to search text within the log.
After viewing a log, click the arrow button to return to the log list.
Sample list of Prism logs in Technician's Toolkit:
.

Log Folder Authorization - Creating Users and Passwords
When opening the Web TTK Log Files tool, the user is prompted to enter valid credentials created using the Apache password tool. After installing 1.14.7 release (or later), at least one password must be created to access the Logs folder from Web TTK. New users and passwords are created or updated using the Apache password tool, htpasswd. See the following link for more information:
https://httpd.apache.org/docs/2.4/programs/htpasswd.html

Note: You can copy the contents of the log to a text editor like Notepad++ if you want to search text within the log.
After viewing a log, click the blue arrow button to return to the log list.
Prism Log File List
The following table lists Prism log files and the location to which the files are saved:

PrismLogging.ini
Configuration settings for log files are stored in the PrismLogging.ini file. The PrismLogging.ini file is in the …\ProgramData\RetailPro\Server\Conf folder. PrismLogging.ini has a [global] section and can have sections for each Prism service. The settings defined in the [global] section apply to all services. The following table lists the available settings for PrismLogging.ini and the default settings:

Sample PrismLogging.ini with Comments
[Global]
LOGLEVEL=2
RetainXLogs=9
FORCELOGINFO=false
ForceLogInfo, when true, means log calls with ltInfo LogEntryType will be logged regardless of the log level.
DebugStackTraceActive=False
BUFFERSIZE=100
BufferSize refers to how many log lines to hold in memory before "flushing" to disk.
MAXENTRYLENGTH=100000
100000 here equates to 100k size limit for the 'message'. Anything beyond 100k slows the logger exponentially. But message 100k or less, minimal impact.
MAXLINESPERLOG=100000
MaxLinesPerLog applies only if log file is segmented, which is the default. "Segmented" means a new log file gets created if MaxLinesPerLog has been reached or the date changes. Otherwise same log file is written to.
LOGPAYLOADS=TRUE
Default is True. Any service that consumes HTTP requests will log request and response payloads when this setting is true. Requires llVerbose or llDebug loglevel.
  rem As implemented, the addition of this setting only affects PrismCommon, PrismBackOffice, PrismTechToolKit, PrismScheduling and DRS. POSV1Service already
implements logging of payloads which cannot be turned off. This can be turned off when/if not needed for individual services. For some services such as PrismScheduling and PrismTechToolKit logging payloads has less value than PrismBackoffice or Common.
LOGTIMING=false
LogTiming, when true will record CPU time with every log write. Requires llVerbose log level
LOGFILEDIR=
The LogFileDir provides the ability to have the logger write to an alternate log folder.
Normally the LOGFILEDIR key should be blank which means the default server\logs folder will be used. The intent is that this should only be updated by TTK webclient. However manual edit is possible and will work. Logging to the new folder will take effect when the service or app is restarted.
If the alternate logs folder does not exist when entered, the api will create it. The TTK api validates it can be written to and raises exception to the webclient's PUT request if not writable. Other causes for rejection: root directories and the RetailPro AppDatata folder which contains the conf, logs, webclient folders. At this time, the alternate path must be the full path with no references to Environment variables. If the change is made in the INI manually, if the api can't create or can't write or is otherwise invalid, the default Prism Logs folder will be used. Setting this key in a service's section is ignored.

Alternate Logs Folder
By default, logs for Prism services are written to C:\ProgramData\RetailPro\Server\Logs. You can change the folder, if necessary. The default login credentials (loginuser/loginuser) will still work if you change the logs folder.
To change the folder to which log files are written:
Expand the Prism Stack element and then click the Settings icon.
Enter the path to the folder where log files should be saved.
Click the blue check mark button to save the changes.
Restart Apache.
Sample Prism Stack element with Alternate Logs folder defined:

Apply Log Folder Change during Maintenance Window
If you specify an Alternate Log Folder, do it during non-business hours. Restart all Prism services or reboot the machine after executing the change. The other Prism services will only recognize the log folder change when they are restarted. The log folder change affects Prism services' logging, including the Web Client, but not RabbitMQ or the DB services. So the latter do not need to be restarted.

Plugin-specific Log Settings
Users can set logging levels for individual plugins via the Prism Proxy "right-click" configuration settings. Previously, it was not possible to change log levels for individual plugins that might need a different level of logging detail.
The Configuration Settings screen has separate tabs for the Prism plugins that are installed with Proxy. To access the settings, start the Proxy, then right-click on the proxy icon and select Configure

Select the tab for the appropriate plugin and update the Log Level and any other log settings as needed. Settings configured for an individual plugin will override the default logging settings defined in PrismLogging.ini, as follows:
If no setting is made for a plugin, the plugin's log settings default to the settings made for Proxy.
The Proxy log settings themselves, as displayed in this UI, default to the "Global" settings in PrismLogging.ini until they are manually changed to different settings.

API
This section has information about:
Logfile virtual resource
Using Prism API Explorer to make API requests
Notes about API updates of PrismLogging.ini
Filtering log files by date range, log entry type, files with errors, as well as applying multiple filters and opening a specific log file
logfile virtual resource
API calls related to logging use the logfile virtual resource.
Example:
http:///api/techtoolkit/logfile
Returns a listing of all Prism-related log files. Sample info is shown below.
"logfilename" : "PrismPOSV1AsService_190905_120515615.log",
"logfiletype" : "PrismPOSV1",
"logfiledate" : "2019-09-05T17:41:05.582-07:00",
"logfilesize" : "20744",
"errorcount" : "0",
"logfilepath" : "C:\\ProgramData\\RetailPro\\Server\\Logs\\PrismPOSV1AsService_190905_120515615.log",
"logfileendpoint" : null

The logfile virtual resource has the following properties:
property LogFileName: Nullable read FLogFileName write FLogFileName;
property LogFileType: Nullable read FLogFileType write FLogFileType;
property LogFileDate: Nullable read FLogFileDate write FLogFileDate;
property LogFileSize: Nullable read FLogFileSize write FLogFileSize;
property ErrorCount: Nullable read FErrorCount write FErrorCount;
property LogFilePath: Nullable read FLogFilePath write FLogFilePath;
property LogFileEndpoint: Nullable read FLogFileEndpoint write FLogFileEndpoint;
The names can be changed. For example, a developer might prefer to remove the "Log" prefix as redundant.

Using Prism API Explorer to make API requests
You can use Prism's built-in API Explorer (or a tool like Postman) to make API calls that access the logfile virtual resource.
To access Prism API Explorer, launch Prism and append "/api-explorer" to the Prism hostname in the browser address bar. Log in if prompted.
Example: http://myhost.mydomain.com/api-explorer
On the left, under the heading "Services" is a set of folders that provide API access to different Prism services and resources.
Click techtoolkit > REST Resources > logfile.

Click the Raw Requests tab.
In the Raw Requests area, the UI has a set of drop-downs that make it easy to construct API requests. Select the desired REST request type (e.g. GET), area and resource.
In the Payload section, you can enter parameters for filtering log files by date range, log entry type, etc. (see the "Setting Filters" section).
Click Send Request.
Sample Prism API Explorer Raw Request area:

The response is returned as an array of matching objects. Click the arrow icons to expand/collapse the object contents.
Sample Prism API Explorer Response Details:

Considerations when making API updates of PrismLogging.ini

• Review the settings in the PrismLogging.ini file before AND after making changes to the log settings from the API.
• If a log setting change that is requested for a service is different from the exiting [global] key value for the setting, the setting is placed in a section for that service (identified by the base name of the binary). If the section or key does not exist it is created.
• If a log setting change is the same as the [global] value and the service has an existing setting in its section PrismLogging.ini, the key is removed since the global value can now be used by the Logger.

Setting Filters
This section has a few examples showing how log files can be filtered.
Filter by Log File Type
Filtering by logfiletype will return a payload with only the specified log file type:
http:///api/techtoolkit/logfile?filter=logfiletype,eq,prismcommon
Use these values when setting filters by logfiletype: PrismBackOffice, PrismCommon, RPSRestServiceModule, LicenseServer, PrismMQService, PrismScheduling, TechToolKit, PrismV9, EFTServiceModule, PrismResiliencyServer, PrismPOSV1, PrismWebModule, PubSubService, V9DRSPubSub, PrismProxy, HardwareServices, JTEInstaller
Sample API Request filtered by logfiletype:
 
Filter by date
Filter by logfiledate to include log files with a date greater than or equal to the specified date. The api uses the date value, starting at midnight for that date. Therefore passing only a date value in the yyyy-mm-dd format will also work.
http:///api/techtoolkit/logfile?filter=logfiledate,ge,2020-09-01T07:00:01.886Z
Files with Errors
Filter by errorcount to return a list containing only log files that have errors:
http:///api/techtoolkit/logfile?filter=(errorcount,ge,1)

Apply Multiple Filters
Use parentheses and the AND/OR operators to apply multiple filter elements.
http:///api/techtoolkit/logfile?filter=(logfiletype,eq,PrismPOSV1)AND(errorcount,ge,1)AND(logfiledate,ge,2020-02-01T17:41:05.582-07:00)
Open a specific log file
http:///techtoolkit/logfile?filter=(logfilename,eq,PrismTechToolKitAsService_190916_154037697.log)
The api will copy the requested file to a new folder and return a payload with the http link where the user can download the file or open it in their editor of choice.
Information for Developers
This section has information for developers about the simplified log method call syntax introduced in 1.14.7 and the StartLogSession() method.
Log Method Call Syntax
In 1.14.7, the log method call syntax no longer requires a log level.
Logger.Log( ‘The message', TlogEntryType);
Example: Logger.Log(‘Some information', ltInfo);
StartLogSession()
procedure StartLogSession(const AAppLogFileName: string; ALogIsSegmented: boolean = true; AAppLogDir: string = '');

Tracking Requests in Retail Pro Prism Log Files
To locate and track requests in the Prism log files can be a little difficult if the log level is set to "3" (most verbose) and there are overlapping requests.
To find the information you are looking for in an efficient manner, use the following two tips:

• Use the Auth-Session ID to identify requests related to the same security session
• Gather the log lines for a request so that you can see all the log entries from the beginning of the request to the end.

1. Identify requests related to the same security session (requests from the same workstation and the same logged-in user). To follow the stream of requests for the same session, search for the session token. It is logged as a long string of characters and digits in the Auth-Session line. Examples:

POSV1:
2020.11.13.01.00.44.339 [3728] Information ------
Auth-Session: 204AC3855B7D498FB7933187BCA992C1
BackOffice:
2020.11.13.04.00.55.249 [5412] Information ------
Auth-Session: 204AC3855B7D498FB7933187BCA992C1
Common:
2020.11.13.01.00.44.323 [1196] Information ------
Auth-Session: 204AC3855B7D498FB7933187BCA992C1

2. Gather log lines for one request from beginning to end. This is very important for multiple requests logging in parallel. In this case you need to find the beginning of the request and use the thread ID to track the log lines generated by that specific consumer while it was processing that specific request. The Thread ID is the number denoted inside square brackets. In this example, the thread ID is 6004

2020.11.08.16.00.12.767 [6004] >> Entry >>
TPOSV1RequestMessageConsumer.ProcessMessage
2020.11.08.16.00.12.767 [6004] Information
********************Message Received********************
2020.11.08.16.00.12.767 [6004] Information ------
Namespace: PrismPOSV1
2020.11.08.16.00.12.767 [6004] Information ------
Host: akvms-v7-1.retailpro.com
2020.11.08.16.00.12.768 [6004] Information ------
URL: /v1/rest/document/542457610000194794?cols=tenders,tender.tender_type,sid,...
2020.11.08.16.00.12.768 [6004] Information ------
ContentType: text/json
2020.11.08.16.00.12.768 [6004] Information ------
Accept: application/json, text/plain, version=2
2020.11.08.16.00.12.768 [6004] Information ------
Method: GET
2020.11.08.16.00.12.768 [6004] Information ------
CorrelationID: {FE3455B7-7848-4C2A-94D9-8F7879653975}
2020.11.08.16.00.12.768 [6004] Information ------
Auth-Session: 36E790446F314B9BB7F9BC0CE47FE5D6
2020.11.08.16.00.12.768 [6004] Information
********************************************************
2020.11.08.16.00.12.769 [6004] >> Entry >>
DISPATCHREST ...
2020.11.08.16.00.13.015 [6004] << Exit << DISPATCHREST
2020.11.08.16.00.13.015 [6004] >> Entry >>
TPrismMessaging.SendReplyMessage
2020.11.08.16.00.13.015 [6004] << Exit <<
TPrismMessaging.SendReplyMessage
2020.11.08.16.00.13.016 [6004] Information Response Message Sent For CorrelationID: {FE3455B7-7848-4C2A-94D9-8F7879653975}
2020.11.08.16.00.13.016 [6004] << Exit <<
TPOSV1RequestMessageConsumer.ProcessMessage
To find out what requests were sent prior to or after the one you are currently examining, search for the session token backward or forward in the log file. You should be able to see those log lines on log levels 2 and 3.
If requests from the SAME session are made to different modules (POSV1, BackOffice, Common) they will show the same Auth-Session value, so you can track whether that session was talking to multiple services.
Note: Do not pay attention to the CorrelationID. CorrelationID is used for tracking interactions between Apache and our services, and is useful only for developers and only in very special circumstances

Locate Request Entry and Exit
The next step is to find where that requests starts and ends. Look for the very first ">> Entry >>" line where it says xxxxxxMessageConsumer.ProcessMessage.
There will be a single blank space on each side of the "Entry" keyword. That is the beginning of the message handler.
Replace ">> Entry >>" with "<< Exit  <<"
There will be a single blank space to the left and TWO blank spaces to the right of the "Exit" keyword.
Keep the rest of the line as is, with FOUR blank spaces after the thread ID, like this:
[6004] << Exit  << TPOSV1RequestMessageConsumer.ProcessMessage
Keep the very same thread ID. If you search FORWARD for that line, it will be the VERY LAST log line for that specific message.
Note: It might end up being in the next log file, so if you did not find it, search in the next file. Or, if you are looking at the last request in the log file it might still be buffered in memory. Wait until the buffer is saved.
Since consumer threads do not change the thread ID while processing requests, each line between the Entry and Exit lines that has the same thread ID belongs to the same consumer thread working on the same request. If you see another line in between with a DIFFERENT thread ID, ignore it. It is coming from a different request.
Note: Each consumer has its own thread ID but there is no correlation between the SESSION and THREAD ID. Any consumer can process any request if it is available.
There is no rule stating that if you process a GET request for a document in thread XYZ, the same thread will process the next request for the same session. THREAD IDs are only important WITHIN the same request. For tracking multiple requests use Auth-Session instead.