-
Notifications
You must be signed in to change notification settings - Fork 16k
[Audit Logs] Add Resource History section to Audit Logs v2 page #32078
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: production
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -125,6 +125,80 @@ To create a Logpush job: | |
| 4. In the datasets section, select the [Audit Logs v2 dataset](/logs/logpush/logpush-job/datasets/account/audit_logs_v2/). Audit Logs v2 is an account-based dataset. | ||
| 5. Once you are done configuring your logpush job, select **Submit**. | ||
|
|
||
| ## Resource History | ||
|
|
||
| Resource History shows what changed on every configuration modification captured in Audit Logs. For any audit log entry, you can see the sequence of previous changes to the same resource and view a side-by-side diff of what was modified. | ||
|
|
||
| Resource History is available in the Cloudflare dashboard and via the Audit Logs API. It uses the audit log entries you already have. There is no additional configuration, no backend recapture, and no changes to how audit logs are generated. | ||
|
|
||
| ### What Resource History gives you | ||
|
|
||
| - **Change history for any resource.** Given any audit log entry, retrieve every other audit log entry for the same resource, ordered chronologically. | ||
| - **Field-level before and after.** Compare any two entries in a resource's history to see exactly which fields changed. | ||
|
|
||
| ### Using Resource History in the dashboard | ||
|
|
||
| 1. Go to **Manage Account** > **Audit Logs**. | ||
| 2. Open any audit log entry. | ||
| 3. Select **Change History** to see the full history for the resource that entry describes. | ||
| 4. In the history view, select any two entries to see a side-by-side diff of the fields that changed between them. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. User can select a single entry to compare with the selected log. In other words, the user can change the previous log entry to compare with. |
||
|
|
||
| When Resource History cannot identify the underlying resource (for example, for certain system-initiated events), the dashboard shows an empty state indicating that change history is not available for that entry. | ||
|
|
||
| For a small subset of events, the dashboard may show approximate results (changes to other resources of the same product and type). When this happens, the view displays a warning banner. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. UI doesn't show a warning banner for this. This is used more for internal investigation, so maybe we shouldn't even mention. I suggest we remove this line. |
||
|
|
||
| ### Using Resource History via the API | ||
|
|
||
| You can retrieve the change history for any audit log entry using the History endpoint. Given the `id` of a source audit log entry, the endpoint derives identifying filters from that entry and returns matching audit log entries within a date window you specify. | ||
|
|
||
| For account-scoped audit logs, use: | ||
|
|
||
| ```bash | ||
| GET https://api.cloudflare.com/client/v4/accounts/{account_id}/logs/audit/{id}/history | ||
| ``` | ||
|
|
||
| For organization-scoped audit logs, use: | ||
|
|
||
| ```bash | ||
| GET https://api.cloudflare.com/client/v4/organizations/{organization_id}/logs/audit/{id}/history | ||
| ``` | ||
|
|
||
| The `{id}` path parameter is the `id` of the source audit log entry whose resource history you want to retrieve. | ||
|
|
||
| :::note[Required API token permissions] | ||
| At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required: | ||
|
|
||
| - `Account Settings Read` | ||
| - `Account Settings Write` | ||
| ::: | ||
|
|
||
| The endpoint requires three query parameters: | ||
|
|
||
| - `action_time` (required): RFC3339 timestamp of the source audit log entry's action time. Provide the `action.time` value from the audit log identified by `{id}`. This narrows the source-entry lookup window. | ||
| - `since` (required): Limits returned results to entries newer than this date. Accepts a date string (`2024-10-30`, interpreted as UTC) or an RFC3339 timestamp. | ||
| - `before` (required): Limits returned results to entries older than this date. Same format as `since`. | ||
|
|
||
| Optional query parameters: | ||
|
|
||
| - `direction`: `desc` (default) or `asc`. | ||
| - `limit`: Number of entries to return per page. Default `100`. | ||
| - `cursor`: Pagination cursor from a previous response's `result_info.cursor`. | ||
|
|
||
| <APIRequest | ||
| method="GET" | ||
| path="/accounts/{account_id}/logs/audit/{id}/history" | ||
| /> | ||
|
|
||
| Each entry in `result` has the same shape as an entry returned by the Audit Logs list endpoint. Results are paginated using the `cursor` value in `result_info`. | ||
|
|
||
| The `result_info.history_status` field indicates the quality of resource identification used to build the history: | ||
|
|
||
| - `exact`: The source entry contained a resource URI, so the history was built from an exact resource match. | ||
| - `approximate`: The source entry did not contain a resource URI, so the history was built from an approximate match (other resources of the same product and type). The dashboard surfaces this state with a warning banner. | ||
| - `unavailable`: The source entry did not contain enough information to identify the resource. `result` is empty. This can happen for certain system-initiated events. | ||
|
|
||
| Resource History reflects the audit log entries currently retained by Audit Logs v2 (refer to [Retention](#retention)). Entries older than the retention window are not returned. Resource History is a query-time capability and is not exposed as additional fields in the `audit_logs_v2` Logpush dataset. | ||
|
|
||
| ## Audit Log structure | ||
|
|
||
| Cloudflare's audit logs offer a detailed view of activity across your environment by capturing both the source of actions and the context in which they occur. These logs are categorized by who initiated the action (user or system) and whether the activity occurred within a specific account or spanned multiple accounts under the same user profile. This structure enables flexible filtering, investigation, and compliance monitoring. | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please see the other comment. User cannot select two entries freely. Once they pick the audit log entry, all they can change is the past entry to compare with.