[RORDEV-2016] Audit improvements

[mgoworko]

Summary by CodeRabbit

• Documentation
  • Updated audit configuration guide with clarified configuration options and event-serialization behavior.
  • Enhanced logging setup documentation with improved configuration guidance and routing details.
  • Expanded block-level audit control documentation with detailed behavior clarifications.
  • Updated guidance for data stream and index audit outputs.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates details/audit.md to document revised audit configuration semantics: introducing a master audit.enabled switch and audit.default_acl_log_enabled setting, clarifying block-level control behavior, updating output configuration examples for round-robin delivery, substantially expanding the log output section with logger and rolling-file configuration, and refactoring audit serializer documentation to use block-setting-dependent Allowed event serialization modes.

Changes

Audit Configuration and Event Serialization Documentation

Layer / File(s)	Summary
Global audit configuration and block-level control semantics details/audit.md	Introduced audit.default_acl_log_enabled as an explicit control for built-in ACL decision logging and the reserved default_acl_log sink name. Clarified that audit.enabled: false on a matched block suppresses all audit events including the default ACL log, and documented the exclusivity semantics of enabled_audit_sinks vs disabled_audit_sinks.
Index and data stream output configuration and round-robin warnings details/audit.md	Updated both index and data stream output documentation with revised round-robin audit-node delivery warnings and cluster topology constraints. Refreshed configuration snippets for outputs/data_stream field names, updated Kibana verification steps, and aligned migration examples with new data_stream syntax.
Log output section with dedicated logger and file_appender configuration details/audit.md	Substantially rewrote the log output section to document INFO-level logging via a dedicated logger, added file_appender sub-section for self-managed rolling files, clarified custom logger naming and log4j2 wiring with additivity behavior, and documented the new acl serializer with the restriction that it applies only to log outputs.
Audit serializer behavior and allowed_events_serialization_mode configuration details/audit.md	Revised predefined serializer behavior to specify that Allowed event serialization depends on the matched block's log_allowed_events setting. Updated full serializer descriptions to state they serialize Allowed events regardless of block settings. Changed all serializer configuration examples (configurable, ECS, and nested variants) to use allowed_events_serialization_mode: "based_on_block_settings" (replacing prior verbosity-based logic).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• beshu-tech/readonlyrest-docs#292: Updates the audit logger setup and SLF4J2/logging configuration in the same details/audit.md file.
• beshu-tech/readonlyrest-docs#289: Modifies audit enablement semantics and block-level audit event filtering behavior in details/audit.md.
• beshu-tech/readonlyrest-docs#302: Updates audit field representation and serialization/sink behavior documentation in the same audit guide.

Suggested reviewers

• coutoPL

Poem

🐰 Audit logs now clearer, sink routing so fine,
Block-level control and serialization align,
Logger configuration rolling with grace,
Allowed events gated in their rightful place,
Documentation refined, configuration delight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title '[RORDEV-2016] Audit improvements' is generic and vague, using the term 'improvements' without clearly specifying what aspects of audit functionality were actually changed.	Consider a more specific title that describes the main change, such as '[RORDEV-2016] Update audit configuration and event-serialization documentation' or '[RORDEV-2016] Revise audit sink and serializer behavior documentation'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch RORDEV-2016

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@details/audit.md`:
- Line 461: Update the audit docs to use the same log4j2.properties path as
other docs: replace the occurrence of "$ES_PATH_CONF/config/log4j2.properties"
in details/audit.md with "$ES_PATH_CONF/log4j2.properties" and keep the
surrounding guidance about matching the logger name to the logger_name value
(default readonlyrest_audit) intact so references remain consistent with
elasticsearch.md and the debug logging docs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4b6cb9bf-403f-43d8-8dfc-41fd875af9a9

📥 Commits

Reviewing files that changed from the base of the PR and between 9a86134 and 6518c59.

📒 Files selected for processing (1)

• details/audit.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for references to log4j2.properties path in documentation
rg -n "log4j2\.properties" -g "*.md" -C2

Repository: beshu-tech/readonlyrest-docs

Length of output: 2315

---

🏁 Script executed:

#!/bin/bash
# List all occurrences of both path variants and print tight context
rg -n "\$ES_PATH_CONF/(config/)?log4j2\.properties" -g "*.md" -C2

Repository: beshu-tech/readonlyrest-docs

Length of output: 54

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== occurrences of \$ES_PATH_CONF/config/log4j2.properties =="
rg -n "\$ES_PATH_CONF/config/log4j2\.properties" -g "*.md" -C2 || true

echo
echo "== occurrences of \$ES_PATH_CONF/log4j2.properties =="
rg -n "\$ES_PATH_CONF/log4j2\.properties" -g "*.md" -C2 || true

Repository: beshu-tech/readonlyrest-docs

Length of output: 186

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== occurrences of config/log4j2.properties (no $ prefix) =="
rg -n "config/log4j2\.properties" -g "*.md" -C2 || true

echo
echo "== occurrences of log4j2.properties (no config/) =="
rg -n "(^|[^/])log4j2\.properties" -g "*.md" -C2 || true

echo
echo "== show details/audit.md around line ~450-470 =="
nl -ba details/audit.md | sed -n '445,470p'
echo
echo "== show elasticsearch.md around line ~3000-3135 =="
nl -ba elasticsearch.md | sed -n '2985,3150p'

Repository: beshu-tech/readonlyrest-docs

Length of output: 2138

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== details/audit.md around line 461 =="
awk 'NR>=452 && NR<=468 {printf "%d:%s\n", NR, $0}' details/audit.md

echo
echo "== elasticsearch.md around line 3010-3020 =="
awk 'NR>=3008 && NR<=3020 {printf "%d:%s\n", NR, $0}' elasticsearch.md

echo
echo "== elasticsearch.md around line 3110-3120 =="
awk 'NR>=3110 && NR<=3120 {printf "%d:%s\n", NR, $0}' elasticsearch.md

echo
echo "== elasticsearch.md around line 3122-3140 =="
awk 'NR>=3122 && NR<=3140 {printf "%d:%s\n", NR, $0}' elasticsearch.md

Repository: beshu-tech/readonlyrest-docs

Length of output: 2922

---

Align log4j2.properties path in audit docs

• details/audit.md points to $ES_PATH_CONF/config/log4j2.properties, but elsewhere in the docs (elasticsearch.md, debug logging) the path is $ES_PATH_CONF/log4j2.properties. Update details/audit.md to use the same documented path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@details/audit.md` at line 461, Update the audit docs to use the same
log4j2.properties path as other docs: replace the occurrence of
"$ES_PATH_CONF/config/log4j2.properties" in details/audit.md with
"$ES_PATH_CONF/log4j2.properties" and keep the surrounding guidance about
matching the logger name to the logger_name value (default readonlyrest_audit)
intact so references remain consistent with elasticsearch.md and the debug
logging docs.