From 3f480ab011a82610facafca71564ce9a13e410a1 Mon Sep 17 00:00:00 2001
From: Neelesh <neelesh1210@icloud.com>
Date: Fri, 30 Jan 2026 23:43:22 +0530
Subject: [PATCH] GH-4015 Adding documentations for MessageRewritePolicy

---
 .../pages/manual/appenders/delegating.adoc    | 151 +++++++++++++++++-
 1 file changed, 150 insertions(+), 1 deletion(-)

diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc
index 7c783c5c498..166a383dea7 100644
--- a/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/appenders/delegating.adoc
@@ -518,7 +518,156 @@ Rewrite policies allow to apply arbitrary modifications to log events.
 
 xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rewrite-RewritePolicy[{plugin-reference-marker} Plugin reference for `RewritePolicy`]
 
-Log4j Core provides three rewrite policies out-of-the-box:
+Log4j Core provides four rewrite policies out-of-the-box:
+
+[#MessageRewritePolicy]
+`MessageRewritePolicy`::
++
+The `MessageRewritePolicy` allows you to manipulate the text of a log message before it is processed by a downstream appender.
+This is particularly useful for masking sensitive data.
++
+[#MessageRewritePolicy-attributes]
+.`MessageRewritePolicy` configuration attributes
+[cols="1m,1,1,5"]
+|===
+| Attribute | Type | Default value | Description
+
+| [[MessageRewritePolicy-attr-replace]]regex
+| String
+| None
+a|
+A Java-compliant regular expression pattern to match the resulting string in the log message.
+
+| [[MessageRewritePolicy-attr-replace]]replacement
+| String
+| None
+a|
+The string to replace the matched patterns with.
+|===
++
+[#MapRewritePolicy-elements]
+.`MessageRewritePolicy` nested elements
+[cols="1m,1,4"]
+|===
+
+| Type | Multiplicity | Description
+
+| [[MapRewritePolicy-element-replace]]
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-RegexReplacement[`replace`]
+| one or more
+|
+A list of regex and replacement pairs to apply to the message.
+|===
++
+.Configuration example
++
+[tabs]
+====
+XML::
++
+[source,xml,indent=0]
+----
+        <Rewrite name="MASKING_REWRITE">
+            <MessageRewritePolicy>
+                <replace regex="([A-Za-z0-9._%+-])([A-Za-z0-9._%+-]*)(@[A-Za-z0-9.-]+\.[A-Za-z]{2,})"
+                         replacement="[EMAIL]"/>
+                <replace regex="\+?1?\s*\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}"
+                         replacement="[PHONE]"/>
+                <replace> <!-- Uses a CDATA Section -->
+                    <regex><![CDATA[[A-Za-z0-9_%+-]{20,}\.[A-Za-z0-9_%+-]{20,}\.[A-Za-z0-9_%+-]+\b]]></regex>
+                    <replacement>[TOKEN]</replacement>
+                </replace>
+            </MessageRewritePolicy>
+            <Appender-Ref ref="Console"/>
+        </Rewrite>
+----
+
+JSON::
++
+[source,json,indent=0]
+----
+{
+  "Rewrite": [
+    {
+      "name": "MASKING_REWRITE",
+      "MessageRewritePolicy": {
+        "replace": [
+          {
+            "regex": "([A-Za-z0-9._%+-])([A-Za-z0-9._%+-]*)(@[A-Za-z0-9.-]+\\.[A-Za-z]{2,})",
+            "replacement": "[EMAIL MASKED]"
+          },
+          {
+            "regex": "\\+?1?\\s*\\(?\\d{3}\\)?[\\s.-]?\\d{3}[\\s.-]?\\d{4}",
+            "replacement": "[PHONE]"
+          },
+          {
+            "regex": "[A-Za-z0-9_%+-]{20,}\\.[A-Za-z0-9_%+-]{20,}\\.[A-Za-z0-9_%+-]+\\b",
+            "replacement": "[TOKEN]"
+          }
+        ]
+      },
+      "AppenderRef": [
+        {
+          "ref": "Console"
+        }
+      ]
+    }
+  ]
+}
+----
+
+YAML::
++
+[source,yaml,indent=0]
+----
+    rewrite:
+      - name: MASKING_REWRITE
+        MessageRewritePolicy:
+          replace:
+            - regex: "([A-Za-z0-9._%+-])([A-Za-z0-9._%+-]*)(@[A-Za-z0-9.-]+\\.[A-Za-z]{2,})"
+              replacement: "[EMAIL MASKED]"
+            - regex: "\\+?1?\\s*\\(?\\d{3}\\)?[\\s.-]?\\d{3}[\\s.-]?\\d{4}"
+              replacement: "[PHONE]"
+            - regex: "[A-Za-z0-9_%+-]{20,}\\.[A-Za-z0-9_%+-]{20,}\\.[A-Za-z0-9_%+-]+\\b"
+              replacement: "[TOKEN]"
+        AppenderRef:
+          - ref: Console
+----
+
+Properties::
++
+[source,properties,indent=0]
+----
+
+appender.rewrite.type = Rewrite
+appender.rewrite.name = MASKING_REWRITE
+
+# Message Rewrite Policy
+appender.rewrite.policy.type = MessageRewritePolicy
+
+# ---- Replace Rule 1 (Email) ----
+appender.rewrite.policy.replace1.type = replace
+appender.rewrite.policy.replace1.regex = ([A-Za-z0-9._%+-])([A-Za-z0-9._%+-]*)(@[A-Za-z0-9.-]+\\.[A-Za-z]{2,})
+appender.rewrite.policy.replace1.replacement = [EMAIL MASKED]
+
+# ---- Replace Rule 2 (Phone) ----
+appender.rewrite.policy.replace2.type = replace
+appender.rewrite.policy.replace2.regex = \\+?1?\\s*\\(?\\d{3}\\)?[\\s.-]?\\d{3}[\\s.-]?\\d{4}
+appender.rewrite.policy.replace2.replacement = [PHONE]
+
+# ---- Replace Rule 3 (Token) ----
+appender.rewrite.policy.replace3.type = replace
+appender.rewrite.policy.replace3.regex = [A-Za-z0-9_%+-]{20,}\\.[A-Za-z0-9_%+-]{20,}\\.[A-Za-z0-9_%+-]+\\b
+appender.rewrite.policy.replace3.replacement = [TOKEN]
+
+# Attach Console appender
+appender.rewrite.appenderRef.type = AppenderRef
+appender.rewrite.appenderRef.ref = console
+----
+====
+
+:repo-url: https://github.com/Neel1210/log4j-utils/blob/main/src/main/java/in/org/nnm/log4j/utils
+{repo-url}/MessageRewritePolicy.java[{plugin-reference-marker} Plugin reference for `MessageRewritePolicy`]
 
 [#MapRewritePolicy]
 `MapRewritePolicy`::