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.

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

Recording control file/payload example

{
  "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.
`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

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)).	Start and stop recording (ssoadm) Start and stop recording (REST)
Retrieve information AM stores the troubleshooting information you gathered, so it is ready to be sent to ForgeRock Support representatives.	Retrieve recording information

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)).

Retrieve information

AM stores the troubleshooting information you gathered, so it is ready to be sent to ForgeRock Support representatives.

Retrieve recording information

Access Management 7.3.1

Capture troubleshooting information