feat docs: document the long transaction detection

Tests: на прод не влияет
commit_hash:60bf568b8b4533be246d4a25774c122ac8a55160

Author: apolukhin

.mapping.json

@@ -4412,6 +4412,7 @@
   "scripts/docs/en/userver/libraries/s3api.md":"taxi/uservices/userver/scripts/docs/en/userver/libraries/s3api.md",
   "scripts/docs/en/userver/log_level_running_service.md":"taxi/uservices/userver/scripts/docs/en/userver/log_level_running_service.md",
   "scripts/docs/en/userver/logging.md":"taxi/uservices/userver/scripts/docs/en/userver/logging.md",
+  "scripts/docs/en/userver/long_transactions.md":"taxi/uservices/userver/scripts/docs/en/userver/long_transactions.md",
   "scripts/docs/en/userver/lru_cache.md":"taxi/uservices/userver/scripts/docs/en/userver/lru_cache.md",
   "scripts/docs/en/userver/memory_profile_running_service.md":"taxi/uservices/userver/scripts/docs/en/userver/memory_profile_running_service.md",
   "scripts/docs/en/userver/mongodb.md":"taxi/uservices/userver/scripts/docs/en/userver/mongodb.md",

core/include/userver/utils/trx_tracker.hpp

@@ -1,6 +1,6 @@
 #pragma once
 
-/// @file
+/// @file userver/utils/trx_tracker.hpp
 /// @brief Tracking for heavy operations while having active transactions.
 
 #include <optional>
@@ -13,16 +13,16 @@ USERVER_NAMESPACE_BEGIN
 
 /// @brief Tracking for heavy operations while having active transactions.
 ///
-/// Some operations, like http requests, are heavy and can take
-/// too long during an incident. If they are called during an active
-/// database transaction, connection will be held for longer and
-/// connection pool will be exhausted. Transaction tracker prevents this
-/// by holding counter of active transactions in TaskLocalVariable
+/// Some operations, like HTTP requests, are heavy and can take too long during an incident. If they are called during
+/// an active database transaction, connection will be held for longer and connection pool will be exhausted.
+/// Transaction tracker prevents this by holding counter of active transactions in TaskLocalVariable
 /// and checking for active transactions in heavy operations.
 ///
 /// ## Example usage:
 ///
 /// @snippet utils/trx_tracker_test.cpp  Sample TransactionTracker usage
+///
+/// @see @ref scripts/docs/en/userver/long_transactions.md
 namespace utils::trx_tracker {
 
 namespace impl {
@@ -42,9 +42,8 @@ bool IsEnabled() noexcept;
 
 /// @brief Unique ID for every task.
 ///
-/// Sometimes transactions start and end in different coroutines.
-/// To prevent transaction from incrementing and decrementing different
-/// transaction counters, TransactionLock stores TaskId on Lock and
+/// Sometimes transactions start and end in different coroutines. To prevent transaction from incrementing and
+/// decrementing different transaction counters, TransactionLock stores TaskId on Lock and
 /// checks that stored TaskId is the same as current TaskId in Unlock.
 class TaskId final {
 public:
@@ -90,10 +89,10 @@ void CheckNoTransactions(std::string_view location);
 
 /// @brief Disable check for active transactions.
 ///
-/// To consciously call a heavy operation in active transaction,
-/// check can be disabled by creating an instance of this class.
-/// Checks will be disabled until every instance either has
-/// Reenable() method called or is destroyed.
+/// To consciously call a heavy operation in active transaction, check can be disabled by creating an instance of this
+/// class. Checks will be disabled until every instance either has Reenable() method called or is destroyed.
+///
+/// @snippet utils/trx_tracker_test.cpp Sample CheckDisabler usage
 class CheckDisabler final {
 public:
     /// @brief Disable check for active transactions.

core/src/utils/trx_tracker_test.cpp

@@ -16,6 +16,26 @@ utils::statistics::Rate GetTriggers() { return utils::trx_tracker::GetStatistics
 
 using TrxTrackerFixture = utest::LogCaptureFixture<>;
 
+class FakeTransaction {
+public:
+    FakeTransaction() { lock_.Lock(); }
+
+    void Commit() { lock_.Unlock(); }
+
+private:
+    utils::trx_tracker::TransactionLock lock_{};
+};
+
+class FakeCluster {
+public:
+    FakeTransaction Begin() { return {}; }
+};
+
+class FakeClient {
+public:
+    void SomeHandle(int) { utils::trx_tracker::CheckNoTransactions(); }
+};
+
 }  // namespace
 
 UTEST_F(TrxTrackerFixture, AssertInTransaction) {
@@ -189,6 +209,27 @@ UTEST(TrxTracker, CopyAssignmentSelf) {
     EXPECT_EQ(GetTriggers(), 1);
 }
 
+UTEST(TrxTracker, CheckDisablerSample) {
+    utils::trx_tracker::ResetStatistics();
+    const utils::trx_tracker::impl::GlobalEnabler enabler;
+
+    FakeCluster cluster;
+    FakeClient client;
+    int request = 42;
+
+    /// [Sample CheckDisabler usage]
+    auto trx = cluster.Begin();
+    {
+        utils::trx_tracker::CheckDisabler disabler;
+        client.SomeHandle(request);  // calls utils::trx_tracker::CheckNoTransactions()
+    }
+
+    trx.Commit();
+    /// [Sample CheckDisabler usage]
+
+    EXPECT_EQ(GetTriggers(), 0);
+}
+
 UTEST(TrxTracker, AssertWithDisabler) {
     utils::trx_tracker::ResetStatistics();
     const utils::trx_tracker::impl::GlobalEnabler enabler;

scripts/docs/en/index.md

@@ -134,6 +134,7 @@ and make sure that it builds and passes tests.
 * @ref scripts/docs/en/userver/congestion_control.md
 * @ref scripts/docs/en/userver/stack.md
 * @ref scripts/docs/en/userver/dump_coroutines.md
+* @ref scripts/docs/en/userver/long_transactions.md
 
 
 ## Caches
@@ -185,6 +186,7 @@ and make sure that it builds and passes tests.
 * @ref scripts/docs/en/userver/libraries/easy.md
 * @ref scripts/docs/en/userver/libraries/s3api.md
 * @ref scripts/docs/en/userver/libraries/grpc-reflection.md
+* @ref scripts/docs/en/userver/libraries/multi_index_lru.md
 
 ## Opensource
 * @ref scripts/docs/en/userver/development/stability.md

scripts/docs/en/userver/caches.md

@@ -227,5 +227,5 @@ Each cache automatically collects metrics. See
 ----------
 
 @htmlonly <div class="bottom-nav"> @endhtmlonly
-⇦ @ref scripts/docs/en/userver/dump_coroutines.md | @ref scripts/docs/en/userver/cache_dumps.md ⇨
+⇦ @ref scripts/docs/en/userver/long_transactions.md | @ref scripts/docs/en/userver/cache_dumps.md ⇨
 @htmlonly </div> @endhtmlonly

scripts/docs/en/userver/development/stability.md

@@ -69,5 +69,5 @@ There are tiers to differentiate technologies:
 ----------
 
 @htmlonly <div class="bottom-nav"> @endhtmlonly
-⇦ @ref scripts/docs/en/userver/libraries/grpc-reflection.md | @ref scripts/docs/en/userver/driver_guide.md ⇨
+⇦ @ref scripts/docs/en/userver/libraries/multi_index_lru.md | @ref scripts/docs/en/userver/driver_guide.md ⇨
 @htmlonly </div> @endhtmlonly

scripts/docs/en/userver/dump_coroutines.md

@@ -100,6 +100,5 @@ json
 ----------
 
 @htmlonly <div class="bottom-nav"> @endhtmlonly
-⇦ @ref scripts/docs/en/userver/stack.md |
-@ref scripts/docs/en/userver/caches.md ⇨
+⇦ @ref scripts/docs/en/userver/stack.md | @ref scripts/docs/en/userver/long_transactions.md ⇨
 @htmlonly </div> @endhtmlonly

scripts/docs/en/userver/libraries/grpc-reflection.md

@@ -44,6 +44,9 @@ components_manager:
 
 4. Thats it. Reflection component will start automatically and expose every gRPC entity in your service.
 
+
+----------
+
 @htmlonly <div class="bottom-nav"> @endhtmlonly
-⇦ @ref scripts/docs/en/userver/libraries/s3api.md | @ref scripts/docs/en/userver/development/stability.md ⇨
+⇦ @ref scripts/docs/en/userver/libraries/s3api.md | @ref scripts/docs/en/userver/libraries/multi_index_lru.md ⇨
 @htmlonly </div> @endhtmlonly

scripts/docs/en/userver/libraries/multi_index_lru.md

@@ -2,11 +2,19 @@
 
 ## Introduction
 
-Generic LRU (Least Recently Used) cache container implementation that combines Boost.MultiIndex for flexible indexing with Boost.Intrusive for efficient LRU tracking. It uses `namespace multi_index_lru`.
+Generic LRU (Least Recently Used) cache container implementation that combines Boost.MultiIndex for flexible indexing
+for efficient LRU tracking. It uses @ref multi_index_lru.
 
-The container maintains elements in access order while supporting multiple indexing strategies through Boost.MultiIndex. The LRU eviction policy automatically removes the least recently accessed items when capacity is reached.
+The container maintains elements in access order while supporting multiple indexing strategies through Boost.MultiIndex.
+ The LRU eviction policy automatically removes the least recently accessed items when capacity is reached.
 
 ## Usage
 
 @snippet libraries/multi-index-lru/src/main_test.cpp Usage
 
+
+----------
+
+@htmlonly <div class="bottom-nav"> @endhtmlonly
+⇦ @ref scripts/docs/en/userver/libraries/grpc-reflection.md | @ref scripts/docs/en/userver/development/stability.md ⇨
+@htmlonly </div> @endhtmlonly

scripts/docs/en/userver/long_transactions.md

@@ -0,0 +1,78 @@
+# Long Transactions Detection
+
+When working with databases, 🐙 userver provides the ability to create a transaction in code and execute database
+queries within it. From creation to commit/rollback, a transaction holds one of the database connections entirely.
+If a heavy operation is called during the transaction’s lifetime (e.g., an HTTP request), then in case of an incident
+(e.g., the service being called via HTTP goes down), the execution time of that operation will increase.
+Consequently, the transaction’s lifetime will also increase while the connection is hold, which may cause the entire
+database to fail.
+
+Consequently there is a built-in mechanism for long transactions detection. See also @ref utils::trx_tracker.
+
+
+## Drawbacks of Long Transactions
+
+* **Exhaustion of the connection pool**. Each transaction occupies a database connection for its entire duration.
+  Prolonged transactions tie up more connections, risking exhaustion of the connection pool.
+* **Exhaustion of database resources**. To ensure transaction isolation between data writing and completion, the
+  database must maintain two versions of each row (old and new). With many concurrent transactions, the number of row
+  duplicates grows significantly, leading to substantial increases in table storage usage.
+* **Execution linearization**. Only one operation can modify a specific database row at a time; others must wait.
+  If a writing transaction becomes blocked, all subsequent write operations are also halt prepared to proceed.
+
+
+## Where the Long Transactions Detection check works
+
+To detect long operations within transactions, we insert a check for active transactions into every heavy operation
+in userver. When triggered, this check writes a log and a metric.
+
+The check is inserted into:
+
++ HTTP requests:
+  + Synchronous code‑generated requests;
+  + Waiting for asynchronous code‑generated requests;
+  + Working with STQ (CallLater, Reschedule, ...);
++ gRPC requests.
+
+Transactions from the following databases are monitored:
+
++ MySQL;
++ PostgreSQL;
++ SQLite;
++ YDB.
+
+The check works in testsuite tests but is disabled in gtest and gbenchmark.
+
+
+## How the Long Transactions Detection check failure is displayed?
+
+**Logs**:
+
+When the check is triggered, the service will spam `WARN` logs with the following text:
+`Long call while having active transactions`. The `meta.location` field displays the name of the method that calls the
+endpoint where the check was triggered.
+
+**Metrics**:
+
+Metric: `engine.heavy-operations-in-transactions` is incremented in case of heavy operation in transaction.
+
+
+## How to fix the Long Transactions Detection check failure
+
+Move the heavy request out from the transaction.
+
+If the bahavior is understood and it is fine to have a long transaction in that particular case, the check could be
+disabled for a scope via @ref utils::trx_tracker::CheckDisabler :
+
+@snippet utils/trx_tracker_test.cpp Sample CheckDisabler usage
+
+To disable the check for the whole service use the `enable_trx_tracker` static configuration option of
+@ref components::ManagerControllerComponent. Note that this is **not** recommended.
+
+
+----------
+
+@htmlonly <div class="bottom-nav"> @endhtmlonly
+⇦ @ref scripts/docs/en/userver/dump_coroutines.md | @ref scripts/docs/en/userver/caches.md ⇨
+@htmlonly </div> @endhtmlonly
+