Updates Custom fields (#21740)

Author: angelampcosta

src/content/docs/logs/reference/custom-fields.mdx

@@ -6,10 +6,23 @@ sidebar:
 
 ---
 
-You can configure custom fields — selected from the list of HTTP request headers, HTTP response headers, and cookies — to include in Logpush log entries of a zone. Custom fields are only available for the [HTTP requests dataset](/logs/reference/log-fields/zone/http_requests/). Once configured, these custom fields will be enabled for all the Logpush jobs in the zone that use the HTTP requests dataset and include the request headers, response headers, or cookie fields.
+The HTTP requests dataset includes most standard log information by default. However, if you need to capture additional request or response headers or cookies, you can use custom fields to tailor the logs to your specific needs
+
+Custom fields are configured per zone and, once set up, are enabled for all Logpush jobs in that zone that use the HTTP requests dataset and include the request headers, response headers, or cookie fields. You can log these fields in their raw form or as transformed values.
+
+:::note[By default:]
+- **Request headers** are logged as **raw values**.
+- **Response headers** are logged as **transformed values**.
+:::
+
+This default behavior can be changed. You can configure either request or response headers to be logged as raw or transformed, depending on your needs -  but not both for the same header. 
 
 Custom fields can be enabled via API or the Cloudflare dashboard.
 
+:::note
+Custom fields are only available for the [HTTP requests dataset](/logs/reference/log-fields/zone/http_requests/).
+:::
+
 ## Enable custom rules via API
 
 Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create a rule that configures custom fields. For more information on concepts like phases, rulesets, and rules, as well as the available API operations, refer to the [Ruleset Engine](/ruleset-engine/) documentation.
@@ -27,20 +40,22 @@ The `action_parameters` object that you must include in the rule that configures
 
 ```json
 "action_parameters": {
+//select raw (default) or transformed request header
   "request_fields": [
-    { "name": "<http_request_header_name_1_in_lower_case>" },
-    { "name": "<http_request_header_name_2_in_lower_case>" },
-    // ...
+    { "name": "<http_request_header_raw>" }
   ],
+  "transformed_request_fields": [
+    { "name": "<http_request_header_transformed>" }
+  ],
+//select raw or transformed (default) response header   
   "response_fields": [
-    { "name": "<http_response_header_name_1_in_lower_case>" },
-    { "name": "<http_response_header_name_2_in_lower_case>" },
-    // ...
+    { "name": "<http_response_header_transformed>" }
+  ],
+  "raw_response_fields": [
+    { "name": "<http_response_header_raw>" }
   ],
   "cookie_fields": [
-    { "name": "<cookie_name_1>" },
-    { "name": "<cookie_name_2>" },
-    // ...
+    { "name": "<cookie_name>" }
   ]
 }
 ```
@@ -51,6 +66,7 @@ Ensure that your rule definition complies with the following:
 * You must enter HTTP request and response header names in lower case.
 * Cookie names are case sensitive — you must enter cookie names with the same capitalization they have in the HTTP request.
 * You must set the rule expression to `true`.
+* You can only log raw or transformed values for either request or response headers but not both for the same header. 
 
 Perform the following steps to create the rule:
 
@@ -101,11 +117,14 @@ Perform the following steps to create the rule:
            "request_fields": [
              { "name": "content-type" },
              { "name": "x-forwarded-for" },
-             { "name": "host" }
            ],
+         "transformed_request_fields": [
+             {"name": "host"}
+          ],
            "response_fields": [
              { "name": "server" },
              { "name": "content-type" },
+         "raw_response_fields": [
              { "name": "allow" }
            ],
            "cookie_fields": [
@@ -138,11 +157,13 @@ Perform the following steps to create the rule:
              "request_fields": [
                { "name": "content-type" },
                { "name": "x-forwarded-for" },
+           "transformed_request_fields": [
                { "name": "host" }
              ],
              "response_fields": [
                { "name": "server" },
                { "name": "content-type" },
+           "raw_response_fields": [    
                { "name": "allow" }
              ],
              "cookie_fields": [
@@ -212,3 +233,4 @@ If you are a Cloudflare Access user, as of March 2022 you have to manually add t
 * For headers which may be included multiple times (for example, the `set-cookie` response header), a custom field will only log the first instance of the header. Subsequent headers of the same type will be ignored.
 * Currently, Cloudflare only logs original request/response headers. Headers that were modified earlier in the request lifecycle with [Transform Rules](/rules/transform/) will not be logged.
 * The request header `Range` is currently not supported by Custom Fields.
+* Transformed and raw values for request and response headers are available only via the API and cannot be set through the UI.