How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I rotate Java Agents 5, 5.5 and 5.6 debug and audit logs?

Last updated Apr 13, 2021

The purpose of this article is to provide information on rotating Java Agents debug and audit logs.


1 reader recommends this article

Overview

By default, the agent logs are named and located as follows:

  • Debug - debug.out (Agents 5.5 and later) or amAgent (Pre-Agents 5.5), which is located in the /path/to/agent/agent_type/agent_instance/logs/debug directory where the agent is installed.
  • Audit - audit.log - which is located in the /path/to/agent/agent_type/agent_instance/logs/audit directory where the agent is installed.

Java Agents 5.7

Java Agents 5.7 introduces new log rotation capabilities. See User Guide › Debug and Metric Properties for further information.

Rotating Java Agent debug log (Pre-Agents 5.7)

AM does not rotate Java Agent debug logs by default, but you can configure it to do so based on:

  • Time interval (in minutes) - for example, every 1440 minutes for once a day. The time interval specified starts when the first log message is logged to the log file.
  • Size (in bytes) - for example, when the debug log reaches 2097152 bytes (2MB).

To configure Java Agent debug file rotation:

  1. Copy the debugconfig.properties file (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory) to a temporary location.
  2. Edit the properties in the debugconfig.properties file as detailed in Rotating Debug Logs to configure debug log file rotation. For example, if you want your Java Agent debug logs to rotate every 1440 minutes with a suffix of the date and time, you would set the rotation and suffix properties in this file as follows: org.forgerock.openam.debug.rotation=1440 org.forgerock.openam.debug.suffix=-MM.dd.yyyy-HH.mmAlternatively, if you want your debug logs to rotate each time they reach 2MB with a suffix of the date and time, you would set the maxsize and suffix properties in this file as follows: org.forgerock.openam.debug.rotation.maxsize=2097152 org.forgerock.openam.debug.suffix=-MM.dd.yyyy-HH.mm_ss.SSS
  3. Copy the debugconfig.properties file to the classpath of your web application container. For example, if you are using Apache Tomcat™, the /path/to/tomcat/lib directory would be a good location.
  4. Restart the web application container in which the agent runs to apply these configuration changes.

It is recommended that you copy the debug logs prior to clearing the contents, rather than deleting the logs as this can cause issues if a process is still holding a filehandle. Additionally, you should keep debug logging to a minimum (level: error) and only increase it when troubleshooting an issue. 

Rotating Java Agent audit log

Note

Audit logs are logged remotely by default. In which case they are located in the /path/to/openam/var/audit directory (AM 7 and later) or the /path/to/openam/openam/log directory (pre-AM 7) by default and cannot be rotated using this method. Instead you can rotate them in the same way as AM audit logs: Reference › File.

AM does not rotate Java Agent local audit logs by default, but you can configure it to do so based on size, for example, once the file reaches 50MB. The size should be specified in bytes, for example, 52428800.

If your Java agent uses centralized configuration, you can configure the local audit log to rotate using either the console, ssoadm or the bootstrap file:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Global and enable Rotate Local Audit Log.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.local.log.rotate=true com.sun.identity.agents.config.local.log.size=[filesize]replacing [realmname], [agentname], [adminID], [passwordfile] and [filesize] with appropriate values.
  • Bootstrap file: edit the com.sun.identity.agents.config.local.log.rotate and com.sun.identity.agents.config.local.log.size properties in the OpenSSOAgentBootstrap.properties file (located in the /config directory where the Java agent is installed). You should set these properties as follows: com.sun.identity.agents.config.local.log.rotate=true com.sun.identity.agents.config.local.log.size=[filesize]replacing [filesize] with an appropriate value.

If using local configuration, you should edit the OpenSSOAgentBootstrap.properties file as described above.

It is recommended that you copy the audit log prior to clearing the contents, rather than deleting the log as this can cause issues if a process is still holding a file handle.

See Also

How do I enable debug logging for troubleshooting Agents (All versions)?

User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6450 (Log Number of History files count is ignored)

OPENAM-6477 (request for Agent log retention configuration)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.