OLD | NEW |
| (Empty) |
1 # -*- coding: utf-8 -*- | |
2 # Copyright 2014 Google Inc. All Rights Reserved. | |
3 # | |
4 # Licensed under the Apache License, Version 2.0 (the "License"); | |
5 # you may not use this file except in compliance with the License. | |
6 # You may obtain a copy of the License at | |
7 # | |
8 # http://www.apache.org/licenses/LICENSE-2.0 | |
9 # | |
10 # Unless required by applicable law or agreed to in writing, software | |
11 # distributed under the License is distributed on an "AS IS" BASIS, | |
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
13 # See the License for the specific language governing permissions and | |
14 # limitations under the License. | |
15 """Additional help text about retry handling.""" | |
16 | |
17 from gslib.help_provider import HelpProvider | |
18 | |
19 _DETAILED_HELP_TEXT = (""" | |
20 <B>RETRY STRATEGY</B> | |
21 There are a number of reasons that gsutil operations can fail; some are not | |
22 retryable, and require that the user take some action, for example: | |
23 - Invalid credentials | |
24 - Network unreachable because of a proxy configuration problem | |
25 - Access denied, because the bucket or object you are trying to use has an | |
26 ACL that doesn't permit the action you're trying to perform. | |
27 | |
28 In other cases errors are retryable - basically, the HTTP 429 and 5xx error | |
29 codes. For these cases, gsutil will retry using a truncated binary exponential | |
30 backoff strategy: | |
31 | |
32 - Wait a random period between [0..1] seconds and retry; | |
33 - If that fails, wait a random period between [0..2] seconds and retry; | |
34 - If that fails, wait a random period between [0..4] seconds and retry; | |
35 - And so on, up to a configurable maximum number of retries (default = 6), | |
36 with each retry period bounded by a configurable maximum period of time | |
37 (default = 60 seconds). | |
38 | |
39 Thus, by default, gsutil will retry 6 times over 1+2+4+8+16+32=63 seconds. | |
40 You can adjust the number of retries and maximum delay of any individual retry | |
41 by editing the num_retries and max_retry_delay configuration variables in the | |
42 "[Boto]" section of the .boto config file. Most users shouldn't need to change | |
43 these values. | |
44 | |
45 For data transfers (the gsutil cp and rsync commands), gsutil provides | |
46 additional retry functionality, in the form of resumable transfers. | |
47 Essentially, a transfer that was interrupted because of a transient error | |
48 can be restarted without starting over from scratch. For more details | |
49 about this, see the "RESUMABLE TRANSFERS" section of "gsutil help cp". | |
50 """) | |
51 | |
52 | |
53 class CommandOptions(HelpProvider): | |
54 """Additional help text about retry handling.""" | |
55 | |
56 # Help specification. See help_provider.py for documentation. | |
57 help_spec = HelpProvider.HelpSpec( | |
58 help_name='retries', | |
59 help_name_aliases=['retry', 'backoff', 'reliability'], | |
60 help_type='additional_help', | |
61 help_one_line_summary='Retry Handling Strategy', | |
62 help_text=_DETAILED_HELP_TEXT, | |
63 subcommand_help_text={}, | |
64 ) | |
OLD | NEW |