backup: adjust concurrency description after v8.2 (#20963)

[ti-chi-bot]

This is an automated cherry-pick of #20963

First-time contributors' checklist

• I've signed Contributor License Agreement that's required for repo owners to accept my contribution.

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.4 (TiDB 8.4 versions)
• v8.3 (TiDB 8.3 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)
• v6.1 (TiDB 6.1 versions)
• v5.4 (TiDB 5.4 versions)

What is the related PR or file link(s)?

• This PR is translated from:
• Other reference link(s):

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

[ti-chi-bot]

@3pointer This PR has conflicts, I have hold it.
Please resolve them or ask others to resolve them, then comment /unhold to remove the hold label.

[gemini-code-assist]

Hello @ti-chi-bot, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

Hello team, gemini-code-assist here to provide a summary of this pull request. This PR, titled "backup: adjust concurrency description after v8.2", is an automated cherry-pick aimed at updating the documentation for the BR (Backup & Restore) tool. The core intent is to clarify the recommended methods for controlling the performance impact of backup tasks on a TiDB cluster, particularly after changes or observations made around the v8.2 release. It adjusts the descriptions of the --concurrency and --ratelimit command-line parameters for br and the tikv.backup.num-threads configuration, emphasizing the latter as the primary method for controlling CPU usage during backup.

Highlights

• Clarified Backup Impact Control: The documentation is updated to clearly distinguish between controlling backup impact via the TiKV configuration backup.num-threads (recommended, controls CPU usage) and the br command-line parameter --ratelimit (alternative, limits bandwidth to storage).
• Recommended backup.num-threads: The documentation now explicitly recommends adjusting the tikv.backup.num-threads configuration parameter as the primary method for limiting backup impact, explaining that it offers more precise control over TiKV's CPU usage.
• Clarified --concurrency Parameter: The description for the br command-line parameter --concurrency is updated to clarify that it primarily affects the granularity of request splitting to a single TiKV node and no longer directly determines overall backup throughput. It recommends using tikv.backup.num-threads for performance tuning instead.
• Updated Examples: Several example tiup br backup commands in the documentation have been updated to remove the --ratelimit parameter, aligning examples with the updated guidance.

Changelog

• br/br-snapshot-guide.md
  • Removed --ratelimit 128 from the example tiup br backup full command.
  • Removed the description for the --ratelimit parameter from the initial command explanation.
  • Rewrote the section on controlling backup impact, designating backup.num-threads as the recommended method and --ratelimit as an alternative, adding a note about further reducing throughput and suggesting alternatives like scaling out or Log Backup.
• br/br-snapshot-manual.md
  • Removed --ratelimit 128 from example commands for tiup br backup full, tiup br backup db, tiup br backup table, and tiup br backup full with filter.
  • Resolved or updated text around parameter descriptions which show merge conflict markers in the diff.
• br/use-br-command-line-tool.md
  • Updated the description of the --concurrency parameter to explain its role in request splitting granularity to a single TiKV node and recommend tikv.backup.num-threads for performance tuning.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request aims to adjust the description of concurrency-related parameters for backup after TiDB v8.2. The changes significantly improve the clarity on how --concurrency, --ratelimit, and backup.num-threads interact and how users should approach tuning backup performance and impact.

Key improvements:

• The updated explanation in br/br-snapshot-guide.md for controlling backup impact is much clearer, recommending backup.num-threads as the primary method.
• The description for the --concurrency option in br/use-br-command-line-tool.md is now more accurate, reflecting its role in request splitting rather than direct throughput control.
• Examples have been simplified by removing --ratelimit, deferring its explanation to the detailed sections.

However, there is a critical merge conflict in br/br-snapshot-manual.md that must be resolved before this PR can be merged. I've provided a specific suggestion for resolving it.

Overall, once the conflict is addressed, these changes will be a valuable improvement to the documentation. The review adheres to the Documentation Review Style Guide, focusing on aspects like clarity [^1], technical accuracy [^2], and consistent terminology [^3].

Due to the merge conflict, I am setting the review status to REQUEST_CHANGES. While the style guide (line 9) suggests preferring COMMENT to avoid blocking, a merge conflict is a technical blocker that needs to be addressed.

Summary of Findings

• Merge Conflict: A critical merge conflict exists in br/br-snapshot-manual.md (lines 44-49) that needs to be resolved. This prevents the file from being correctly interpreted.
• Documentation Clarity: The changes significantly improve the clarity of how backup concurrency parameters (--concurrency, --ratelimit, backup.num-threads) work and should be used, which is a great enhancement for users.
• Punctuation: A minor punctuation suggestion was made in br/br-snapshot-guide.md for consistency ("TiKV’s" to "TiKV's").

Merge Readiness

This pull request contains valuable clarifications for the backup documentation. However, there is a critical merge conflict in br/br-snapshot-manual.md that must be resolved before merging. Once this conflict is addressed, and the minor punctuation suggestion is considered, the PR should be in good shape. As a reviewer, I am not authorized to approve pull requests, but I recommend that the merge conflict be fixed before this PR is considered for merging by other reviewers.

[ti-chi-bot]

@gemini-code-assist[bot]: adding LGTM is restricted to approvers and reviewers in OWNERS files.

In response to this:

Code Review

This pull request aims to adjust the description of concurrency-related parameters for backup after TiDB v8.2. The changes significantly improve the clarity on how --concurrency, --ratelimit, and backup.num-threads interact and how users should approach tuning backup performance and impact.

Key improvements:

• The updated explanation in br/br-snapshot-guide.md for controlling backup impact is much clearer, recommending backup.num-threads as the primary method.
• The description for the --concurrency option in br/use-br-command-line-tool.md is now more accurate, reflecting its role in request splitting rather than direct throughput control.
• Examples have been simplified by removing --ratelimit, deferring its explanation to the detailed sections.

However, there is a critical merge conflict in br/br-snapshot-manual.md that must be resolved before this PR can be merged. I've provided a specific suggestion for resolving it.

Overall, once the conflict is addressed, these changes will be a valuable improvement to the documentation. The review adheres to the Documentation Review Style Guide, focusing on aspects like clarity [^1], technical accuracy [^2], and consistent terminology [^3].

Due to the merge conflict, I am setting the review status to REQUEST_CHANGES. While the style guide (line 9) suggests preferring COMMENT to avoid blocking, a merge conflict is a technical blocker that needs to be addressed.

Summary of Findings

• Merge Conflict: A critical merge conflict exists in br/br-snapshot-manual.md (lines 44-49) that needs to be resolved. This prevents the file from being correctly interpreted.
• Documentation Clarity: The changes significantly improve the clarity of how backup concurrency parameters (--concurrency, --ratelimit, backup.num-threads) work and should be used, which is a great enhancement for users.
• Punctuation: A minor punctuation suggestion was made in br/br-snapshot-guide.md for consistency ("TiKV’s" to "TiKV's").

Merge Readiness

This pull request contains valuable clarifications for the backup documentation. However, there is a critical merge conflict in br/br-snapshot-manual.md that must be resolved before merging. Once this conflict is addressed, and the minor punctuation suggestion is considered, the PR should be in good shape. As a reviewer, I am not authorized to approve pull requests, but I recommend that the merge conflict be fixed before this PR is considered for merging by other reviewers.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[hfxsd]

/approve

no need

[hfxsd]

/approve

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: hfxsd

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [hfxsd]

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