Undeprecate v2 metrics (#1375)

feorlen · web-flow · commit 3458e72e40be · 2024-12-05T08:19:18.000-07:00
Metrics version 2 is not dead. Continue to feature v3, but restore the v2 info as an alternate version. Out of scope: Updating the Prometheus and InfluxDB procedures. For now, note they are v2 and deal with it in a separate PR. Staged http://192.241.195.202:9000/staging/metrics-v2-not-deprecated/linux/operations/monitoring/metrics-and-alerts.html http://192.241.195.202:9000/staging/metrics-v2-not-deprecated/linux/reference/minio-mc-admin/mc-admin-prometheus.html
diff --git a/source/operations/monitoring/collect-minio-metrics-using-prometheus.rst b/source/operations/monitoring/collect-minio-metrics-using-prometheus.rst
@@ -21,6 +21,9 @@ The procedure on this page documents the following:
 - Configuring a Prometheus service to scrape and display metrics from a MinIO deployment
 - Configuring an Alert Rule on a MinIO Metric to trigger an AlertManager action
 
+These instructions use :ref:`version 2 metrics. <minio-metrics-v2>`
+For more about metrics API versions, see :ref:`Metrics and alerts. <minio-metrics-and-alerts>`
+
 .. admonition:: Prerequisites
    :class: note
 
@@ -32,6 +35,7 @@ The procedure on this page documents the following:
 
    - An :mc:`mc` installation on your local host configured to :ref:`access <alias>` the MinIO deployment
 
+
 Configure Prometheus to Collect and Alert using MinIO Metrics
 -------------------------------------------------------------
 
diff --git a/source/operations/monitoring/grafana.rst b/source/operations/monitoring/grafana.rst
@@ -11,7 +11,6 @@ Monitor a MinIO Server with Grafana
    :depth: 2
    
 `Grafana <https://grafana.com/>`__ allows you to query, visualize, alert on and understand your metrics no matter where they are stored. 
-Create, explore, and share dashboards with your team and foster a data driven culture.
 
 Prerequisites
 -------------
@@ -20,6 +19,15 @@ Prerequisites
 - An existing MinIO deployment with network access to the Prometheus deployment
 - `Grafana installed <https://grafana.com/grafana/download>`__
 
+.. admonition:: Grafana dashboards use metrics version 2
+   :class: note
+
+   The MinIO Grafana dashboards use :ref:`metrics version 2 <minio-metrics-v2>`.
+   For more about metrics API versions, see :ref:`Metrics and alerts. <minio-metrics-and-alerts>`
+
+   Version 3 metrics require creating your own dashboard.
+   For more information about dashboards, see `the Grafana documentation. <https://grafana.com/docs/grafana/latest/dashboards/>`__
+
 MinIO Grafana Dashboard
 -----------------------
 
diff --git a/source/operations/monitoring/healthcheck-probe.rst b/source/operations/monitoring/healthcheck-probe.rst
@@ -33,11 +33,9 @@ A response code of ``200 OK`` indicates the MinIO server is
 online and functional. Any other HTTP codes indicate an issue with reaching
 the server, such as a transient network issue or potential downtime.
 
-The healthcheck probe alone cannot determine if a MinIO server is offline - only
-that the current host machine cannot reach the server. Consider configuring
-a Prometheus :ref:`alert <minio-metrics-and-alerts>` using the 
-``minio_cluster_nodes_offline_total`` metric to detect whether one or
-more MinIO nodes are offline.
+The healthcheck probe alone cannot determine if a MinIO server is offline.
+Instead, the probe determines whether the current host machine can reach the server.
+Consider configuring a Prometheus :ref:`alert <minio-metrics-and-alerts>` using ``minio_cluster_health_nodes_offline_count`` for :ref:`metrics v3 <minio-available-v3-cluster-metrics>` or ``minio_cluster_nodes_offline_total`` for :ref:`metrics v2 <minio-available-cluster-metrics>` to detect whether one or more MinIO nodes are offline.
 
 .. _minio-cluster-write-quorum:
 
diff --git a/source/operations/monitoring/metrics-and-alerts.rst b/source/operations/monitoring/metrics-and-alerts.rst
@@ -3,7 +3,7 @@
 .. _minio-metrics-and-alerts:
 
 ==================
-Metrics and Alerts
+Metrics and alerts
 ==================
 
 .. default-domain:: minio
@@ -12,15 +12,24 @@ Metrics and Alerts
    :local:
    :depth: 2
 
-.. admonition:: Metrics Version 2 Deprecated
+
+MinIO publishes metrics using the :prometheus-docs:`Prometheus Data Model <concepts/data_model/>`.
+You can use any scraping tool to pull metrics data from MinIO for further analysis and alerting.
+
+Starting with MinIO Server :minio-release:`RELEASE.2024-07-15T19-02-30Z` and MinIO Client :mc-release:`RELEASE.2024-07-11T18-01-28Z`, metrics version 3 provides additional endpoints.
+MinIO recommends version 3 for new deployments.
+
+.. admonition:: Metrics version 2
    :class: note
 
-   Starting with MinIO Server :minio-release:`RELEASE.2024-07-15T19-02-30Z` and MinIO Client :mc-release:`RELEASE.2024-07-11T18-01-28Z`, metrics version 3 replaces the deprecated :ref:`metrics version 2 <minio-metrics-v2>`.
+   Existing deployments can continue to use version 2 :ref:`metrics <minio-metrics-v2>` and :ref:`Grafana dashboards <minio-grafana>`.
 
-MinIO publishes cluster and node metrics using the :prometheus-docs:`Prometheus Data Model <concepts/data_model/>`.
-You can use any scraping tool to pull metrics data from MinIO for further analysis and alerting.
 
-For metrics version 3, all metrics are available under the base ``/minio/metrics/v3`` endpoint by appending an additional path for each category.
+Version 3 Endpoints
+-------------------
+
+For metrics version 3, all metrics are available under the base ``/minio/metrics/v3`` endpoint.
+You can scrape the base endpoint to collect all metrics in a single operation, or append an optional path to return a specific category.
 
 For example, the following endpoint returns audit metrics:
 
@@ -98,7 +107,7 @@ MinIO provides the following scraping endpoints, relative to the base URL:
        
        ``/system/process``
 
-For a complete list of metrics for each endpoint, see :ref:`Available Metrics <minio-metrics-and-alerts-available-metrics>`.
+For a complete list of metrics for each endpoint, see :ref:`Available version 3 etrics <minio-metrics-and-alerts-available-metrics>`.
 
 .. cond:: k8s
 
@@ -114,19 +123,12 @@ For a complete list of metrics for each endpoint, see :ref:`Available Metrics <m
 - Set :envvar:`MINIO_PROMETHEUS_URL` to the URL of the Prometheus service
 - Set :envvar:`MINIO_PROMETHEUS_JOB_ID` to the unique job ID assigned to the collected metrics
 
-MinIO Grafana Dashboard
------------------------
-
-MinIO also publishes two :ref:`Grafana Dashboards <minio-grafana>` for visualizing collected metrics. 
-For more complete documentation on configuring a Prometheus-compatible data source for Grafana, see the :prometheus-docs:`Prometheus documentation on Grafana Support <visualization/grafana/>`.
-
 .. _minio-metrics-and-alerts-available-metrics:
 
-Available Metrics
------------------
+Available version 3 metrics
+---------------------------
 
-MinIO publishes a number of metrics at the cluster, node, or bucket levels.
-Each metric includes a label for the MinIO server which generated that metric.
+MinIO publishes a number of metrics for clusters, API requests, buckets, and other aspects of the MinIO service:
 
 - :ref:`API Metrics <minio-available-v3-api-metrics>`
 - :ref:`Audit Metrics <minio-available-v3-audit-metrics>`
@@ -139,6 +141,7 @@ Each metric includes a label for the MinIO server which generated that metric.
 - :ref:`Scanner Metrics <minio-available-v3-scanner-metrics>`
 - :ref:`System Metrics <minio-available-v3-system-metrics>`
 
+Many metrics include labels identifying the resource which generated that metric and other relevant details.
 
 .. _minio-available-v3-api-metrics:
 
@@ -197,3 +200,4 @@ Each metric includes a label for the MinIO server which generated that metric.
 
    /operations/monitoring/collect-minio-metrics-using-prometheus
    /operations/monitoring/monitor-and-alert-using-influxdb
+   /operations/monitoring/metrics-v2
diff --git a/source/operations/monitoring/metrics-v2.rst b/source/operations/monitoring/metrics-v2.rst
@@ -1,8 +1,7 @@
-:orphan:
 .. _minio-metrics-v2:
 
 =================
-Metrics Version 2
+Metrics version 2
 =================
 
 .. default-domain:: minio
@@ -11,12 +10,44 @@ Metrics Version 2
    :local:
    :depth: 3
 
-.. admonition:: Metrics Version 2 Deprecated
-   :class: note
 
-   Starting with MinIO Server :minio-release:`RELEASE.2024-07-15T19-02-30Z` and MinIO Client :mc-release:`RELEASE.2024-07-11T18-01-28Z`, :ref:`metrics version 3 <minio-metrics-and-alerts>` replaces the deprecated metrics version 2.
+MinIO publishes cluster and node metrics using the :prometheus-docs:`Prometheus Data Model <concepts/data_model/>`.
+You can use any scraping tool to pull metrics data from MinIO for further analysis and alerting.
 
-The following sections describe the deprecated endpoints and metrics.
+Version 3 Endpoints
+-------------------
+
+Metrics version 2 provides metrics organized into three categories:
+
+- :ref:`Cluster Metrics <minio-available-cluster-metrics>`
+- :ref:`Bucket Metrics <minio-available-bucket-metrics>`
+- :ref:`Resource Metrics <minio-available-resource-metrics>`
+
+Each v2 endpoint returns all metrics for its category.
+For example, scraping the following endpoint returns all cluster metrics:
+
+.. code-block:: shell
+   :class: copyable
+
+   http://HOSTNAME:PORT/minio/v2/metrics/cluster
+
+The base endpoint alone, ``/minio/v2/metrics/``, returns cluster metrics.
+
+For more flexible scraping and a wider range of metrics, use :ref:`metrics version 3. <minio-metrics-and-alerts>`
+   Existing deployments can continue to use version 2 :ref:`metrics <minio-metrics-v2>` and :ref:`Grafana dashboards <minio-grafana>`.
+
+
+MinIO Grafana dashboard
+-----------------------
+
+MinIO publishes two :ref:`Grafana Dashboards <minio-grafana>` for visualizing v2 metrics.
+For more complete documentation on configuring a Prometheus-compatible data source for Grafana, see the :prometheus-docs:`Prometheus documentation on Grafana Support <visualization/grafana/>`.
+
+
+Available version 2 metrics
+---------------------------
+
+The following sections describe the version 2 endpoints and metrics.
 
 .. tab-set::
 
diff --git a/source/operations/monitoring/monitor-and-alert-using-influxdb.rst b/source/operations/monitoring/monitor-and-alert-using-influxdb.rst
@@ -27,6 +27,9 @@ The procedure on this page documents the following:
    - An existing MinIO deployment with network access to the InfluxDB deployment
    - An :mc:`mc` installation on your local host configured to :ref:`access <alias>` the MinIO deployment
 
+   These instructions use :ref:`version 2 metrics. <minio-metrics-v2>`
+   For more about metrics API versions, see :ref:`Metrics and alerts. <minio-metrics-and-alerts>`
+
 .. cond:: k8s
 
    This procedure assumes all necessary network control components, such as Ingress or Load Balancers, to facilitate access between the MinIO Tenant and the InfluxDB service.
diff --git a/source/reference/minio-mc-admin/mc-admin-prometheus-generate.rst b/source/reference/minio-mc-admin/mc-admin-prometheus-generate.rst
diff --git a/source/reference/minio-mc-admin/mc-admin-prometheus-metrics.rst b/source/reference/minio-mc-admin/mc-admin-prometheus-metrics.rst
