transaction: add contextual logging with start_ts (#267)

[eduralph]

Enrich the transaction lifecycle, plan/retry, and region-cache logging with each transaction's start_ts and region/store context; add commit/rollback outcome logs, log dropping an active transaction under all check levels, and a terminal warn when region-error retries are exhausted. Truncate keys in the one full-key error log. Fix message typos/duplicates and remove dead logger-threading comments. Add a dependency-free capture-logger test and a RUST_LOG note to the README.

Refs #267

Signed-off-by: Eduard Ralph eduard@ralphovi.net

Summary by CodeRabbit

• Documentation

  • Added guidance on client logging setup, including backend selection, log levels, and RUST_LOG configuration.

• Bug Fixes

  • Corrected a misleading log message for reverse key scans.
  • Improved cache invalidation and region-error logs so operational issues are easier to trace.

• Improvements

  • Transaction lifecycle logs now include more context, making commits, rollbacks, retries, and heartbeat activity easier to diagnose.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign sticnarf for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 58c71128-8dca-4222-a0f7-6e4925b67e58

📥 Commits

Reviewing files that changed from the base of the PR and between e53837d and b3b76dc.

📒 Files selected for processing (7)

• README.md
• src/raw/client.rs
• src/region_cache.rs
• src/request/plan.rs
• src/transaction/client.rs
• src/transaction/lock.rs
• src/transaction/transaction.rs

---

📝 Walkthrough

Walkthrough

This PR expands logging across the client-rust crate: adds debug/warn/info logs with contextual details (start_ts, region/store ids, key counts) to region cache invalidation, region error retry handling, transaction client operations, and transaction/2PC lifecycle code; adds a pub(crate) key formatter, a test CaptureLogger, and README documentation.

Changes

Logging improvements

Layer / File(s)	Summary
Logging documentation README.md	New "Logging" section describes the log facade, env_logger example, RUST_LOG usage, and debug vs info+ verbosity levels.
Raw client scan log fix src/raw/client.rs	Fixes mislabeled debug log message in scan_keys_reverse.
Region cache invalidation logging src/region_cache.rs	Adds debug logging for leader updates and cache invalidation; invalidate_store_cache refactored to log and return the removed value.
Request retry/region error logging src/request/plan.rs	Adds warn-level logging when retries are exhausted, and enriches debug logs with region_ver_id, store_id, ver_id, and error context.
Transaction client lifecycle logging src/transaction/client.rs	Removes stale commented log, moves/enriches begin_* debug logs to include start_ts, updates gc info log with safepoint version.
Key formatting helper visibility src/transaction/lock.rs	format_key_for_log visibility changed from private to pub(crate).
Transaction and 2PC lifecycle logging src/transaction/transaction.rs	Swaps HexRepr for format_key_for_log; adds start_ts-rich debug logs across commit, rollback, heartbeat, pessimistic lock, auto-heartbeat, Drop, and Committer methods; TransactionStatus derives Debug.
Log capture test coverage src/transaction/transaction.rs	Adds CaptureLogger and a commit_logs_start_ts test verifying logs include start_ts.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
    participant Transaction
    participant Committer
    participant TiKVStore
    participant Logger

    Transaction->>Logger: debug!(commit start, start_ts)
    Transaction->>Committer: commit()
    Committer->>Logger: debug!(prewrite start, start_ts, mutation count)
    Committer->>TiKVStore: prewrite request
    TiKVStore-->>Committer: response
    Committer->>Logger: debug!(commit_primary start, start_ts)
    Committer->>TiKVStore: commit_primary request
    TiKVStore-->>Committer: commit_ts
    Committer->>Logger: debug!(commit_secondary start, start_ts, mutation count)
    Committer->>TiKVStore: commit_secondary request
    Committer-->>Transaction: Ok(commit_ts)
    Transaction->>Logger: debug!(commit success, commit_ts, elapsed)

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: transaction logging now includes start_ts context.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}