DOC-12277 Add contention examples using crdb_internal.transaction_contention_events

src/current/_includes/v25.1/sidebar-data/optimize-performance.json

@@ -57,6 +57,12 @@
           "/${VERSION}/admission-control.html"
         ]
       },
+      {
+        "title": "Monitor and Analyze Transaction Contention",
+        "urls": [
+          "/${VERSION}/monitor-and-analyze-transaction-contention.html"
+        ]
+      },
       {
         "title": "Performance Tuning Recipes",
         "urls": [

src/current/_includes/v25.1/transaction-contention-events-columns.md

@@ -0,0 +1,17 @@
+Column | Type | Description
+-------|------|------------
+`collection_ts` | `TIMESTAMPTZ NOT NULL` | The timestamp when the transaction [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) event was collected.
+`blocking_txn_id` | `UUID NOT NULL` | The ID of the blocking transaction. You can join this column into the [`cluster_contention_events`]({% link {{ page.version.version }}/crdb-internal.md %}#cluster_contention_events) table.
+`blocking_txn_fingerprint_id` | `BYTES NOT NULL`| The ID of the blocking transaction fingerprint. To surface historical information about the transactions that caused the [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention), you can join this column into the [`statement_statistics`]({% link {{ page.version.version }}/crdb-internal.md %}#statement_statistics) and [`transaction_statistics`]({% link {{ page.version.version }}/crdb-internal.md %}#transaction_statistics) tables.
+`waiting_txn_id` | `UUID NOT NULL` | The ID of the waiting transaction. You can join this column into the [`cluster_contention_events`]({% link {{ page.version.version }}/crdb-internal.md %}#cluster_contention_events) table.
+`waiting_txn_fingerprint_id` | `BYTES NOT NULL` | The ID of the waiting transaction fingerprint. To surface historical information about the transactions that caused the [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention), you can join this column into the [`statement_statistics`]({% link {{ page.version.version }}/crdb-internal.md %}#statement_statistics) and [`transaction_statistics`]({% link {{ page.version.version }}/crdb-internal.md %}#transaction_statistics) tables.
+`waiting_stmt_id` | `STRING NOT NULL` | The statement id of the transaction that was waiting (unique for each statement execution).
+`waiting_stmt_fingerprint_id` | `BYTES NOT NULL` | The ID of the waiting statement fingerprint. To surface historical information about the statements that caused the [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention), you can join this column into the [`statement_statistics`]({% link {{ page.version.version }}/crdb-internal.md %}#statement_statistics) table.
+`contention_duration` | `INTERVAL NOT NULL` | The interval of time the waiting transaction spent waiting for the blocking transaction.
+`contending_key` | `BYTES NOT NULL` | The key on which the transactions contended.
+`contending_pretty_key` | `STRING NOT NULL` | The specific key that was involved in the contention event, in readable format.
+`database_name` | `STRING NOT NULL` | The database where the contention occurred.
+`schema_name` | `STRING NOT NULL` | The schema where the contention occurred.
+`table_name` | `STRING NOT NULL` | The table where the contention occurred.
+`index_name` | `STRING NULL` | The index where the contention occurred.
+`contention_type` | `STRING NOT NULL` | The type of contention. Possible values:<ul><li>`LOCK_WAIT`: Indicates that the transaction waited on a specific key. The record includes the key and the wait duration.</li><li>`SERIALIZATION_CONFLICT`: Represents a serialization conflict specific to a transaction execution. This is recorded only when a [client-side retry error]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}) containing the conflicting transaction details is emitted.</li></ul>After recording, the `contention_type` is not modified. A transaction may have multiple `LOCK_WAIT` events, as they correspond to specific keys, but only one `SERIALIZATION_CONFLICT` event.

src/current/v25.1/crdb-internal.md

@@ -1173,15 +1173,7 @@ Contention events are stored in memory. You can control the amount of contention
 
 The `sql.contention.event_store.duration_threshold` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) specifies the minimum contention duration to cause the contention events to be collected into the `crdb_internal.transaction_contention_events` table. The default value is `0`. If contention event collection is overwhelming the CPU or memory you can raise this value to reduce the load.
 
-Column | Type | Description
-------------|-----|------------
-`collection_ts` | `TIMESTAMPTZ NOT NULL` | The timestamp when the transaction [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention) event was collected.
-`blocking_txn_id` | `UUID NOT NULL` | The ID of the blocking transaction. You can join this column into the [`cluster_contention_events`](#cluster_contention_events) table.
-`blocking_txn_fingerprint_id` | `BYTES NOT NULL`| The ID of the blocking transaction fingerprint. To surface historical information about the transactions that caused the [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention), you can join this column into the [`statement_statistics`](#statement_statistics) and [`transaction_statistics`](#transaction_statistics) tables to surface historical information about the transactions that caused the contention.
-`waiting_txn_id` | `UUID NOT NULL` | The ID of the waiting transaction. You can join this column into the [`cluster_contention_events`](#cluster_contention_events) table.
-`waiting_txn_fingerprint_id` | `BYTES NOT NULL` | The ID of the waiting transaction fingerprint. To surface historical information about the transactions that caused the [contention]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#transaction-contention), you can join this column into the [`statement_statistics`](#statement_statistics) and [`transaction_statistics`](#transaction_statistics) tables.
-`contention_duration` | `INTERVAL NOT NULL` | The interval of time the waiting transaction spent waiting for the blocking transaction.
-`contending_key` | `BYTES NOT NULL` | The key on which the transactions contended.
+{% include {{ page.version.version }}/transaction-contention-events-columns.md %}
 
 #### Transaction contention - example