Logging

MAPS generates log files that record events that occur in MAPS and all of the MAPS applications. If a job errors out, an application crashes, or an action fails, this is where MAPS administrators can look to find the problem and view other related events that occurred around the time of the error.

Note: Email log information is included in the MAPS logs unless you specify a separate log file in the email server setup.

Configuration

The Logging -> Configuration tab allows you to control what information is included in the log files, and how many days' worth of logs to keep.

Logging String

There are nine types of log entries which are included in the log file by default. Four of these are always included in the logs no matter what; the remaining five can be removed if desired. Under most circumstances, we suggest leaving the logging string blank (the default) to retain the most helpful information while keeping the file size low. When no logging string is specified, the logs include all of the "always" and "by default" entries shown in the table below.

When working with Evisions Support on an issue, we may request that you temporarily set your logging string to "All". This adds four additional entry types: Command, Debug, and Operation.

If you wish to remove a specific entry type from the log files, use the following notation:

All, -Type1, -Type2, -Type3, etc.

For example, to remove the NormalAction entries from the default, use:

All, -Command, -Debug, -NormalAction

 

Type	Included?	Information
All		Includes ALL entry types. Use with - notation to remove entries.
Application	always	Name and version number of launched applications.
Connect	always	User connects.
Disconnect	always	User disconnects.
Logon	always	User logs in to a MAPS application.
Action	by default	Server initialization information.
Error	by default	Any error messages that occur. These entries can be extremely helpful in identifying any issues.
Info	by default	Detailed information about server activity.
NormalAction	by default	Detailed action information such as retrieving lists of mail servers, displaying version numbers, etc.
Warning	by default	Error detected which does not impact system or data integrity.
Command	with "all"	Server actions such as compression, encryption, and calls to mapplets.
Debug	with "all"	Verbose messages for debugging, including idle time and response times.
Operation	with "all"	Activities such as displaying user lists and connection names.
Trace		Function enters or exits.

Memory usage

Enter the interval (in seconds) that memory usage information should be included in the log. The default is 0 (do not include).

Log retention

Specify the number of days that log files should be kept. The default is 30.

Logs

The Logging -> Logs tab lists all of the log files currently saved on the MAPS server.

You may see several types of log files depending on your configuration and installed products. All logs except for email logs use system-generated names in date order.

Log Type	Naming Convention	Contents
Maintenance	Maintenance.YYYY-MM-DD.log	Logs pertaining to automated backups and stopping/starting the service. Typically only a few lines.
BankMobile	BankMobile_YYYY-MM-DD.log	IntelleCheck only. Logs pertaining to transmission of payment information using the optional BankMobile module for IntelleCheck.
Email	If present, the user-specified name from the email server configuration.	Email transmission logs. Only present if an email server is configured to use a separate log file instead of writing to the MAPS log.
MAPS	YYYY-MM-DD.log	Main MAPS log file containing all entries specified on the Configuration tab.
Salesforce	Salesforce_[connection name].YYYY-MM-DD[unique string].log	Logs pertaining to data connections that use the Salesforce Connector.
REST	rest_[connection name].YYYY-MM-DD[unique string].log	Logs pertaining to data connections that use the REST Connector.

To open a log file, double click on it to use the plain-text log viewer, or go to View -> Advanced View in the menu to open the MAPS Log Viewer.

You can save a log file to your local system by clicking the Save button. Alternatively, all log files are available on the MAPS server in the C:\Program Files\Evisions\MAPS\Service\Logs directory. To save hard disk space, log files more than two days old that are over 100k in size are compressed using gzip and have a .gz extension. If you want to access these files from the Logs directory, you will need to unzip them before you can open the files in a text editor. Logs downloaded from the MAPS Config application using the Save button are uncompressed text files.

Note: In clustered environments, email logs and Salesforce logs are located only on the specific MAPS node that generated the log file.

MAPS log files can be sorted by filename, size, or creation date. To add the creation date to the view, right-click in the column header and check the Created Date option.

The MAPS Log Viewer

Double-click on a log file to open it in the plain-text viewer. Note how the entries are not very easy to read in plain-text format:

To improve readability and to help interpret the log file using filters and sorting, you can instead open it in the MAPS Log Viewer by going to View -> Advanced View.

The Log Viewer parses the file and displays it in an easy-to-read format. Depending on the size of the file, it may take a minute or more to parse. You can watch its progress and see and any related messages in the status box in the lower left hand corner.

Components of a MAPS Log File

The Log Viewer breaks the data in the log file into six columns:

Column	Description
Tag	The type of log entry (Info, NormalAction, Connect, etc.)
Time	Time the action occurred
Text	Detailed information about the entry (the actual action or information)
User	The name of the user performing the action
LID	A unique Log ID assigned to each connection. This takes the form of the client's IP address and communication port for this application.
TID	Thread ID. Indicates which thread (on the MAP server) performed the action.

By default, the log entries are sorted by time in the same order that they appear in the plain-text file. You can easily change the sort by clicking on the desired column heading.

Selecting any entry displays the full text in its original format in the box in the lower right.

Filtering

The checkboxes and text fields at the top of the Log Viewer allow you to apply filters to show only the data you are looking for. For instance, if you want to see all error messages and warning messages that occurred that day, type "Error, Warning" in the Tags box and then click Apply Filters.

Check the appropriate box if you want to filter on specific Log IDs (LIDs) or Thread IDs (TIDs) or specify a start and end time to help narrow down the results. The LID and TID boxes allow you to enter multiple values, separated by commas.

Note: You must check the box next to each filter you want to use. Simply entering a value does not enable the filter.

The Group by Connection option changes the way entries are displayed. It groups the log entries by the connection (essentially grouping on the LID, but may include other connection-related entries), and then applies your chosen sort. This can be very helpful when you have many users logged into the system at a given time and want to see only the entries relating to a specific user or event.

Notice how the first line of the connection group identifies the user. By definition, all entries in a connection group belong to the same user.

Interpreting Log Files

Look for errors

When trying to track down messages relating to a specific event or problem, start by looking at any Error log entries for that day. If you know the approximate time the problem happened, filter the entries for a period around that time.

Identify the user and application

Sometimes you need to find which user was associated with an error message or event. For example, if someone is running large jobs at an inconvenient time, you may want to know who that is so you can ask them to reschedule. It can also be helpful to know which application they were running.

Notice that most log entries do not identify the user or application responsible for the entry. Usernames are recorded in the Logon entry types; similarly, applications are identified in the Application entries. Recall that every connection has a unique LID. You will want to make note of the LID belonging to the error or event you are looking at, and then find the Logon and/or Application entries with the same LID.

You can use the Group by Connection feature to show the Logon and Application entries alongside any error messages; alternatively, simply filter on the LID for these tag types.

Follow query threads

Query errors may not have an associated LID. However, since each query uses its own thread, you can filter on the Thread ID (TID) in a similar manner to how you would filter on the LID. Note that there should be entries before the error that include the LID along with the selected TID, which help you identify the user.

See also: Tracking an Argos Schedule with the MAPS Log Viewer

Installing Your Own Log Viewer

The MAPS Log Viewer is a stand-alone executable which you can replace with any log parser/text viewer executable of your choice. This can be done either for every MAPS user, or on your local system for your own personal use. Simply rename your executable to be "MAPSLogViewer.exe" and overwrite the original in the appropriate directory.

Local Windows XP system:
C:\Documents and Settings\username\ Application Data\Evisions\MAPClients\Configuration\version number folder

Local Windows 7 or higher system:
C:\Users\username\AppData\Roaming\Evisions\MAPClients\Configuration\version number folder

MAPS server:
C:\Program Files\Evisions\MAPS\Service\Applications\Configuration\version number folder for 32-bit MAPS installations

C:\Program Files\Evisions\MAPS\Service\bin64\ for 64-bit MAPS installations

If you replace this file, new users who have not yet logged in to the current version of the MAPS Configuration tool will download the replacement executable from the MAP server. The executable is saved on their local system in one of the above directories, and run when they launch the Configuration tool/log viewer. To update the executable on a system that has logged in before, replace the local copy as well.

Note: Any time you update to a new version of the MAPS Config application, you will need to copy your custom viewer into the new version's folder (either locally or on the MAPS server).