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 beginTime and endTime query parameters to return records created between the two times.

Specify UTC times, in ISO 8601 format.

For example:

curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-activity' \
--data 'beginTime=2020-09-11T09:00:31Z' \
--data 'endTime=2020-09-18T17:30:59Z' \
'https://<tenant-env-fqdn>/monitoring/logs'

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 pagedResultsCookie field and pass it back to the tail endpoint. This retrieves all records stored since that request.

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&_pagedResultsCookie=<pagedResultsCookie>'
'https://<tenant-env-fqdn>/monitoring/logs/tail'

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 page-size limit is 1000 logs per request.
The request limit is 60 requests per minute.
The theoretical upper rate limit is therefore 60,000 logs per minute.

These limits apply per environment, so your development, staging, and production environments each have their own quota.

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.