How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated May 17, 2021

The purpose of this article is to provide information on recording troubleshooting information in AM. You can record troubleshooting information using ssoadm or the REST API. Troubleshooting information includes: debug logs, thread dumps (similar output to a JStack stack trace), important run-time properties and the AM configuration.


2 readers recommend this article

Overview

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

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 Maintenance Guide › Recording 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 Getting the Status of a Recording Event (REST).

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains a valid resource version.

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

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" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/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   }  }' http://host1.example.com:8080/openam/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 Maintenance Guide › Recording 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" http://host1.example.com:8080/openam/json/records?_action=stop
  5. Find your recording, which is located in the /debug/record directory (by default, /path/to/openam/var/debug/record (AM 7 and later) or /path/to/openAM/debug/record (pre-AM 7)) and is stored according to the issueID and referenceID as explained in Maintenance Guide › Retrieving 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 Maintenance Guide › Recording 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 http://host1.example.com:8080/openam -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -J /path/to/recording.json
    • Pre-AM 7: $ ./ssoadm start-recording -s http://host1.example.com:8080/openam -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/"}}

  1. Reproduce the issue for which you want to record troubleshooting information.
  2. 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.
  3. Find your recording, which is located in the /debug/record directory (by default, /path/to/openam/var/debug/record (AM 7 and later) or /path/to/openAM/debug/record (pre-AM 7)) and is stored according to the issueID and referenceID as explained in Maintenance Guide › Retrieving Recording Information.
  4. 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)

Maintenance Guide › Recording Troubleshooting Information

Related Training

N/A

Related Issue Tracker IDs

N/A


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