Adds mc admin scanner to reference docs (#1332)

Closes #1304

source/reference/minio-mc-admin.rst

@@ -95,6 +95,11 @@ The following table lists :mc:`mc admin` commands:
           :start-after: start-mc-admin-replicate-desc
           :end-before: end-mc-admin-replicate-desc
 
+   * - :mc-cmd:`mc admin scanner`
+     - .. include:: /reference/minio-mc-admin/mc-admin-scanner.rst
+          :start-after: start-mc-admin-scanner-desc
+          :end-before: end-mc-admin-scanner-desc
+
    * - :mc-cmd:`mc admin service`
      - .. include:: /reference/minio-mc-admin/mc-admin-service.rst
           :start-after: start-mc-admin-service-desc
@@ -182,6 +187,7 @@ See :ref:`minio-mc-global-options`.
    /reference/minio-mc-admin/mc-admin-prometheus
    /reference/minio-mc-admin/mc-admin-rebalance
    /reference/minio-mc-admin/mc-admin-replicate
+   /reference/minio-mc-admin/mc-admin-scanner
    /reference/minio-mc-admin/mc-admin-service
    /reference/minio-mc-admin/mc-admin-trace
    /reference/minio-mc-admin/mc-admin-update

source/reference/minio-mc-admin/mc-admin-scanner-status.rst

@@ -0,0 +1,132 @@
+===========================
+``mc admin scanner status``
+===========================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+.. mc:: mc admin scanner info
+.. mc:: mc admin scanner status
+
+Description
+-----------
+
+.. start-mc-admin-scanner-status-desc
+
+The :mc-cmd:`mc admin scanner status` command displays a real-time summary of :ref:`scanner <minio-concepts-scanner>` information for a MinIO Server.
+
+.. end-mc-admin-scanner-status-desc
+
+This command has an alias of ``mc admin scanner info``.
+
+.. admonition:: Use ``mc admin`` on MinIO Deployments Only
+   :class: note
+
+   .. include:: /includes/facts-mc-admin.rst
+      :start-after: start-minio-only
+      :end-before: end-minio-only
+
+.. tab-set::
+
+   .. tab-item:: EXAMPLE
+
+      The following example returns information about the current state of the scanner process.
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin scanner status myminio
+
+      The command returns results similar to the following:
+
+      .. code-block:: shell
+         
+         Overall Statistics                               	
+         ------------------                                                  	
+         Last full scan time:   0d0h15m; Estimated 2879.79/month             	
+         Current cycle:         (between cycles)                             	
+         Active drives: 0                                                    	
+                                                                             	
+         Last Minute Statistics                                              	
+         ----------------------                                              	
+         Objects Scanned:       3 objects; Avg: 67.611µs; Rate: 4320/day     	
+         Versions Scanned:      3 versions; Avg: 2.506µs; Rate: 4320/day     	
+         Versions Heal Checked: 0 versions; Avg: 0ms                         	
+         Read Metadata:         3 objects; Avg: 40.817µs, Size: 395 bytes/obj	
+         ILM checks:            3 versions; Avg: 714ns                       	
+         Check Replication:     3 versions; Avg: 892ns                       	
+         Verify Deleted:        0 folders; Avg: 0ms                          	
+         Yield:                 18ms total; Avg: 6ms/obj     
+
+   .. tab-item:: SYNTAX
+
+      The command has the following syntax:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin scanner status ALIAS
+                                [--bucket <string>]     \
+                                [--interval <value>]   \
+                                [--max-paths <value>]  \
+                                [-n <integer>]         \
+                                [--nodes <string>] 
+
+      .. include:: /includes/common-minio-mc.rst
+         :start-after: start-minio-syntax
+         :end-before: end-minio-syntax
+
+Parameters
+~~~~~~~~~~
+
+.. mc-cmd:: ALIAS
+   :required:
+
+   The :ref:`alias <alias>` of the MinIO deployment for which to display :ref:`scanner <minio-concepts-scanner>` API operations.
+
+.. mc-cmd:: --bucket
+   :optional:
+
+   Filter scanner statistics to the specified bucket.
+
+.. mc-cmd:: --interval
+   :optional:
+
+   The number of seconds to wait between status request refreshes.
+   If not specified, the status refreshes every 3 seconds.
+
+.. mc-cmd:: --max-paths
+   :optional:
+
+   The maximum number of active paths to show.
+   Use ``-1`` for an unlimited number of paths.
+
+   Limiting the number of paths shown can reduce the scrolling of the console window when there are a large number of drives being scanned.
+   
+   If not specified, the results return for an unlimited number of active paths.
+
+.. mc-cmd:: -n
+   :optional:
+
+   The number of status requests to return before automatically exiting.
+   Use ``0`` to return an unlimited number of status results.
+
+   If not specified, the results continuously refresh at the specified interval until manually exited.
+
+.. mc-cmd:: --nodes
+   :optional:
+
+   Returns scanner status information for the specified node(s).
+   Specify multiple nodes as a comma-separated list.
+
+
+Global Flags
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-mc.rst
+   :start-after: start-minio-mc-globals
+   :end-before: end-minio-mc-globals
+

source/reference/minio-mc-admin/mc-admin-scanner-trace.rst

@@ -0,0 +1,219 @@
+==========================
+``mc admin scanner trace``
+==========================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+.. mc:: mc admin scanner trace
+
+Description
+-----------
+
+.. start-mc-admin-scanner-trace-desc
+
+The :mc-cmd:`mc admin scanner trace` command displays :ref:`scanner <minio-concepts-scanner>`-specific API operations occurring on the target MinIO deployment.
+
+.. end-mc-admin-scanner-trace-desc
+
+.. admonition:: Use ``mc admin`` on MinIO Deployments Only
+   :class: note
+
+   .. include:: /includes/facts-mc-admin.rst
+      :start-after: start-minio-only
+      :end-before: end-minio-only
+
+.. tab-set::
+
+   .. tab-item:: EXAMPLE
+
+      The following example returns a list of API operations related to the scanner on the ``myminio`` deployment.
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin scanner trace myminio
+
+   .. tab-item:: SYNTAX
+
+      The command has the following syntax:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin scanner trace ALIAS
+                                [--filter-request]            \
+                                [--filter-response]           \
+                                [--filter-size <value>]       \
+                                [--funcname <value>]          \
+                                [--node <value>]              \
+                                [--path <value>]              \
+                                [--response-duration <value>] \
+                                [--verbose, -v]
+
+      .. include:: /includes/common-minio-mc.rst
+         :start-after: start-minio-syntax
+         :end-before: end-minio-syntax
+
+Parameters
+~~~~~~~~~~
+
+.. mc-cmd:: ALIAS
+   :required:
+
+   The :ref:`alias <alias>` of the MinIO deployment for which to display :ref:`scanner <minio-concepts-scanner>` API operations.
+
+.. mc-cmd:: --filter-request
+   :optional:
+
+   Trace scanner operations or calls with request size greater than the specified :mc-cmd:`~mc admin scanner trace --filter-size` value.
+
+   **Must** be used with :mc-cmd:`~mc admin scanner trace --filter-size` flag.
+
+.. mc-cmd:: --filter-response
+   :optional:
+
+   Trace scanner operations or calls with response size greater than the specified :mc-cmd:`~mc admin scanner trace --filter-size` value.
+
+   **Must** be used with :mc-cmd:`~mc admin scanner trace --filter-size` flag.
+
+.. mc-cmd:: --filter-size
+   :optional:
+
+   Filter output to request sizes or response sizes greater than the specified size.
+
+   Must be used with either :mc-cmd:`~mc admin scanner trace --filter-request` or :mc-cmd:`~mc admin scanner trace --filter-response` flag.
+
+   Valid units include:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 80
+      :width: 100%
+   
+      * - Suffix
+        - Unit Size
+   
+      * - ``k``
+        - KB (Kilobyte, 1000 Bytes)
+   
+      * - ``m``
+        - MB (Megabyte, 1000 Kilobytes)
+   
+      * - ``g``
+        - GB (Gigabyte, 1000 Megabytes)
+   
+      * - ``t``
+        - TB (Terrabyte, 1000 Gigabytes)
+   
+      * - ``ki``
+        - KiB (Kibibyte, 1024 Bites)
+   
+      * - ``mi``
+        - MiB (Mebibyte, 1024 Kibibytes)
+   
+      * - ``gi``
+        - GiB (Gibibyte, 1024 Mebibytes)
+   
+      * - ``ti``
+        - TiB (Tebibyte, 1024 Gibibytes)
+
+.. mc-cmd:: --funcname
+   :optional:
+
+   Returns calls for the entered function name.
+
+.. mc-cmd:: --node
+   :optional:
+
+   Returns calls for the specified server.
+
+.. mc-cmd:: --path
+   :optional:
+
+   Returns calls for the specified path.
+
+.. mc-cmd:: --response-duration
+   :optional:
+
+   Trace calls with response duration greater than the specified value.
+
+.. mc-cmd:: --verbose, -v
+   :optional:
+
+   Returns verbose output.
+
+
+Global Flags
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-mc.rst
+   :start-after: start-minio-mc-globals
+   :end-before: end-minio-mc-globals
+
+
+Examples
+--------
+
+Monitor all scanner API operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc admin scanner trace` to monitor :ref:`scanner <minio-concepts-scanner>` API operations on the MinIO deployment at the alias ``myminio``:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin scanner trace myminio
+
+Show scanner trace for a specific path
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc admin scanner trace` to monitor API operations for a the path ``my-bucket/my-prefix/*`` on the deployment at the ``myminio`` alias:
+
+.. code-block:: shell
+   :class: copyable
+   
+    mc admin scanner trace --path my-bucket/my-prefix/* myminio
+
+Show scanner API operations for the ``scanObject`` function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Monitor scanner activity for the ``scanObject function`` on the ``myminio`` deployment:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin scanner trace --funcname=scanner.ScanObject myminio 
+
+Show scanner operation requests greater than ``1MB`` in size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc admin scanner trace` to monitor requests larger than a ``1MB`` on the ``myminio`` deployment:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin scanner trace --filter-request --filter-size 1MB myminio
+
+Show scanner operation responses greater than ``1MB`` in size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc admin scanner trace` to monitor large response sizes:
+
+.. code-block:: shell
+   :class: copyable
+
+    mc admin scanner trace --filter-response --filter-size 1MB myminio 
+
+Show scanner operations that last longer than five milliseconds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc admin scanner trace` to monitor long operations:
+
+.. code-block:: shell
+   :class: copyable
+
+    mc admin scanner trace --response-duration 5ms myminio

source/reference/minio-mc-admin/mc-admin-scanner.rst

@@ -0,0 +1,51 @@
+====================
+``mc admin scanner``
+====================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+.. mc:: mc admin scanner
+
+
+Description
+-----------
+
+.. start-mc-admin-scanner-desc
+
+The :mc:`mc admin scanner` commands provide information about the :ref:`scanner <minio-concepts-scanner>` process. 
+
+.. end-mc-admin-scanner-desc
+
+Subcommands
+-----------
+
+:mc:`mc admin scanner` includes the following subcommands:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+   :width: 100%
+
+   * - Subcommand
+     - Description
+
+   * - :mc:`~mc admin scanner status`
+     - .. include:: /reference/minio-mc-admin/mc-admin-scanner-status.rst
+          :start-after: start-mc-admin-scanner-status-desc
+          :end-before: end-mc-admin-scanner-status-desc
+
+   * - :mc:`~mc admin scanner trace`
+     - .. include:: /reference/minio-mc-admin/mc-admin-scanner-trace.rst
+          :start-after: start-mc-admin-scanner-trace-desc
+          :end-before: end-mc-admin-scanner-trace-desc
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+   
+   /reference/minio-mc-admin/mc-admin-scanner-status
+   /reference/minio-mc-admin/mc-admin-scanner-trace