Merge branch 'weimeng-master-patch-93321' into 'master'

Documentation: Add additional Rails maintenance commands

See merge request gitlab-org/gitlab!28745

doc/administration/auth/ldap-troubleshooting.md

@@ -634,7 +634,7 @@ The rails console is a valuable tool to help debug LDAP problems. It allows you
 directly interact with the application by running commands and seeing how GitLab
 responds to them.
 
-Please refer to [this guide](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+Please refer to [this guide](../troubleshooting/debug.md#starting-a-rails-console-session)
 for instructions on how to use the rails console.
 
 #### Enable debug output

doc/administration/instance_limits.md

@@ -70,7 +70,7 @@ There is a limit when embedding metrics in GFM for performance reasons.
 On GitLab.com, the [maximum number of webhooks](../user/gitlab_com/index.md#maximum-number-of-webhooks) per project, and per group, is limited.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -120,7 +120,7 @@ will fail with a `job_activity_limit_exceeded` error.
   This limit is disabled by default.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -145,7 +145,7 @@ limit, the subscription will be considered invalid.
 - On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined for the `default` plan that affects all projects.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.limits.update!(ci_project_subscriptions: 500)
@@ -170,7 +170,7 @@ or higher tiers), this limit is defined for the `default` plan that affects all
 projects. By default, there is no limit.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.limits.update!(ci_pipeline_schedules: 100)

doc/administration/repository_storage_types.md

@@ -100,7 +100,7 @@ The "Gitaly relative path" is shown there, for example:
 This is the path under `/var/opt/gitlab/git-data/repositories/` on a
 default Omnibus installation.
 
-In a [Rails console](troubleshooting/debug.md#starting-a-rails-console),
+In a [Rails console](troubleshooting/debug.md#starting-a-rails-console-session),
 get this information using either the numeric project ID or the full path:
 
 ```ruby
@@ -112,7 +112,7 @@ Project.find_by_full_path('group/project').disk_path
 
 To translate from a hashed storage path to a project name:
 
-1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console).
+1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console-session).
 1. Run the following:
 
 ```ruby

doc/administration/troubleshooting/debug.md

@@ -3,9 +3,10 @@
 Sometimes things don't work the way they should. Here are some tips on debugging issues out
 in production.
 
-## Starting a Rails console
+## Starting a Rails console session
 
-Troubleshooting and debugging often requires a rails console.
+Troubleshooting and debugging your GitLab instance often requires a
+[Rails console](https://guides.rubyonrails.org/command_line.html#rails-console).
 
 **For Omnibus installations**
 
@@ -13,22 +14,81 @@ Troubleshooting and debugging often requires a rails console.
 sudo gitlab-rails console
 ```
 
----
-
 **For installations from source**
 
 ```shell
-bundle exec rails console production
+sudo -u git -H bundle exec rails console -e production
 ```
 
 Kubernetes: the console is in the task-runner pod, refer to our [Kubernetes cheat sheet](kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details.
 
+### Enabling Active Record logging
+
+You can enable output of Active Record debug logging in the Rails console
+session by running:
+
+```ruby
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+```
+
+This will show information about database queries triggered by any Ruby code
+you may run in the console. To turn off logging again, run:
+
+```ruby
+ActiveRecord::Base.logger = nil
+```
+
+### Disabling database statement timeout
+
+You can disable the PostgreSQL statement timeout for the current Rails console
+session by running:
+
+```ruby
+ActiveRecord::Base.connection.execute('SET statement_timeout TO 0')
+```
+
+Note that this change only affects the current Rails console session and will
+not be persisted in the GitLab production environment or in the next Rails
+console session.
+
+### Output Rails console session history
+
+If you'd like to output your Rails console command history in a format that's
+easy to copy and save for future reference, you can run:
+
+```ruby
+puts Readline::HISTORY.to_a
+```
+
+## Using the Rails Runner
+
+If you need to run some Ruby code in thex context of your GitLab production
+environment, you can do so using the [Rails Runner](https://guides.rubyonrails.org/command_line.html#rails-runner).
+
+**For Omnibus installations**
+
+```shell
+sudo gitlab-rails runner "RAILS_COMMAND"
+
+# Example with a two-line Ruby script
+sudo gitlab-rails runner "user = User.first; puts user.username"
+```
+
+**For installations from source**
+
+```shell
+sudo -u git -H bundle exec rails runner -e production "RAILS_COMMAND"
+
+# Example with a two-line Ruby script
+sudo -u git -H bundle exec rails runner -e production "user = User.first; puts user.username"
+```
+
 ## Mail not working
 
 A common problem is that mails are not being sent for some reason. Suppose you configured
 an SMTP server, but you're not seeing mail delivered. Here's how to check the settings:
 
-1. Run a [Rails console.](#starting-a-rails-console)
+1. Run a [Rails console](#starting-a-rails-console-session).
 
 1. Look at the ActionMailer `delivery_method` to make sure it matches what you
    intended. If you configured SMTP, it should say `:smtp`. If you're using
@@ -168,7 +228,7 @@ separate Rails process to debug the issue:
 1. Log in to your GitLab account.
 1. Copy the URL that is causing problems (e.g. `https://gitlab.com/ABC`).
 1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens).
-1. Bring up the [GitLab Rails console.](#starting-a-rails-console)
+1. Bring up the [GitLab Rails console.](#starting-a-rails-console-session)
 1. At the Rails console, run:
 
    ```ruby

doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md

@@ -25,36 +25,6 @@ mentioned above, we recommend running these scripts under the supervision of a
 Support Engineer, who can also verify that they will continue to work as they
 should and, if needed, update the script for the latest version of GitLab.
 
-## Use the Rails Runner
-
-If the script you want to run is short, you can use the Rails Runner to avoid
-entering the rails console in the first place. Here's an example of its use:
-
-```shell
-gitlab-rails runner "RAILS_COMMAND"
-
-# Example with a 2-line script
-gitlab-rails runner "user = User.first; puts user.username"
-```
-
-## Enable debug logging on rails console
-
-```ruby
-Rails.logger.level = 0
-```
-
-## Enable debug logging for ActiveRecord (db issues)
-
-```ruby
-ActiveRecord::Base.logger = Logger.new(STDOUT)
-```
-
-## Temporarily Disable Timeout
-
-```ruby
-ActiveRecord::Base.connection.execute('SET statement_timeout TO 0')
-```
-
 ## Find specific methods for an object
 
 ```ruby
@@ -85,12 +55,6 @@ o = Object.where('attribute like ?', 'ex')
 Rails.cache.instance_variable_get(:@data).keys
 ```
 
-## Rails console history
-
-```ruby
-puts Readline::HISTORY.to_a
-```
-
 ## Profile a page
 
 ```ruby

doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md

@@ -3,7 +3,7 @@
 At the heart of GitLab is a web application [built using the Ruby on Rails
 framework](https://about.gitlab.com/blog/2018/10/29/why-we-use-rails-to-build-gitlab/).
 Thanks to this, we also get access to the amazing tools built right into Rails.
-In this guide, we'll introduce the [Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+In this guide, we'll introduce the [Rails console](debug.md#starting-a-rails-console-session)
 and the basics of interacting with your GitLab instance from the command line.
 
 CAUTION: **CAUTION:**

doc/administration/troubleshooting/ssl.md

@@ -23,7 +23,7 @@ After configuring a GitLab instance with an internal CA certificate, you might n
   More details here: https://curl.haxx.se/docs/sslcerts.html
   ```
 
-- Testing via the [rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session) also fails:
+- Testing via the [rails console](debug.md#starting-a-rails-console-session) also fails:
 
   ```ruby
   uri = URI.parse("https://gitlab.domain.tld")

doc/ci/yaml/README.md

@@ -2549,7 +2549,7 @@ This example creates four paths of execution:
 
 The maximum number of jobs that can be defined within `needs:` defaults to 10, but
 can be changed to 50 via a feature flag. To change the limit to 50,
-[start a Rails console session](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+[start a Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
 and run:
 
 ```ruby

doc/integration/github.md

@@ -151,7 +151,7 @@ via Omnibus, or [restart GitLab] if you installed from source.
 Check the [`production.log`](../administration/logs.md#productionlog)
 on your GitLab server to obtain further details. If you are getting the error like
 `Faraday::ConnectionFailed (execution expired)` in the log, there may be a connectivity issue
-between your GitLab instance and GitHub Enterprise. To verify it, [start the rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+between your GitLab instance and GitHub Enterprise. To verify it, [start the rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session)
 and run the commands below replacing `<github_url>` with the URL of your GitHub Enterprise instance:
 
 ```ruby

doc/raketasks/import.md

@@ -125,7 +125,7 @@ There is an [open issue to add a migration to make all bare repositories
 importable](https://gitlab.com/gitlab-org/gitlab-foss/issues/41776).
 
 Until then, you may wish to manually migrate repositories yourself. You can use
-[Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+[Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session)
 to do so. In a Rails console session, run the following to migrate a project:
 
 ```ruby

doc/update/README.md

@@ -122,7 +122,7 @@ If using GitLab 12.9 and newer, run:
 sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
 ```
 
-If using GitLab 12.8 and older, run the following using a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console):
+If using GitLab 12.8 and older, run the following using a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 puts Sidekiq::Queue.new("background_migration").size
@@ -140,7 +140,7 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
 ```
 
-If using GitLab 12.8 and older, run the following using a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console):
+If using GitLab 12.8 and older, run the following using a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 puts Sidekiq::Queue.new("background_migration").size