Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel

On this page:

Table of Contents


Info
Summary: this page explains where the dashboard/RestAPI log files are located, how to change their storage location if required and how to enable the Audit Trail facility.

Default log file location

By default the dashboard/RestAPI will place all relevant log files (i.e. logs relative to the functioning of the dashboard) in the following location:

No Format
languagetext
CATALINA_HOME\webapps\<dashboard>\logs

Logs are provided in two different formats:

Log files
Description
Notes

restapi.log

restapi.html

Records all web service interaction (errors, warnings etc.)


Info
Note that the *.html log files will not be used in the default "out of the box" configuration. If you would like to have log messages sent to the *.html files as well as the *.log files, please see Enabling log output to *.html files.


restapi.perf.log

restapi.perf.html

Records performance information about user interaction.
restapi.audit.log

Records successful user logins, failed logins, logouts, web application startup/stop. This log is not active by default.



Info
See Enabling and configuring the Audit Trail mode section below for more information about this.


Changing the log file storage location

You do not need to change the location of the log files unless you specifically need to use a different location other than the default. To do so, you need to modify the following file with a text editor:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\WEB-INF\log4j2.xml

To change the location of the log folder within the limits of the web application, search for the following line in the file:

Code Block
languagexml
<Property name="logPath">$${web:rootDir}/logs</Property>

Change /logs to the required location (for example /test) within the web application file hierarchy:

Code Block
languagexml
<Property name="logPath">$${web:rootDir}/test</Property>

Following any changes you make, save the log4j2.xml file and then restart your application server so that the changes are taken into account. Your log files will now be stored in the new location. For example:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\test

Changing the log file roll over strategy

All log files that are generated have a default roll over strategy as follows:

  • When the initial log file (as listed in the Default log file location section above) reaches 10MB in size, logging will cease to this file and a new dated log file (with the file name in the format aad-{yyyy-MM-dd}.log) will be created and logging will continue in the new file.
  • 5 previous log files will be retained in the default log file location. Any subsequent roll overs will cause the oldest log file to be deleted, keeping the number of log files retained to 5.

This strategy can be modified as follows modify the following file with a text editor:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\WEB-INF\log4j2.xml

Find the following two elements which control the strategy (there are two elements per log file):

Code Block
languagexml
<SizeBasedTriggeringPolicy size="10 MB"/>
<DefaultRolloverStrategy max="5"/>

Modify the options as necessary. For example, to cause a roll over of the restapi.log file when the file size reaches 20MB and to retain 10 previous log files, set the options as follows:

Code Block
languagexml
<RollingFile name="textout" fileName="${logPath}/restapi.log"
		filePattern="${logPath}/restapi-%d{yyyy-MM-dd}.log">
	<PatternLayout pattern="%d| %-5p | %t | %c | %m%n"
		charset="UTF-8"/>
	<Policies>
		<SizeBasedTriggeringPolicy size="20 MB"/>
	</Policies>
	<DefaultRolloverStrategy max="10"/>
</RollingFile>

Following any changes you make, save the log4j2.xml file and then restart your application server so that the changes are taken into account.

Anchor
html
html
Enabling log output to *.html files

By default the log system is configured to ouput log messages only to *.log files. If you require messages to be output to *.html files as well, you need to modify the following file with a text editor:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\WEB-INF\log4j2.xml

Add the line <AppenderRef ref="htmlout"/> to the following five <Logger> elements in the file, this will give you the following:

Code Block
languagexml
<Logger name="com.castsoftware.adg.webservice" level="info" additivity="false">
	<AppenderRef ref="textout"/>
	<AppenderRef ref="htmlout"/>
</Logger>
<Logger name="com.castsoftware.adg.webservice.servlet" level="error" additivity="false">
	<AppenderRef ref="textout"/>
	<AppenderRef ref="htmlout"/>
</Logger>
<Logger name="org.springframework" level="info" additivity="false">
	<AppenderRef ref="textout"/>
	<AppenderRef ref="htmlout"/>
</Logger>
<Logger name="org.springframework.jdbc.core.JdbcTemplate" level="error" additivity="false">
	<AppenderRef ref="textout"/>
	<AppenderRef ref="htmlout"/>
</Logger>
<Logger name="org.springframework.jdbc.core.StatementCreatorUtils" level="error" additivity="false">
	<AppenderRef ref="textout"/>
	<AppenderRef ref="htmlout"/>
</Logger>


Info
Note that there are other <Logger> elements in the file, but these do not need modifying.

Anchor
audit
audit
Enabling and configuring the Audit Trail mode

By default, the various log outputs do not contain any information about successful user logins, failed logins, logouts, web application startup/stop etc. If you would like to see this information in a log file for security reasons, then you can enable the Audit Trail feature. To do so, you need to modify the following file with a text editor:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\WEB-INF\log4j2.xml

Search for the following line in the file:

Code Block
languagexml
<Property name="auditLevel">OFF</Property>

Change the OFF value to ALL:

Code Block
languagexml
<Property name="auditLevel">ALL</Property>

Following any changes you make, save the log4j2.xml file and then restart your application server so that the changes are taken into account. Messages relating to successful user logins, failed logins, logouts, web application startup/stop will now be displayed in the restapi.audit.log file in the following format:

Code Block
languagetext
[ Date | ip address | level | user behavior | rest URL | user name | user role | delay time ]

For example:

Code Block
languagetext
2015-03-19 18:05:07,488 | 192.168.16.73 | INFO | Application startup |     SLI   
2015-03-19 18:05:29,602 | 192.168.16.73 | INFO | Login successful | http://tomcat/testContext/rest/login    CIO  [NO_ROLE]  18
2015-03-19 18:05:29,602 | 192.168.16.73 | INFO | Login successful | http://tomcat/testContext/rest/user    CIO  [NO_ROLE]  0
2015-03-19 18:05:30,756 | 192.168.16.73 | INFO | User Logout |     CIO   
2015-03-19 18:05:34,723 | 192.168.16.73 | WARN | Login failed |     cioS   
2015-03-19 18:05:41,806 | 192.168.16.73 | INFO | Login successful | http://tomcat/testContext/rest/login    admin  [ADMIN]  0
2015-03-19 18:05:41,806 | 192.168.16.73 | INFO | Login successful | http://tomcat/testContext/rest/user    admin  [ADMIN]  0
2015-03-19 18:05:43,313 | 192.168.16.73 | INFO | User Logout |     admin   


Info
Note that the rest URL, user role and delay time options are only displayed for successful login messages.

Enabling DEBUG log mode for Active Directory authentication issues

By default, the log mechanism is not configured to provide any logging information to debug Active Directory authentication issues (see the relevant section in User authentication). If you have encountered issues activating Active Directory authentication, you can enable DEBUG log mode specifically to help resolve the problems you are having. To do so, you need to modify the following file with a text editor:

Code Block
languagetext
CATALINA_HOME\webapps\<dashboard>\WEB-INF\log4j2.xml

Uncomment the following section (this can be found at the end of the file):

Code Block
languagexml
<!-- Uncomment on LDAP access issues -->
<!-- 
<Logger name="org.springframework.security" level="debug">
	<AppenderRef ref="textout"/>
</Logger>        
-->

This should give you this:

Code Block
languagexml
<!-- Uncomment on LDAP access issues -->
<Logger name="org.springframework.security" level="debug">
    <AppenderRef ref="textout"/>
</Logger>        

Following any changes you make, save the log4j2.xml file and then restart your application server so that the changes are taken into account. Messages relating to Active Directory authentication will now be displayed in the log files.