Server Log Files

Owned by Chris Welford
Last updated: Oct 08, 2024 by Zoe Baldwin
5 min read

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:

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

See also Logs for Third-Party Systems.

If you want to integrate PhixFlow server logs into other logging frameworks, such as Google Cloud's stackdriver, please contact support@phixflow.com.

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.

  1. Click  Administration to open the Administration menu.
  2. Select Other Options → Download Log Files. PhixFlow opens a window prompting you to enter file names.
  3. 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
  4. 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.
  5. 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.