This is an automated email from the ASF dual-hosted git repository.
alex-plekhanov pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new b2eb30b6351 IGNITE-28859 Documentation: Add section about LRT
diagnostics and termination (#13339)
b2eb30b6351 is described below
commit b2eb30b635181db1c0b546de6ef273795b660ae6
Author: Andrey Nadyktov <[email protected]>
AuthorDate: Wed Sep 23 13:17:28 2026 +0300
IGNITE-28859 Documentation: Add section about LRT diagnostics and
termination (#13339)
---
.../code-snippets/dotnet/PerformingTransactions.cs | 14 ++++
.../ignite/snippets/PerformingTransactions.java | 24 +++++-
docs/_docs/code-snippets/xml/transactions.xml | 6 ++
docs/_docs/key-value-api/transactions.adoc | 89 +++++++++++++++++++++-
4 files changed, 126 insertions(+), 7 deletions(-)
diff --git a/docs/_docs/code-snippets/dotnet/PerformingTransactions.cs
b/docs/_docs/code-snippets/dotnet/PerformingTransactions.cs
index 3284905fc31..c83b03d4336 100644
--- a/docs/_docs/code-snippets/dotnet/PerformingTransactions.cs
+++ b/docs/_docs/code-snippets/dotnet/PerformingTransactions.cs
@@ -148,5 +148,19 @@ namespace dotnet_helloworld
Ignition.Start(cfg);
// end::pmeTimeout[]
}
+
+ public static void TxTimeout()
+ {
+ // tag::txTimeout[]
+ var cfg = new IgniteConfiguration
+ {
+ TransactionConfiguration = new TransactionConfiguration
+ {
+ DefaultTimeout = TimeSpan.FromSeconds(300)
+ }
+ };
+ Ignition.Start(cfg);
+ // end::txTimeout[]
+ }
}
}
diff --git
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/PerformingTransactions.java
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/PerformingTransactions.java
index 8a22e81430e..d8ee974e759 100644
---
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/PerformingTransactions.java
+++
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/PerformingTransactions.java
@@ -166,8 +166,26 @@ public class PerformingTransactions {
}
}
- void timeout() {
- // tag::timeout[]
+ void defaultTimeout() {
+ // tag::default[]
+ // Create a configuration
+ IgniteConfiguration cfg = new IgniteConfiguration();
+
+ // Create a Transaction configuration
+ TransactionConfiguration txCfg = new TransactionConfiguration();
+
+ // Set the timeout to 5 minutes
+ txCfg.setDefaultTxTimeout(300000);
+
+ cfg.setTransactionConfiguration(txCfg);
+
+ // Start the node
+ Ignition.start(cfg);
+ // end::default[]
+ }
+
+ void pmeTimeout() {
+ // tag::pme[]
// Create a configuration
IgniteConfiguration cfg = new IgniteConfiguration();
@@ -181,7 +199,7 @@ public class PerformingTransactions {
// Start the node
Ignition.start(cfg);
- // end::timeout[]
+ // end::pme[]
}
public static void deadlockDetectionExample() {
diff --git a/docs/_docs/code-snippets/xml/transactions.xml
b/docs/_docs/code-snippets/xml/transactions.xml
index ec85cfda970..5e5afd6822f 100644
--- a/docs/_docs/code-snippets/xml/transactions.xml
+++ b/docs/_docs/code-snippets/xml/transactions.xml
@@ -31,8 +31,14 @@
<!-- tag::configuration[] -->
<property name="transactionConfiguration">
<bean
class="org.apache.ignite.configuration.TransactionConfiguration">
+ <!-- tag::timeout[] -->
+ <!--Set the timeout to 5 minutes-->
+ <property name="defaultTxTimeout" value="300000" />
+ <!-- end::timeout[] -->
+ <!-- tag::pme[] -->
<!--Set the timeout to 20 seconds-->
<property name="TxTimeoutOnPartitionMapExchange"
value="20000"/>
+ <!-- end::pme[] -->
</bean>
</property>
diff --git a/docs/_docs/key-value-api/transactions.adoc
b/docs/_docs/key-value-api/transactions.adoc
index 2297e1e9a25..4d631ab9ee4 100644
--- a/docs/_docs/key-value-api/transactions.adoc
+++ b/docs/_docs/key-value-api/transactions.adoc
@@ -204,7 +204,26 @@ Only during the commit phase, in case of any conflict, a
`TransactionOptimisticE
IMPORTANT: If you are not using PESSIMISTIC REPEATABLE_READ or SERIALIZABLE
transactions or OPTIMISTIC SERIALIZABLE transactions, then it is possible to
see a partial transaction state. This means that if one transaction updates
objects A and B, then another transaction may see the new value for A and the
old value for B.
+== Transactions Statuses
+A transaction, from its initiation to its completion via commit or rollback,
goes through several statuses as required by the two-phase commit protocol
(2-phase commit, 2PC):
+[cols="15%,10%,75%"]
+|===
+| Transaction Status | 2PC Phase | Description
+| `ACTIVE` | — | The user created a transaction using the `txStart(...)`
method; the `commit`/`rollback` methods have not been called
+| `PREPARING` | `PREPARE` | The user called the `commit` method on the
transaction; the 2PC protocol has started the preparation phase
+| `PREPARED` | `PREPARE` | The 2PC protocol has completed the preparation
phase (nodes participating in the transaction have sent notifications of
readiness to commit)
+| `COMMITTING` | `COMMIT` | The 2PC protocol has started the final commit
phase and sent the commit command to the nodes
+| `COMMITTED` | `COMMIT` | The 2PC protocol has received responses from all
nodes; the transaction commit is complete, and its context is being cleared
+| `MARKED_ROLLBACK` | `PREPARE`/`COMMIT` | The user called the `rollback`
method on the transaction; the 2PC protocol has started the rollback procedure
+| `ROLLING_BACK` | `PREPARE`/`COMMIT` | The 2PC protocol has sent rollback
requests to the nodes participating in the transaction
+| `ROLLED_BACK` | `PREPARE`/`COMMIT` | The 2PC protocol has received responses
from all nodes; the rollback is complete, and the transaction context is being
cleared
+| `SUSPENDED` | — | The transaction is suspended. This can occur in two cases:
upon explicit user request by calling the `suspend` method on the `Transaction`
object, or when starting a transaction using a thin client. In this case, the
transaction is immediately moved to the `SUSPENDED` status after creation and
exits it upon receiving subsequent requests from the client
+| `UNKNOWN` | — | An error occurred during rollback or transaction processing;
the state is unknown
+|===
+== Transaction Lifecycle
+* Transaction with a successful commit: `ACTIVE` → `PREPARING` → `PREPARED` →
`COMMITTING` → `COMMITTED`.
+* Transaction that rolled back due to one of the nodes being unready to
commit: `ACTIVE` → `PREPARING` → `ROLLING_BACK` → `ROLLED_BACK`.
== Deadlock Detection
@@ -322,6 +341,69 @@ A transaction might fail with the following exceptions:
== Long Running Transactions Termination
+The `tx` command of the `control.sh` utility allows you to search for
transactions based on various criteria (such as ID, duration, or label) and
roll back transactions. Since transactions in Apache Ignite are generally
distributed (multiple nodes are involved in processing a single transaction),
this command may display the same transaction as present on multiple nodes
simultaneously.
+
+Rolling back a transaction using the `tx` command is only possible for the
`ACTIVE`, `PREPARING`, and `PREPARED` statuses. A transaction in statuses
related to the `rollback` procedure is already in the process of rolling back.
Transactions in the `COMMITTING` and `COMMITTED` statuses cannot be rolled back
due to 2PC protocol restrictions.
+
+To look if there are any long running transactions, execute the `control.sh
--tx --min-duration <transaction_duration_seconds>` command. Example output:
++
+----
+Command [TX] started
+Arguments: --tx --min-duration 30
+--------------------------------------------------------------------------------
+Matching transactions:
+TcpDiscoveryNode [id=<id>, addrs=[<address>], order=1,
ver=2.18.0#YYYYMMDD-sha1:00000000, isClient=false,
consistentId=gridCommandHandlerTest0]
+ Tx: [xid=<id>, label=null, state=ACTIVE, startTime=YYYY-MM-DD
15:15:16.852, duration=3 sec, isolation=REPEATABLE_READ,
concurrency=PESSIMISTIC, topVer=AffinityTopologyVersion [topVer=3,
minorTopVer=2], timeout=0 sec, size=100, dhtNodes=[<id>, <id>], nearXid=<id>,
parentNodeIds=[<id>]]
+ Tx: [xid=<id>, label=null, state=ACTIVE, startTime=YYYY-MM-DD
15:15:16.852, duration=3 sec, isolation=REPEATABLE_READ,
concurrency=PESSIMISTIC, topVer=AffinityTopologyVersion [topVer=3,
minorTopVer=2], timeout=0 sec, size=100, dhtNodes=[<id>, <id>], nearXid=<id>,
parentNodeIds=[<id>]]
+Command [TX] finished with code: 0
+----
+To cancel the transactions, whose execution time takes longer than expected,
use the `control.sh --tx --min-duration <transaction_duration_seconds> --kill`
command. For example, to cancel the transactions that have been running for
more than 100 seconds, execute the following command:
+[source, shell]
+----
+control.sh --tx --min-duration 100 --kill
+----
+
+== Causes of LRT
+* High system load, which leads to slower transaction processing. Indicators:
+** log messages about the start of page eviction for in-memory data regions or
page replacement for persistent data regions;
+** growth of queues in the striped pool;
+** increased checkpoint duration for clusters with persistence enabled;
+** high cpu or disk utilization;
+** increased latency of cache operation;
+** long GC pauses.
+* Unstable network operation. Indicators: log messages about connection loss
between nodes, socket closures, or network timeouts triggering.
+* Resource-intensive operations (for example, deleting a cache that is part of
a cache group, snapshots execution, index rebuild, rebalancing, etc.).
+* Deadlocks during transaction execution. Indicators: message `Deadlock
detected` on the node that initiated the transaction.
+* Java-level deadlocks caused by internal Apache Ignite bugs or incorrect
server configuration. Indicators: thread dumps showing threads waiting for
locks held by other threads; over time, the thread state doesn't change (stack
trace remains unchanged). Some but not all deadlocks can be automatically
discovered by the thread dumps deadlock detector. In other cases, e.g., when
deadlocks are caused by thread pool starvation, pay attention to `pool
starvation` messages in logs.
+
+== Transaction Timeout
+
+=== Default Transaction Timeout
+`TransactionConfiguration#setDefaultTxTimeout` — default transaction timeout
(used when user code starts a transaction without specifying a timeout). If a
transaction execution exceeds this time, the cluster attempts to roll it back.
If the transaction state does not allow a rollback, the timeout will have no
effect.
+
+Example:
+
+[tabs]
+--
+tab:XML[]
+[source,xml]
+----
+include::code-snippets/xml/transactions.xml[tags=ignite-config;configuration;timeout;!pme;!cache;!discovery,
indent=0]
+----
+tab:Java[]
+[source,java]
+----
+include::{javaFile}[tag=default,indent=0]
+----
+tab:C#/.NET[]
+[source,csharp]
+----
+include::code-snippets/dotnet/PerformingTransactions.cs[tag=txTimeout,indent=0]
+----
+tab:C++[unsupported]
+--
+
+=== Timeout on Partition Map Exchange
Some cluster events trigger partition map exchange process and data
rebalancing within an Ignite cluster to ensure even data distribution
cluster-wide. An example of one such event is the cluster-topology-change event
that takes place whenever a new node joins the cluster or an existing one
leaves it. Plus, every time a new cache or SQL table is created, the partition
map exchange gets triggered.
@@ -330,20 +412,19 @@ When the partition map exchange starts, Ignite acquires a
global lock at a parti
Use the `TransactionConfiguration.setTxTimeoutOnPartitionMapExchange(...)`
method to set the maximum time allowed for your long-running transactions to
block the partition map exchange.
Once the timeout fires, all incomplete transactions are rolled back letting
the partition map exchange proceed.
-This example shows how to configure the timeout:
-
+Example:
[tabs]
--
tab:XML[]
[source,xml]
----
-include::code-snippets/xml/transactions.xml[tags=ignite-config;configuration;!cache;!discovery,
indent=0]
+include::code-snippets/xml/transactions.xml[tags=ignite-config;configuration;!timeout;!cache;!discovery,
indent=0]
----
tab:Java[]
[source,java]
----
-include::{javaFile}[tag=timeout,indent=0]
+include::{javaFile}[tag=pme,indent=0]
----
tab:C#/.NET[]
[source,csharp]
