Improve Gitaly timeouts UI text and documentation

app/views/admin/application_settings/_gitaly.html.haml

@@ -3,25 +3,19 @@
 
   %fieldset
     .form-group
-      = f.label :gitaly_timeout_default, _('Default Timeout Period'), class: 'label-bold'
+      = f.label :gitaly_timeout_default, _('Default timeout'), class: 'label-bold'
       = f.number_field :gitaly_timeout_default, class: 'form-control gl-form-input'
       .form-text.text-muted
-        Timeout for Gitaly calls from the GitLab application (in seconds). This timeout is not enforced
-        for git fetch/push operations or Sidekiq jobs.
-        This timeout should be less than the worker timeout. If a Gitaly call timeout would exceed the
-        worker timeout, the remaining time from the worker timeout would be used to avoid having to terminate
-        the worker.
+        = _('Timeout for most Gitaly operations (in seconds).')
     .form-group
-      = f.label :gitaly_timeout_fast, _('Fast Timeout Period'), class: 'label-bold'
+      = f.label :gitaly_timeout_fast, _('Fast timeout'), class: 'label-bold'
       = f.number_field :gitaly_timeout_fast, class: 'form-control gl-form-input'
       .form-text.text-muted
-        Fast operation timeout (in seconds). Some Gitaly operations are expected to be fast.
-        If they exceed this threshold, there may be a problem with a storage shard and 'failing fast'
-        can help maintain the stability of the GitLab instance.
+        = _('Timeout for the fastest Gitaly operations (in seconds).')
     .form-group
-      = f.label :gitaly_timeout_medium, _('Medium Timeout Period'), class: 'label-bold'
+      = f.label :gitaly_timeout_medium, _('Medium timeout'), class: 'label-bold'
       = f.number_field :gitaly_timeout_medium, class: 'form-control gl-form-input'
       .form-text.text-muted
-        Medium operation timeout (in seconds). This should be a value between the Fast and the Default timeout.
+        = _('Timeout for moderately fast Gitaly operations (in seconds). Provide a value between Default timeout and Fast timeout.')
 
   = f.submit _('Save changes'), class: "gl-button btn btn-confirm"

app/views/admin/application_settings/preferences.html.haml

@@ -60,11 +60,13 @@
 %section.settings.as-gitaly.no-animate#js-gitaly-settings{ class: ('expanded' if expanded_by_default?) }
   .settings-header
     %h4
-      = _('Gitaly')
+      = _('Gitaly timeouts')
     %button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
       = expanded_by_default? ? _('Collapse') : _('Expand')
     %p
       = _('Configure Gitaly timeouts.')
+      %span
+        = link_to _('Learn more.'), help_page_path('user/admin_area/settings/gitaly_timeouts.md'), target: '_blank'
   .settings-content
     = render 'gitaly'
 

doc/user/admin_area/settings/gitaly_timeouts.md

@@ -8,23 +8,20 @@ type: reference
 # Gitaly timeouts **(FREE SELF)**
 
 [Gitaly](../../../administration/gitaly/index.md) timeouts are configurable. The timeouts can be
-configured to make sure that long running Gitaly calls don't needlessly take up resources.
+configured to make sure that long-running Gitaly calls don't needlessly take up resources.
 
 To access Gitaly timeout settings:
 
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. On the left sidebar, select **Settings > Preferences**.
-1. Expand the **Gitaly** section.
+1. Expand the **Gitaly timeouts** section.
 
 ## Available timeouts
 
-The following timeouts can be modified:
+The following timeouts are available.
 
-- **Default Timeout Period**. This timeout is the default for most Gitaly calls. It should be shorter than the
-  worker timeout that can be configured for [Puma](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings).
-  Used to make sure that Gitaly calls made within a web request cannot exceed the entire request timeout.
-  Defaults to 55 seconds.
-
-- **Fast Timeout Period**. This is the timeout for very short Gitaly calls. Defaults to 10 seconds.
-- **Medium Timeout Period**. This timeout should be between the default and the fast timeout.
-  Defaults to 30 seconds.
+| Timeout | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+|:--------|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the worker timeout that can be configured for [Puma](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. |
+| Fast    | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance.                                                                                                                                                                                                                                                                        |
+| Medium  | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast.                                                                                                                                                                                                                                                                                                                                                       |

locale/gitlab.pot

@@ -10278,9 +10278,6 @@ msgstr ""
 msgid "Default CI/CD configuration file"
 msgstr ""
 
-msgid "Default Timeout Period"
-msgstr ""
-
 msgid "Default artifacts expiration"
 msgstr ""
 
@@ -10317,6 +10314,9 @@ msgstr ""
 msgid "Default projects limit"
 msgstr ""
 
+msgid "Default timeout"
+msgstr ""
+
 msgid "Default: Map a FogBugz account ID to a full name"
 msgstr ""
 
@@ -13527,7 +13527,7 @@ msgstr ""
 msgid "False positive"
 msgstr ""
 
-msgid "Fast Timeout Period"
+msgid "Fast timeout"
 msgstr ""
 
 msgid "Fast-forward merge is not possible. Rebase the source branch onto %{targetBranch} to allow this merge request to be merged."
@@ -14989,9 +14989,6 @@ msgstr ""
 msgid "GitLabPages|Your pages are served under:"
 msgstr ""
 
-msgid "Gitaly"
-msgstr ""
-
 msgid "Gitaly Servers"
 msgstr ""
 
@@ -15001,6 +14998,9 @@ msgstr ""
 msgid "Gitaly storage name:"
 msgstr ""
 
+msgid "Gitaly timeouts"
+msgstr ""
+
 msgid "Gitaly|Address"
 msgstr ""
 
@@ -20165,7 +20165,7 @@ msgstr ""
 msgid "Measured in bytes of code. Excludes generated and vendored code."
 msgstr ""
 
-msgid "Medium Timeout Period"
+msgid "Medium timeout"
 msgstr ""
 
 msgid "Medium vulnerabilities present"
@@ -33858,6 +33858,15 @@ msgstr ""
 msgid "Timeout connecting to the Google API. Please try again."
 msgstr ""
 
+msgid "Timeout for moderately fast Gitaly operations (in seconds). Provide a value between Default timeout and Fast timeout."
+msgstr ""
+
+msgid "Timeout for most Gitaly operations (in seconds)."
+msgstr ""
+
+msgid "Timeout for the fastest Gitaly operations (in seconds)."
+msgstr ""
+
 msgid "Timezone"
 msgstr ""