This page is for administrators who need to monitor events on the PhixFlow system using the server log files.

Overview

You can monitor PhixFlow activity using:

the System Console records details of user activity and tasks within PhixFlow. For details, see System Console. You can configure system logging options in the System Logging Configuration properties.
server log files, which record PhixFlow activity on the server and network. These files are generated by:
- the PhixFlow webapp
- the Tomcat servlet.

This page explains where to find the server log files, and how to configure them.

PhixFlow Webapp Log Files

Where to Look

To find the logged information about PhixFlow webapp activity on the server and network, use the log files saved in the <tomcat_installation_base>/logs directory. You can also download a zip file of all or selected log files; see Downloading Server Log Files, below.

The default names of the server log files generated by PhixFlow are:

phixflow.log
phixflow.<date>.<increment number>.log.gz
security.log
security.<date>.log
audit.log

If you have multiple instances of PhixFlow hosted under the same Tomcat instance, each PhixFlow instance requires a different log file name. You can find the log file names for different instances in logback.xml.

Security.log

This records all logouts and login attempts.

For logouts this includes:

username
session
IP address
whether the user logged out or their session timed out

For login attempts, this includes:

username
IP address of the user
successful logins include the session
failed attempts include the reason for the failure

Audit.log

This provides reliable auditing that works even if the database goes down or the application is restarted before the audit can be written to the database.

An audit.log file is created with records that look similar to:

2024-08-09 12:37:52,724 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:36] audit summary (transaction=6e069a642616791ed5d43db795a8aab3 id=a43a17886a945bd00ef25a10a2201b9d dtm=2024-08-09T12:37:52.696+01:00 code='audit.new' args=['User','acampbell'])
2024-08-09 12:37:52,725 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:38] audit object (transaction=6e069a642616791ed5d43db795a8aab3 name='acampbell' ref=User-f7b51ccb65b21f4955985394cd725df2)
2024-08-09 12:37:52,725 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field' args=['activeDirectoryGroups',''])
2024-08-09 12:37:52,725 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field.nodetail' args=['defaultApplication'])
2024-08-09 12:37:52,725 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field.nodetail' args=['defaultDashboard'])
2024-08-09 12:37:52,725 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field' args=['deleted',false])
2024-08-09 12:37:52,725 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field' args=['designMode',false])
2024-08-09 12:37:52,726 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field' args=['domainName','local'])
2024-08-09 12:37:52,726 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:41] audit detail (transaction=6e069a642616791ed5d43db795a8aab3 code='audit.set.field' args=['email',''])
2024-08-09 12:37:52,820 INFO [ForkJoinPool-6-worker-3] p.audit [LoggingAuditService.java:32] audit trans-end (transaction=6e069a642616791ed5d43db795a8aab3 status=FAIL)

The audit trans-end record has 3 possibilities for each transaction:

status=SUCCESS: The transaction completed and the associated audit records are valid
status=FAIL: The transaction failed and rolled back
- The associated audit records should be ignored as they were not committed to the database
trans-end missing: The application crashed before the trans-end log message was written
- This is unlikely but possible the transaction was committed so manual verification against the database is required

On application start up, audit log files are reread. Any audit events that were not successfully persisted are replayed into the database.

Configuration

phixflow-logging.xml

phixflow-logging.xml is configured at installation; see Configure phixflow-logging.xml. When you use the PhixFlow Administration menu option Download Log Files, PhixFlow uses this file to find the the path to the logs directory; see Downloading Server Log Files, below.

You only need to change this file as requested by PhixFlow Support.

logback.xml

logback.xml is configured at installation; see Configure logback.xml. The installer sets:

the default level of event or error logging
the name of the log files generated, if you have multiple PhixFlow instances; see Multiple PhixFlow Webapps.

The logback.xml file is in:

<tomcat_installation_base>/webapps/<instance_name>/WEB-INF/classes/logback.xml

For example:

/usr/local/tomcat/webapps/phixflow/WEB-INF/classes/logback.xml

Setting the retention policy

The logback configuration includes a setting maxHistory to remove PhixFlow logs after a specified number of days. This is set for each type of log file. Note that these settings apply only to the log files generated by PhixFlow, through logback, and do not apply to the log files that are produced by Tomcat itself (see Tomcat and Java Log Files below). In most cases, however, the files produced by Tomcat do not become very large. If you need help managing these, please contact support@phixflow.com.

In most cases the files generated by PhixFlow through logback are phixflow.log and security.log. In this case, the logback.xml file will include the following snippets. Update the maxHistory setting in each to meet your log retention requirements.

  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/phixflow.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">        
      <!-- daily rollover -->
      <fileNamePattern>logs/phixflow.%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>30</maxHistory>
    </rollingPolicy>

  <appender name="SECURITY" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/security.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">        
      <!-- daily rollover -->
      <fileNamePattern>logs/security.%d{yyyy-MM-dd}.log</fileNamePattern>
	  <maxHistory>30</maxHistory>
    </rollingPolicy>

Changing the Logging Level

When investigating problems, you can change the logging level set in logback.xml. If you are working with the PhixFlow support team, they can advise you about what to change. Changes to logback.xml take effect within one or two minutes, without having to restart the Tomcat server.

logback.xml contains lines with the form: <logger name="name" level="level" />

where level is one of:

error - reports errors only
debug - reports more details.

For example: <logger name="com.accipia.centerview.util.security" level="debug" />

Edit logback.xml to change the logging level to debug for the required logger and then rerun the activity that has the problem. Then, check the more detailed output in phixflow.log.

With additional debug information, PhixFlow will generate very large log files. Remember to reset the logging level when you have solved your problem and you no longer need the debug information.

Tomcat and Java Log Files

In most cases you will not need to look at these log files, but PhixFlow support may ask you to provide these when investigating an issue.

Tomcat log files

Tomcat generates a set of log files, including:

manager.<date>.log
localhost_access_log.<date>.txt
localhost.<date>.log
host-manager.<date>.log
catalina.out and catalina.<date>.log
tomcat-stdout.<date>.log
tomcat-stderr.<date>.log

Java log files - GC logs

Java generates GC (Garbage Collection) files with the file name format:

gc-yyyy-mm-dd_hh-mm-ss.log

where yyyy-mm-dd_hh-mm-ss is the start time of the Tomcat process. Therefore, there may be a number of files like this if you have restarted Tomcat several times since the logs directory was cleared.

Downloading Server Log Files

In addition to viewing the log files in the <tomcat_installation_base>/logs directory you can download a zip file of all or selected log files.

Click Administration to open the Administration menu.
Select Other Options → Download Log Files. PhixFlow opens a window prompting you to enter file names.
Enter file names, optionally using an asterisk * as a wildcard. Files you may want to download are:
- generated by PhixFlow (you may have configured different names for different instances)
  - phixflow.log
  - phixflow.log.<date>
  - security.log
  - security.log.<date>
  - audit.log
- generated by Tomcat and Java
  - manager.<date>.log
  - localhost_access_log.<date>.txt
  - localhost.<date>.log
  - host-manager.<date>.log
  - catalina.out and catalina.<date>.log
  - tomcat-stdout.<date>.log
  - tomcat-stderr.<date>.log
  - gc-yyyy-mm-dd_hh-mm-ss.log
Click to start the download process. PhixFlow zips the specified log files into a single zipped archive. Depending on your system configuration, downloading all log files may take some time and will produce a large (several GB) zip file.
When the download is finished, a blue notification box reports that the file is ready. Click the notification to download the zip file.

PhixFlow finds the location of the server log files using the directories specified in phixflow-logging.xml.

Browser not supported