View audit and debug logs
Overview
Identity Cloud provides audit and debug logs to help you manage your tenant:
-
Use audit logs to investigate user and system behavior.
-
Use debug logs to investigate any issues which may arise in production.
Identity Cloud stores logs for 30 days. Use the /monitoring/logs
endpoint to view the stored
data.
You need to get an API key and secret before you can authenticate to the endpoints.
Sources
Identity Cloud stores logs in various sources, to make browsing them simpler.
The following knowledge base article lists the sources available, and describes their purpose: https://backstage.forgerock.com/knowledge/kb/article/a37739488. The article also lists the default log levels for sources that contain debug logs.
Get sources
To get a list of the available sources, use the /monitoring/logs/sources
endpoint.
Example request:
curl \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
'https://<tenant-env-fqdn>/monitoring/logs/sources'
Example response:
{
"result": [
"<string>",
"<string>"
],
"resultCount": "<integer>",
"pagedResultsCookie": "<string>",
"totalPagedResultsPolicy": "<string>",
"totalPagedResults": "<integer>",
"remainingPagedResults": "<integer>"
}
Identity Cloud returns the available sources in the result
array.
View logs
To view the stored logs for a source, use the /monitoring/logs
endpoint, specifying the source as a parameter.
Example request:
curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-activity' \
'https://<tenant-env-fqdn>/monitoring/logs'
Example response:
{
"result": [
{
"payload": "<object>",
"timestamp": "<dateTime>",
"type": "<string>"
},
{
"payload": "<object>",
"timestamp": "<dateTime>",
"type": "<string>"
}
],
"resultCount": "<integer>",
"pagedResultsCookie": "<string>",
"totalPagedResultsPolicy": "<string>",
"totalPagedResults": "<integer>",
"remainingPagedResults": "<integer>"
}
Identity Cloud returns the available logs in the result
array.
Results are in JSON format, or plaintext, depending on the source you request.
Use the Specify UTC times, in ISO 8601 format. For example:
|
Tail logs
To tail, or view the latest entries in the stored logs for a source, use the /monitoring/logs/tail
endpoint, specifying the source as a parameter.
The first call to the tail endpoint returns results from the last 15 seconds. Subsequent calls (when using _pagedResultsToken
for example) return logs from:
-
Time of last line from previous call to tail
-
Log timestamp
-
Now
You can request results in JSON format or plaintext. One source can have both JSON and
plaintext logs (for example, when you request am-everything
).
Example request:
curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-activity' \
'https://<tenant-env-fqdn>/monitoring/logs/tail'
Example response:
{
"result": [
{
"payload": "<object>",
"timestamp": "<dateTime>",
"type": "<string>"
},
{
"payload": "<object>",
"timestamp": "<dateTime>",
"type": "<string>"
}
],
"resultCount": "<integer>",
"pagedResultsCookie": "<string>",
"totalPagedResultsPolicy": "<string>",
"totalPagedResults": "<integer>",
"remainingPagedResults": "<integer>"
}
You can specify multiple sources in a single call. Example request:
curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-access,idm-access,idm-sync,idm-activity' \
'https://<tenant-env-fqdn>/monitoring/logs/tail'
To keep tailing, take the Example request:
|
Filter logs using a transaction ID
All log events for an external request into Identity Cloud are assigned the same UUID transaction ID. An example of a transaction ID is 918ddc87-791a-480b-acf7-7982b7bea973-16108
.
To filter the logs for a specific transaction ID, add the transactionId
parameter to your API request:
curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=userstore-access&transactionId=<transaction-id>' (1)
'https://<tenant-env-fqdn>/monitoring/logs'
1 | Replace <transaction-id> with a transaction ID |
Add additional fields to audit requests
The following knowledge base article describes how to add additional fields to an audit request: https://backstage.forgerock.com/knowledge/kb/article/a94880145.
Rate limiting
To reduce unwanted stresses on the system, Identity Cloud limits the number of requests you can make to the /monitoring/logs
endpoint in a certain timeframe.
The following rate limit notification headers are sent in the response to each request to the /monitoring/logs
endpoint:
- X-Rate-Limit-Limit
-
The maximum number of requests allowed in the current rate limit window.
- X-Rate-Limit-Remaining
-
The number of requests remaining in the current rate limit window.
- X-Rate-Limit-Reset
-
The time at which the rate limit window is reset, specified in UTC epoch time.