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 Jan 11, 2023

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

1 reader recommends this article

This article does not apply to Java Agents 5.7 and later because Java Agents 5.7 introduces new log rotation capabilities. See Debug and Metric Properties for further information.


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.

Rotating Java Agent debug log

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 file (located in the /path/to/tomcat/webapps/am/WEB-INF/classes directory) to a temporary location.
  2. Edit the properties in the 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 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


Audit logs are logged remotely by default. In which case they are located in the /path/to/am/var/audit directory (AM 7 and later) or the /path/to/am/am/log directory (AM 6.x) by default and cannot be rotated using this method. Instead you can rotate them in the same way as AM audit logs: 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 AM admin UI, ssoadm or the bootstrap file:

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Global and enable Rotate Local Audit Log. 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 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 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)?

Configuring Global Properties

Related Training


Related Issue Tracker IDs

OPENAM-6477 (request for Agent log retention configuration)

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