--- title: Capture troubleshooting information description: The AM recording facility lets you initiate events to monitor AM while saving output that is useful when performing troubleshooting. component: pingam version: 7.3 page_id: pingam:maintenance-guide:record-troubleshooting canonical_url: https://docs.pingidentity.com/pingam/8.1/maintenance/record-troubleshooting.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Troubleshooting"] --- # Capture troubleshooting information The AM recording facility lets you initiate events to monitor AM while saving output that is useful when performing troubleshooting. AM recording events save four types of information: * AM debug logs * Thread dumps, which show you the status of every active thread, with output similar to a JStack stack trace * Important runtime properties * The AM configuration You initiate a recording event by invoking the `ssoadm start-recording` command with a JSON file, or through a REST call with a JSON payload. The file or payload controls the amount of information AM records, the duration of the recording, and the location of recording output files. > **Collapse: Recording control file/payload reference** > > Record control file configuration properties > > * `issueID` > > Type: Number > > *Required*. The issue identifier—a positive integer stored internally as a Java `long` data type. A case number is a good choice for the `issueID` value. > > The `issueID` is a component of the path at which recorded information is stored. > > See [Retrieving Recording Information](#recording-location) for more information. > > * `referenceID` > > Type: String > > *Required*. A second identifier for the recording event. Use this property to segregate multiple recording events for the same issue. > > The `referenceID` is a component of the path at which recorded information is stored. > > Spaces are not allowed in the `referenceID` value. > > See [Retrieving Recording Information](#recording-location) for more information. > > * `Description` > > Type: String > > *Required*. A textual description of the recording event. > > * `zipEnable` > > Type: Boolean > > *Required*. Whether to compress the output directory into a zip file when recording has stopped. > > * `configExport` > > Type: Object > > *Required*. An object containing the following properties: > > * `enable` > > Type: Boolean > > *Required*. Whether to export the AM configuration upon completion of the recording event. Exporting the AM configuration is a best practice, because it is extremely useful to have access to the configuration when troubleshooting. > > * `password` > > Type: String > > *Required* if `enable` is `true`. A key required to import the exported configuration. The key is used the same way that the `ssoadm export-svc-cfg` command uses the `-e` argument. > > * `sharePassword` > > Type: Boolean > > *Required* if `enable` is `true`. Whether to show the `password` value in the `ssoadm start-recording`, `ssoadm get-recording-status`, and `ssoadm stop-recording` output, and in the `info.json` file, which is output during recording events, and which contains runtime properties. > > * `debugLogs` > > Type: Object > > *Required*. An object containing the following properties: > > * `debugLevel` > > Type: String > > *Required*. The debug level to set for the recording event. Set the value of `debugLevel` to `MESSAGE` to get the most troubleshooting information from your recording period. Other acceptable but less commonly used values are `ERROR` and `WARNING`. > > * `autoStop` > > Type: Object > > *Optional*. Contains another object used to specify an event that automatically ends a recording period. For time-based termination, specify a `time` object; for termination based on uncompressed file size, specify a `fileSize` object. If you specify both `time` and `fileSize` objects, the event that occurs first causes recording to stop. > > Specifying `fileSize` and `time` objects is a best practice, because it ensures that the recorded output does not occupy a larger than expected amount of space on your file system, and that recording events end in a timely fashion. > > * `time` > > Type: Object > > *Optional*; must be specified in the `autoStop` object if `fileSize` is not specified. Configures a recording period to terminate recording after this amount of time. > > * `timeUnit`: > > Type: String > > *Required*. Acceptable values are `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, and `DAYS`. > > * `value`: > > Type: Numeric > > *Required*. Values in `MILLISECONDS` are rounded down to the second. The minimum acceptable value for `autoStop` is one second. > > * `fileSize` > > Type: Object > > *Optional*; must be specified in the `autoStop` object if `time` is not specified. Configures a recording period to terminate after the aggregate size of uncompressed debug logs has reached this size. > > * `sizeUnit`: > > Type: String > > *Required*. Acceptable values are `B`, `KB`, `MB`, and `GB`. > > * `value`: > > Type: Numeric > > *Required*. > > * `threadDump` > > Type: Object > > *Required*. An object containing the following properties: > > * `enable` > > Type: Boolean > > *Required*. Whether to dump threads during the recording event. Thread dumps are especially useful when troubleshooting performance issues and issues with unresponsive servers. > > * `delay` > > Type: Object > > *Required* if `enable` is `true`. Contains another object used to specify an interval at which thread dumps are taken. The initial thread dump is taken at the start of the recording event; subsequent thread dumps are taken at multiples of the `delay` interval. > > * `timeUnit` > > Type: String > > *Required*. Acceptable values are `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, and `DAYS`. > > * `value` > > Type: Numeric > > *Required*. The minimum acceptable value is one second. Time units that are smaller than seconds, such as `MILLISECONDS`, are rounded to the closest second. > **Collapse: Recording control file/payload example** > > ```json > { > "issueID": 103572, > "referenceID": "policyEvalFails", > "description": "Troubleshooting artifacts in support of case 103572", > "zipEnable": true, > "configExport": { > "enable": true, > "password": "5x2RR70", > "sharePassword": false > }, > "debugLogs": { > "debugLevel": "MESSAGE", > "autoStop": { > "time": { > "timeUnit": "SECONDS", > "value": 15 > }, > "fileSize": { > "sizeUnit": "GB", > "value": 1 > } > } > }, > "threadDump": { > "enable": true, > "delay": { > "timeUnit": "SECONDS", > "value": 5 > } > } > } > ``` > > The recording control file properties in the preceding example affect the recording output as follows: > > **Recording control file example properties and effects on recording behavior** > > | Recording Control File Property | Value | Effect | > | ------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `issueID`, `referenceID` | `103572`, `policyEvalFails` | Recording output is stored at the path `debugFileLocation/record/103572/policyEvalFails_timestamp.zip`. For more information about the location of recording output, see [Retrieve recording information](recording-location.html). | > | `Description` | `Troubleshooting artifacts in support of case 103572` | No effect. | > | `zipEnable` | `true` | Recording output is compressed into a ZIP file. | > | `configExport` / `enable` | `true` | The AM configuration is exported at the start of the recording event. | > | `configExport` / `password` | `5x2RR70` | Knowledge of this password will be required to access the AM configuration that was saved during recording. | > | `configExport` / `sharePassword` | `false` | The password is not displayed in output messages displayed during the recording event or in the `info.json` file. | > | `debugLogs` / `debugLevel` | `MESSAGE` | Recording enables message-level debug logs during the recording event. | > | `debugLogs` / `autoStop` / `time` | `SECONDS`, `15` | Because both the `time` and `fileSize` properties are set, recording stops after 15 seconds, or after the size of the debug logs exceeds 1 GB, whichever occurs first. | > | `debugLogs` / `autoStop` / `fileSize` | `GB`, `1` | Because both the `time` and `fileSize` properties are set, recording stops after 15 seconds, or after the size of the debug logs exceeds 1 GB, whichever occurs first. | > | `threadDump` / `enable` | `true` | Thread dumps are taken throughout the recording event. | > | `threadDump` / `delay` | `SECONDS`, `5` | The first thread dump is taken when the recording event starts. Additional thread dumps are taken every five seconds hence. | The following table shows different tasks related to recording troubleshooting information: | Task or Requirement | Resources | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Start and stop recording information**Use the `ssoadm` command or REST calls to start and stop recording information. You can also check if there are active recording events using REST ([Get recording status (REST)](rest-api-records-get-status.html)). | * [Start and stop recording (ssoadm)](recording-start-stop.html) * [Start and stop recording (REST)](rest-api-record-start-stop.html) | | **Retrieve information**AM stores the troubleshooting information you gathered, so it is ready to be sent to ForgeRock Support representatives. | - [Retrieve recording information](recording-location.html) |