From 8da7c7d94ca6e252d713bdd250a5742b65d53044 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Tue, 8 Oct 2024 11:55:48 -0400 Subject: [PATCH] Adds mc admin scanner to reference docs (#1332) Closes #1304 --- source/reference/minio-mc-admin.rst | 6 + .../mc-admin-scanner-status.rst | 132 +++++++++++ .../minio-mc-admin/mc-admin-scanner-trace.rst | 219 ++++++++++++++++++ .../minio-mc-admin/mc-admin-scanner.rst | 51 ++++ 4 files changed, 408 insertions(+) create mode 100644 source/reference/minio-mc-admin/mc-admin-scanner-status.rst create mode 100644 source/reference/minio-mc-admin/mc-admin-scanner-trace.rst create mode 100644 source/reference/minio-mc-admin/mc-admin-scanner.rst diff --git a/source/reference/minio-mc-admin.rst b/source/reference/minio-mc-admin.rst index 6e92cd36..7cbba955 100644 --- a/source/reference/minio-mc-admin.rst +++ b/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 diff --git a/source/reference/minio-mc-admin/mc-admin-scanner-status.rst b/source/reference/minio-mc-admin/mc-admin-scanner-status.rst new file mode 100644 index 00000000..cbd7c8e2 --- /dev/null +++ b/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 ` 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 ] \ + [--interval ] \ + [--max-paths ] \ + [-n ] \ + [--nodes ] + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment for which to display :ref:`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 + diff --git a/source/reference/minio-mc-admin/mc-admin-scanner-trace.rst b/source/reference/minio-mc-admin/mc-admin-scanner-trace.rst new file mode 100644 index 00000000..d4d40bd3 --- /dev/null +++ b/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 `-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 ] \ + [--funcname ] \ + [--node ] \ + [--path ] \ + [--response-duration ] \ + [--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 ` of the MinIO deployment for which to display :ref:`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 ` 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 diff --git a/source/reference/minio-mc-admin/mc-admin-scanner.rst b/source/reference/minio-mc-admin/mc-admin-scanner.rst new file mode 100644 index 00000000..f9597ee6 --- /dev/null +++ b/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 ` 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