DOC-12484 XDCR Conflict Logging feature

modules/ROOT/nav.adoc

@@ -82,6 +82,10 @@ include::third-party:partial$nav.adoc[]
     **** xref:learn:clusters-and-availability/xdcr-filtering.adoc[XDCR Advanced Filtering]
     **** xref:learn:clusters-and-availability/xdcr-conflict-resolution.adoc[XDCR Conflict Resolution]
     **** xref:learn:clusters-and-availability/xdcr-with-scopes-and-collections.adoc[XDCR with Scopes and Collections]
+    **** xref:learn:clusters-and-availability/xdcr-enable-crossclusterversioning.adoc[XDCR enableCrossClusterVersioning]
+    **** xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc[XDCR Conflict Logging]
+      ***** xref:learn:clusters-and-availability/xdcr-viewing-conflict-logs.adoc[Viewing Conflict Logs]
+    **** xref:learn:clusters-and-availability/xdcr-active-active-sgw.adoc[XDCR Active-Active with Sync Gateway]
   *** xref:learn:clusters-and-availability/groups.adoc[Server Group Awareness]
 * xref:learn:security/security-overview.adoc[Security]
  ** xref:learn:security/authentication.adoc[Authentication]

modules/introduction/partials/new-features-80.adoc

@@ -113,6 +113,11 @@ Additional information sent by clients at connection time can be found in the lo
 https://jira.issues.couchbase.com/browse/MB-61048[MB-61048]::
 Once faulty remote cluster credentials are fixed, XDCR will now be able to more quickly restart replications that depend on the repaired references.
 
+https://jira.issues.couchbase.com/browse/MB-58989[MB-58989]::
+XDCR detects and logs concurrent conflicts that occur in different clusters but on the same document version due to independent modifications by locally connected applications during Active-Active replication.
+The conflict logs are for your information only.
+For more information, see xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc[XDCR Conflict Logging Feature].
+
 [#section-new-feature-800-query-service]
 === Query Service
 

modules/learn/pages/clusters-and-availability/conflictlogging-examples.adoc

@@ -0,0 +1,147 @@
+[#conflictlogging-key]
+==== conflictLogging key
+
+`conflictLogging` is the replication setting key.
+The types of values for `conflictLogging` are as follows:
+
+* xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#enabled-for-all-conflicts[Enabled for all conflicts]
+
+* xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#enabled-with-special-logging-rules[Enabled with special logging rules]
+
+* xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#disabled-with-stored-logging-rules[Disabled with stored logging rules]
+
+* xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#disabled-conflict-logging[Disabled]
+
+NOTE: The conflict logs are not replicated because XDCR adds a hidden system xattribute flag called `_xdcr_conflict` into each of the conflict logs (xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc#conflict-record[Conflict Records]) stored in conflict collection.
+This attribute prevents conflict logs from replicating to the target.
+
+`conflictLogging` details, value format, and examples are as follows.
+
+[#enabled-for-all-conflicts]
+===== Enabled for all conflicts
+
+To log all conflicts to the same collection for the entire replication:
+
+. Enable conflict logging by setting `disabled` to `false`.
+
+. Designate a default conflict collection by specifying the conflict log bucket and the conflict log collection in `bucket` and `collection`.
+
+NOTE: You can designate any regular collection as the conflict collection, including collections that are a part of the replication.
+
+*Format:*
+[source,json]
+----
+--data-urlencode conflictLogging= '{
+                        "disabled": false,
+                        "bucket": [bucketName],
+                        "collection": [scope].[collection],
+                        }'
+----
+
+*Example:* Conflict logging is enabled, and the default conflict collection is `conflictlogsbucket.myappscope.log1collection`. 
+All conflicts in the replication will be logged to the default conflict collection.
+
+[source,json]
+----
+--data-urlencode conflictLogging= '{
+                        "disabled": false,
+                        "bucket": "conflictlogsbucket",
+                        "collection": "myappscope.log1collection"
+                        }'
+----
+
+[#enabled-with-special-logging-rules]
+===== Enabled with special logging rules
+
+To specify different conflict collection rules for different scopes and collections in your replication, define `loggingRules` in the `conflictLogging` settings. 
+
+You can use `loggingRules` to specify, for any scope or collection in the replication, whether the conflicts from that scope or collection must be logged to a different conflict collection or not.  
+If you do not specify in the logging rules, then by default, the conflicts from all collections are logged to the default conflict collection.
+
+*Format:*
+[source,json]
+----
+--data-urlencode conflictLogging= '{
+                    "disabled": false,
+                    "bucket": [bucketName],
+                    "collection": [scope].[collection],
+                    "loggingRules": {[logging_rules]},
+                    }'
+----
+
+*Example:* Conflict logging is enabled. The default conflict collection is the same as in the previous example, however, `loggingRules` is added. 
+The `conflictLogging` setting defines the following rules:
+
+* Conflict logs for the collection `agents.partners` must be logged to a different collection called `conflictlogsbucket2.myappscope.partnerlogs`
+
+* Conflicts must not be logged in the collection `agents.retailers`.
+
+* Conflict logs for the `inventory` scope must be logged to a collection called `conflictlogsbucket2.myappscope.inventorylogs`.
+
+[source,json]
+----
+--data-urlencode conflictLogging= '{
+"disabled": false,
+"bucket": "conflictlogsbucket1",
+"collection": "myappscope.log1collection"
+"loggingRules": {
+      "agents.partners": {
+        "bucket": "conflictlogsbucket2",
+        "collection": "myappscope.partnerlogs"
+      },
+      "agents.retailers": null,
+      "inventory": {
+        "bucket": "conflictlogsbucket2",
+        "collection": "myappscope.inventorylogs"
+      }
+    }
+}'
+----
+
+[#disabled-with-stored-logging-rules]
+===== Disabled with stored logging rules
+
+You can configure `conflictLogging` (specify the default conflict collection and the `loggingRules`) but not enable `conflictLogging` by setting `disabled` to `true`. 
+
+NOTE: You can update the replication and set the `conflictLogging` status `disabled` to `true` or `false` at any time.
+
+When you set `"disabled": true`, it also disables conflict logging, but all of the rules are retained for the collection.
+
+*Format:*
+
+[source,json]
+----
+--data-urlencode conflictLogging= '{
+                    "bucket": [bucketName],
+                    "collection": [scope].[collection],
+                    "loggingRules": {[logging_rules]},
+                    "disabled": true,
+}'
+----
+
+*Example:* Conflict logging is disabled, but the default conflict collection and the logging rules are retained.
+
+[source,json]
+----
+--data-urlencode conflictLogging= '{
+                    "disabled": true,
+                    "bucket": "conflictlogsbucket1",
+                    "collection": "myappscope.log1collection",
+                    "loggingRules": {
+                        "agents.partners": {
+                        "bucket": "conflictlogsbucket2",
+                        "collection": "myappscope.partnerlogs"
+                    },
+                    "agents.retailers": null,
+                    "inventory": {
+                        "bucket": "conflictlogsbucket2",
+                        "collection": "myappscope.inventorylogs"
+                    }
+            }
+}'
+----
+
+[#disabled-conflict-logging]
+===== Disabled
+
+To disable conflict logging, set `--data-urlencode conflictLogging='{}'`.