Skip to content

[Audit Logs] Add Resource History section to Audit Logs v2 page#32078

Open
Sahidya wants to merge 2 commits into
cloudflare:productionfrom
Sahidya:audit-logs/resource-history-docs
Open

[Audit Logs] Add Resource History section to Audit Logs v2 page#32078
Sahidya wants to merge 2 commits into
cloudflare:productionfrom
Sahidya:audit-logs/resource-history-docs

Conversation

@Sahidya

@Sahidya Sahidya commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Adds a new Resource History section to the Audit Logs v2 documentation page, covering both the dashboard experience and the History API endpoint.

What this adds

  • Overview of Resource History — what it does, how it uses existing audit log entries, no additional configuration needed.
  • Dashboard usage — step-by-step for viewing change history and side-by-side diffs from any audit log entry.
  • API usage — full documentation of the GET .../logs/audit/{id}/history endpoint for account and organization scopes.

API section details

  • Path parameter: {id} (the source audit log entry).
  • Required query parameters: action_time, since, before.
  • Optional query parameters: direction, limit, cursor.
  • Required token permissions: Account Settings Read or Account Settings Write.
  • history_status values documented: exact, approximate, unavailable.
  • <APIRequest> component renders the request/response schema directly from the OpenAPI spec.

Also bumps the pinned api-schemas commit

src/util/api.ts is bumped from 082fe875… to 25d60329… so the History endpoint resolves in <APIRequest>. This matches the pending automated bot PR #31888. If #31888 lands first, this change becomes a no-op.

Validation

Ran locally against the full CI pipeline:

  • pnpm run check (Astro + Worker tsc): 0 errors
  • Prettier: pass
  • pnpm run build with RUN_LINK_CHECK=true: 8,636 pages, all internal links valid

Sahidya added 2 commits July 9, 2026 13:26
- Fix path parameter from {audit_log_id} to {id} to match spec.
- Document required query params: action_time, since, before.
- Document optional query params: direction, limit, cursor.
- Correct history_status values to exact, approximate, unavailable.
- Remove hand-written response example; APIRequest renders from schema.
- Bump pinned api-schemas commit so History endpoint resolves.
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Review

⚠️ 3 warnings, 💡 1 suggestion found in commit 76500d3.

Fix in your agent
Fix the following review findings in PR #32078 (https://github.com/cloudflare/cloudflare-docs/pull/32078).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, fix all legitimate findings. For any you decide to skip,
post a comment on this PR with the finding ID and your reasoning.

---

## Code Review

### Warnings (1)

#### CR-743752e6d560 · Malformed aside closing marker
- **File:** `src/content/docs/fundamentals/account/account-security/audit-logs.mdx` line 173
- **Issue:** The closing `:::` for the `:::note[Required API token permissions]` aside is indented with two spaces (`  :::`). Starlight aside delimiters need to be at the start of a line; an indented closing marker can prevent the aside from closing correctly.
- **Fix:** Move the closing `:::` to the start of the line so it matches the opening delimiter and the aside renders correctly.

---

## Style Guide Review

### Warnings (2)

#### SG-d2169bc98d6c · Heading begins with -ing verb
- **File:** `src/content/docs/fundamentals/account/account-security/audit-logs.mdx` line 139
- **Issue:** Added heading `### Using Resource History in the dashboard` starts with `Using`
- **Fix:** Use imperative form: `### Use Resource History in the dashboard`

#### SG-3e01da80cea3 · Heading begins with -ing verb
- **File:** `src/content/docs/fundamentals/account/account-security/audit-logs.mdx` line 150
- **Issue:** Added heading `### Using Resource History via the API` starts with `Using`
- **Fix:** Use imperative form: `### Use Resource History via the API`

### Suggestions (1)

#### SG-7a9c95d55f99 · Bullet list has fewer than three items
- **File:** `src/content/docs/fundamentals/account/account-security/audit-logs.mdx` line 136
- **Issue:** Added bullet list under `### What Resource History gives you` contains only two items
- **Fix:** Consider writing the two items as prose instead of a bulleted list

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (1)
File Issue
fundamentals/account/account-security/audit-logs.mdx line 173 Malformed aside closing marker — The closing ::: for the :::note[Required API token permissions] aside is indented with two spaces ( :::). Starlight aside delimiters need to be at the start of a line; an indented closing marker can prevent the aside from closing correctly. Fix: Move the closing ::: to the start of the line so it matches the opening delimiter and the aside renders correctly.

Conventions

No convention issues found.

Style Guide Review

Warnings (2)
File Issue
fundamentals/account/account-security/audit-logs.mdx line 139 Heading begins with -ing verb — Added heading ### Using Resource History in the dashboard starts with Using Fix: Use imperative form: ### Use Resource History in the dashboard
fundamentals/account/account-security/audit-logs.mdx line 150 Heading begins with -ing verb — Added heading ### Using Resource History via the API starts with Using Fix: Use imperative form: ### Use Resource History via the API
Suggestions (1)
File Issue
fundamentals/account/account-security/audit-logs.mdx line 136 Bullet list has fewer than three items — Added bullet list under ### What Resource History gives you contains only two items Fix: Consider writing the two items as prose instead of a bulleted list
Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command Description
/review Runs a review now. Incremental if a prior review exists, full if not.
/full-review Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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.

### 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.

Copy link
Copy Markdown
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants