Best Practice
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Mar 24, 2021

The purpose of this article is to provide best practice advice on using the recording feature in AM. You can use this to record troubleshooting information, which includes: debug logs, thread dumps (similar output to a JStack stack trace), important run-time properties and the AM configuration.


5 readers recommend this article

Recording AM

This article provides a set of recording examples, which will help you understand this recording feature and investigate AM during everyday usage. We recommend using Postman to manage the REST requests; this tool is easy to use and gives you quick access to your requests to make them easier to re-use.

For further information on this feature, refer to How do I record troubleshooting information in AM (All versions)? and Maintenance Guide › Recording Troubleshooting Information.

Note

Postman uses your browser's cookies; therefore you may need to log out and re-authenticate between Postman tests if you are using the same browser for testing different scenarios.

Installing Postman

First you need to install Postman and then import the required collections.

  1. Install Postman.
  2. Select the Manage Environments option from the Settings cog (No environment drop-down in the top right-hand corner of Postman if you do not have any environments configured). You can then add one or more environments or import this example one to get you started: ForgeRockRecordingExampleEnv.postman_environment

You should avoid including specific environment properties to make it easier to switch between environments without modifying your request. 

If you have multiple AM environments, it is recommended that you create a Postman environment for each one. You can do this by importing the example environment multiple times and then adjusting the values needed. 

The following examples show four AM environments, where only the port number differs:

  1. Import the following collection of example requests: Record AM5.postman_collection.json by clicking the Import button in the top-left hand corner of Postman. You should now have a new collection on the left-hand side of Postman, like this:

By importing this Postman collection and having the correct environment configured, you should be able to use these example requests immediately. If you want to modify one of these requests, it is recommended that you duplicate the request prior to making changes in order to keep these examples intact for future reference.

Using the collection

This section walks through an example scenario using requests within the Postman collection; you can use the other requests in the collection in a similar way. Each request in this collection has a description that outlines what you should know about it. You can copy the example requests you are interested in and modify the request with your data.

This example investigates a configuration issue by comparing the problematic configuration to a similar working configuration. This is a typical use case you might encounter when setting up a policy: You are configuring policy A, which doesn't seem to work yet, but is very similar to policy B which is working. By recording both policy A and B, you can compare AM debug logs to help you understand why policy A isn't working.

  1. Authenticate as the amAdmin user by running the following request: Record AM > Basic Commands > Authenticate and changing the X-OpenAM-Password value. On the Body tab, you should ensure the raw option is selected before you send your request:
  1. Start recording the working policy B by running the following request: Record AM > Configuration issue > Success conf and changing the issueID value; it is recommended that you use the ZenDesk Ticket ID as the issueID when working with ForgeRock Support:
  1. Test policy B. AM records logs for 5 minutes after you have run this request. You can manually stop it after you have tested the policy by running the following request: Record AM > Basic commands > Stop recording or wait until the 5 minutes have elapsed.
Note

You can check the current status of the recording manager by running the request: Record AM > Basic commands > Check status.

  1. Start recording the problematic policy A by running the following request: Record AM > Configuration issue > Failing conf and changing the issueID value.
  2. Test policy A. Again, this records logs for 5 minutes; you can stop it manually after you have tested your policy or wait until the 5 minutes have elapsed.

After recording these two use cases, you should have two folders in your AM /debug directory: record/8888/PolicySuccess and record/8888/PolicyFailure, where 8888 is the issueID and PolicySuccess / PolicyFailure are the referenceIDs used in this example:

Once you have located your recordings, you can compare the debug logs and configurations to investigate your problematic policy. If you need further help from ForgeRock Support, you can attach the recording to your support request as detailed in Sending troubleshooting data to ForgeRock Support for analysis.

See Also

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

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

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


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