How do I record troubleshooting information in AM (All versions)?

Overview

The following sections demonstrate how to manually start and stop recording using REST or ssoadm:

• Using the REST API to record troubleshooting information
• Using ssoadm to record troubleshooting information

However, recordings can stop automatically if:

• You start a new recording that has a different issueID specified in the recording control file.
• The maximum recording time specified in the recording control file has been reached (autoStop and time properties).
• The maximum debug log file size specified in the recording control file has been reached (autoStop and fileSize properties).

See Record troubleshooting information (Recording Control File) for further information on these properties.

There is also a Postman collection with example requests for recording. See Best practice for recording troubleshooting information in AM (All versions) for further information.

Known issues

You should be aware of the following known issues and workarounds:

• If your recording exceeds the time set in the autoStop property, your recording may be empty or show content from a previous recording. You can work around this by increasing the recording time (autoStop) from the default 15 seconds to ensure it exceeds your recording time, for example, by setting it to 5 minutes. For example, if you use the ssoadm stop-recording command to stop the recording after 1 minute, but autoStop is set to 15 seconds, you will see the following error: {"code":400,"reason":"Bad Request","message":"No record or it's already stopped."}
• If you enable the threadDump section and then subsequently disable it, you also need to remove the delay section as shown in the examples below, else the recording will fail.
• If you disable module based authentication, the ssoadm start-recording command will fail with a 401 Unauthorized: Access denied response. See Some ssoadm commands fail with Service URL not found:session error when module based authentication is disabled in AM (All versions) for further information and the solution.

Using the REST API to record troubleshooting information

This section provides information on manually starting and stopping the recording using the REST API. You can check the status of a recording using the json/records?_action=status endpoint as described in Get recording status (REST).

You can use the REST API to record troubleshooting information as follows:

1. Authenticate as amAdmin (you cannot use a delegated administrator). For example: $ curl -v -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }
2. Start recording the troubleshooting information using the following curl command. This curl command includes very simple example recording properties (including thread dumps enabled), but you should change them according to what data you need to collect: $ curl -v -X POST -H "iPlanetDirectoryPro: AQIC5..." -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -d ' { "issueID": 103572, "referenceID": "policyEvalFails", "description": "Troubleshooting artifacts in support of case 103572", "zipEnable": true, "configExport": { "enable": true, "password": "5x2RR70", "sharePassword": false }, "debugLogs": { "debugLevel": "MESSAGE" }, "threadDump" : { "enable": false } }' https://am.example.com:8443/am/json/records?_action=startExample response: {"recording":true,"record":{"issueID":103572,"referenceID":"policyEvalFails","description":"Troubleshooting artifacts in support of case 103572","zipEnable":true,"threadDump":{"enable":false},"configExport":{"enable":true,"password":"xxxxxx","sharePassword":false},"debugLogs":{"debugLevel":"message","autoStop":{"time":{"timeUnit":"MINUTES","value":5},"fileSize":{"sizeUnit":"KB","value":1048576}}},"status":"RUNNING","folder":"/home/forgerock/am1/var/debug/record/103572/policyEvalFails/"}}See Record troubleshooting information (Recording Control File) for further information on the properties in this curl command.
3. Reproduce the issue for which you want to record troubleshooting information.
4. Stop recording the troubleshooting information (unless it will stop automatically) using the following curl command: $ curl -v -X POST -H "iPlanetDirectoryPro: AQIC5..." -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" https://am.example.com:8443/am/json/records?_action=stop
5. Find your recording, which is located in the /debug/record directory (by default, /path/to/am/var/debug/record (AM 7 and later) or /path/to/am/debug/record (AM 6.x)) and is stored according to the issueID and referenceID as explained in Retrieve recording information.
6. Attach the recording to your support request as detailed in Sending troubleshooting data to ForgeRock Support for analysis.

Using ssoadm to record troubleshooting information

This section provides information on manually starting and stopping the recording using ssoadm. You can check the status of a recording using the ssoadm get-recording-status command, which takes the same format as the stop-recording command detailed in step 4 below.

You can use ssoadm to record troubleshooting information as follows:

1. Create a JSON recording control file to specify what should be recorded and how. An example file looks like this (with autoStop properties specified and thread dumps disabled): { "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": "MINUTES", "value": 5 }, "fileSize": { "sizeUnit": "GB", "value": 1 } } }, "threadDump" : { "enable": false } }See Record troubleshooting information (Recording Control File) for further information on the properties in this file.
2. Start recording the troubleshooting information using the following ssoadm command: $ ./ssoadm start-recording -s [serverName] -u [adminID] -f [passwordfile] -J [controlFile]replacing [serverName], [adminID], [passwordfile] and [controlFile] with appropriate values, where [serverName] is the URL with fully qualified domain name (FQDN) of the server for which you want to record information and [controlFile] is the path and filename of the recording control file you created in step 1.
   • AM 7 and later: $ ./ssoadm start-recording -s https://am.example.com:8443/am -u uid=amAdmin,ou=People,dc=am,dc=forgerock,dc=org -f pwd.txt -J /path/to/recording.json
   • AM 6.x: $ ./ssoadm start-recording -s https://am.example.com:8443/am -u amadmin -f pwd.txt -J /path/to/recording.json

Example response:{"recording":true,"record":{"issueID":103572,"referenceID":"policyEvalFails","description":"Troubleshooting artifacts in support of case 103572","zipEnable":true,"threadDump":{"enable":false},"configExport":{"enable":true,"password":"xxxxxx","sharePassword":false},"debugLogs":{"debugLevel":"message","autoStop":{"time":{"timeUnit":"MINUTES","value":5},"fileSize":{"sizeUnit":"KB","value":1048576}}},"status":"RUNNING","folder":"/home/forgerock/am1/var/debug/record/103572/policyEvalFails/"}}

3. Reproduce the issue for which you want to record troubleshooting information.
4. Stop recording the troubleshooting information using the following ssoadm command (unless it will stop automatically): $ ./ssoadm stop-recording -s [serverName] -u [adminID] -f [passwordfile]replacing [serverName], [adminID] and [passwordfile] with appropriate values.
5. Find your recording, which is located in the /debug/record directory (by default, /path/to/am/var/debug/record (AM 7 and later) or /path/to/am/debug/record (AM 6.x)) and is stored according to the issueID and referenceID as explained in Retrieve recording information.
6. Attach the recording to your support request as detailed in Sending troubleshooting data to ForgeRock Support for analysis

See Also

How do I collect all the data required for troubleshooting AM and Agents (All versions)?

How do I avoid common issues with REST calls in AM (All versions)?

Best practice for recording troubleshooting information in AM (All versions)

Record troubleshooting information

Related Training

N/A

Related Issue Tracker IDs

N/A