[FA] Set display_priority in elastic spec.yaml (DataDog#23278)

* Set display_priority in elastic spec.yaml based on field usage

* Add changelog entry for elastic

* Reorder fields in elastic spec.yaml by display_priority

Author: coignetp

elastic/assets/configuration/spec.yaml

@@ -10,6 +10,7 @@ files:
   - template: instances
     options:
     - name: url
+      display_priority: 7
       fleet_configurable: true
       required: true
       description: |
@@ -19,88 +20,98 @@ files:
       value:
         example: http://localhost:9200
         type: string
-    - name: node_name_as_host
+    - name: pshard_stats
+      display_priority: 6
       description: |
-        If each machine only runs a single Elasticsearch node per cluster, you
-        want to set each Elasticsearch `node.name` to the machine hostname. You may
-        then set `node_name_as_host` to `true` to avoid duplicate hostnames.
-        See: https://www.elastic.co/guide/en/elasticsearch/reference/current/node.name.html
+        If you enable the `pshard_stats` flag, statistics over primary shards
+        are collected by the check and sent to the backend with the
+        `elasticsearch.primary` prefix. It is particularly useful if you want to
+        get certain metrics without taking replicas into account. For instance,
+        `elasticsearch.primaries.docs.count` gives you the total number of
+        documents in your indexes WITHOUT counting duplicates due to the existence
+        of replica shards in your ES cluster.
       fleet_configurable: true
       value:
         type: boolean
         example: false
-    - name: cluster_stats
-      description: |
-        If your cluster is hosted externally (i.e., you're not pointing to localhost),
-        you must set `cluster_stats` to true, otherwise the check only
-        submits metrics of the local node.
-        This parameter was also called `is_external` and you can still use it but it
-        is removed in Agent version 6+.
+    - name: index_stats
+      display_priority: 5
+      description: Set `index_stats` to true to collect metrics for individual indices.
       fleet_configurable: true
       value:
         type: boolean
         example: false
-    - name: detailed_index_stats
+    - name: pending_task_stats
+      display_priority: 4
       description: |
-        If you want to obtain index-specific stats, use this flag with `cluster_stats` and `pshard_stats` set to true.
-        Without this flag you only get stats from `_all`.
-        Do not use it if you are pointing to localhost.
+        Specifies whether to collect data exposed by the `pending_tasks` cluster endpoint.
+        Ref: https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-pending.html
+        Some managed Elasticsearch services (e.g., AWS Elasticsearch) do not expose this endpoint.
+        Set `pending_task_stats` to false if you use such a service.
       fleet_configurable: true
       value:
         type: boolean
-        example: false
-    - name: index_stats
-      description: Set `index_stats` to true to collect metrics for individual indices.
+        example: true
+    - name: cluster_stats
+      display_priority: 3
+      description: |
+        If your cluster is hosted externally (i.e., you're not pointing to localhost),
+        you must set `cluster_stats` to true, otherwise the check only
+        submits metrics of the local node.
+        This parameter was also called `is_external` and you can still use it but it
+        is removed in Agent version 6+.
       fleet_configurable: true
       value:
         type: boolean
         example: false
-    - name: pshard_stats
+    - name: cat_allocation_stats
+      display_priority: 2
       description: |
-        If you enable the `pshard_stats` flag, statistics over primary shards
-        are collected by the check and sent to the backend with the
-        `elasticsearch.primary` prefix. It is particularly useful if you want to
-        get certain metrics without taking replicas into account. For instance,
-        `elasticsearch.primaries.docs.count` gives you the total number of
-        documents in your indexes WITHOUT counting duplicates due to the existence
-        of replica shards in your ES cluster.
+        Enable to collect Elastic Cat Allocation metrics. Available only for Elasticsearch 5.0 or higher.
+        Ref: https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-allocation.html.
       fleet_configurable: true
       value:
         type: boolean
         example: false
     - name: slm_stats
+      display_priority: 1
       description: |
         Set `slm_stats` to true to collect statistics about Snapshot Lifecycle Management.
         The user must have the `read_slm` cluster privilege to get these metrics.
       fleet_configurable: true
       value:
         type: boolean
         example: false
-    - name: pshard_graceful_timeout
-      description: Continue gracefully if pshard stats timeout.
+    - name: node_name_as_host
+      display_priority: 0
+      description: |
+        If each machine only runs a single Elasticsearch node per cluster, you
+        want to set each Elasticsearch `node.name` to the machine hostname. You may
+        then set `node_name_as_host` to `true` to avoid duplicate hostnames.
+        See: https://www.elastic.co/guide/en/elasticsearch/reference/current/node.name.html
       fleet_configurable: true
       value:
         type: boolean
         example: false
-    - name: pending_task_stats
+    - name: detailed_index_stats
+      display_priority: 0
       description: |
-        Specifies whether to collect data exposed by the `pending_tasks` cluster endpoint.
-        Ref: https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-pending.html
-        Some managed Elasticsearch services (e.g., AWS Elasticsearch) do not expose this endpoint.
-        Set `pending_task_stats` to false if you use such a service.
+        If you want to obtain index-specific stats, use this flag with `cluster_stats` and `pshard_stats` set to true.
+        Without this flag you only get stats from `_all`.
+        Do not use it if you are pointing to localhost.
       fleet_configurable: true
       value:
         type: boolean
-        example: true
-    - name: cat_allocation_stats
-      description: |
-        Enable to collect Elastic Cat Allocation metrics. Available only for Elasticsearch 5.0 or higher.
-        Ref: https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-allocation.html.
+        example: false
+    - name: pshard_graceful_timeout
+      display_priority: 0
+      description: Continue gracefully if pshard stats timeout.
       fleet_configurable: true
       value:
         type: boolean
         example: false
     - name: detailed_shard_metrics
+      display_priority: 0
       description: |
         Enable to collect detailed shard placement metrics with `index_name` and `prirep` (primary/replica) tags.
         Requires `cat_allocation_stats` to be enabled.
@@ -112,6 +123,7 @@ files:
         type: boolean
         example: false
     - name: admin_forwarder
+      display_priority: 0
       description: |
         Specifies a URL that includes a context root
         needed for a forwarder application to access Elasticsearch REST services, for example:
@@ -121,6 +133,7 @@ files:
         type: boolean
         example: false
     - name: gc_collectors_as_rate
+      display_priority: 0
       description: |
         Submit `jvm.gc.collectors` metrics as rate.
         Note: Only for ES versions 0.9.10 or higher.
@@ -129,6 +142,7 @@ files:
         type: boolean
         example: false
     - name: disable_legacy_cluster_tag
+      display_priority: 0
       description: Enable to stop submitting the tag `cluster_name`, which has been renamed to `elastic_cluster`.
       fleet_configurable: true
       value:
@@ -137,6 +151,7 @@ files:
         example: true
       enabled: false
     - name: disable_legacy_service_check_tags
+      display_priority: 0
       description: |
         Disable the submission of the Elasticsearch `host` and `port` as tags in service checks.
         Submit them as `url` instead.
@@ -147,6 +162,7 @@ files:
         example: true
       enabled: true
     - name: custom_queries
+      display_priority: 0
       description: |
         Run custom queries for Elasticsearch. Each custom query endpoint can collect multiple metrics and tags.
         Note: Each custom query requires an `endpoint`, `data_path`, and `columns` parameter. Each `columns` parameter
@@ -220,6 +236,7 @@ files:
               items:
                 type: string
     - name: submit_events
+      display_priority: 0
       description: |
         By default we submit events to Datadog if the cluster starts unhealthy or anytime its health changes.
         You can set this option to `false` to disable submitting the events in case you already implemented

elastic/changelog.d/23278.fixed

@@ -0,0 +1 @@
+Re-order configuration fields based on real-world usage data.

elastic/datadog_checks/elastic/data/conf.yaml.example

@@ -51,35 +51,6 @@ instances:
     #
   - url: http://localhost:9200
 
-    ## @param node_name_as_host - boolean - optional - default: false
-    ## If each machine only runs a single Elasticsearch node per cluster, you
-    ## want to set each Elasticsearch `node.name` to the machine hostname. You may
-    ## then set `node_name_as_host` to `true` to avoid duplicate hostnames.
-    ## See: https://www.elastic.co/guide/en/elasticsearch/reference/current/node.name.html
-    #
-    # node_name_as_host: false
-
-    ## @param cluster_stats - boolean - optional - default: false
-    ## If your cluster is hosted externally (i.e., you're not pointing to localhost),
-    ## you must set `cluster_stats` to true, otherwise the check only
-    ## submits metrics of the local node.
-    ## This parameter was also called `is_external` and you can still use it but it
-    ## is removed in Agent version 6+.
-    #
-    # cluster_stats: false
-
-    ## @param detailed_index_stats - boolean - optional - default: false
-    ## If you want to obtain index-specific stats, use this flag with `cluster_stats` and `pshard_stats` set to true.
-    ## Without this flag you only get stats from `_all`.
-    ## Do not use it if you are pointing to localhost.
-    #
-    # detailed_index_stats: false
-
-    ## @param index_stats - boolean - optional - default: false
-    ## Set `index_stats` to true to collect metrics for individual indices.
-    #
-    # index_stats: false
-
     ## @param pshard_stats - boolean - optional - default: false
     ## If you enable the `pshard_stats` flag, statistics over primary shards
     ## are collected by the check and sent to the backend with the
@@ -91,16 +62,10 @@ instances:
     #
     # pshard_stats: false
 
-    ## @param slm_stats - boolean - optional - default: false
-    ## Set `slm_stats` to true to collect statistics about Snapshot Lifecycle Management.
-    ## The user must have the `read_slm` cluster privilege to get these metrics.
-    #
-    # slm_stats: false
-
-    ## @param pshard_graceful_timeout - boolean - optional - default: false
-    ## Continue gracefully if pshard stats timeout.
+    ## @param index_stats - boolean - optional - default: false
+    ## Set `index_stats` to true to collect metrics for individual indices.
     #
-    # pshard_graceful_timeout: false
+    # index_stats: false
 
     ## @param pending_task_stats - boolean - optional - default: true
     ## Specifies whether to collect data exposed by the `pending_tasks` cluster endpoint.
@@ -110,12 +75,47 @@ instances:
     #
     # pending_task_stats: true
 
+    ## @param cluster_stats - boolean - optional - default: false
+    ## If your cluster is hosted externally (i.e., you're not pointing to localhost),
+    ## you must set `cluster_stats` to true, otherwise the check only
+    ## submits metrics of the local node.
+    ## This parameter was also called `is_external` and you can still use it but it
+    ## is removed in Agent version 6+.
+    #
+    # cluster_stats: false
+
     ## @param cat_allocation_stats - boolean - optional - default: false
     ## Enable to collect Elastic Cat Allocation metrics. Available only for Elasticsearch 5.0 or higher.
     ## Ref: https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-allocation.html.
     #
     # cat_allocation_stats: false
 
+    ## @param slm_stats - boolean - optional - default: false
+    ## Set `slm_stats` to true to collect statistics about Snapshot Lifecycle Management.
+    ## The user must have the `read_slm` cluster privilege to get these metrics.
+    #
+    # slm_stats: false
+
+    ## @param node_name_as_host - boolean - optional - default: false
+    ## If each machine only runs a single Elasticsearch node per cluster, you
+    ## want to set each Elasticsearch `node.name` to the machine hostname. You may
+    ## then set `node_name_as_host` to `true` to avoid duplicate hostnames.
+    ## See: https://www.elastic.co/guide/en/elasticsearch/reference/current/node.name.html
+    #
+    # node_name_as_host: false
+
+    ## @param detailed_index_stats - boolean - optional - default: false
+    ## If you want to obtain index-specific stats, use this flag with `cluster_stats` and `pshard_stats` set to true.
+    ## Without this flag you only get stats from `_all`.
+    ## Do not use it if you are pointing to localhost.
+    #
+    # detailed_index_stats: false
+
+    ## @param pshard_graceful_timeout - boolean - optional - default: false
+    ## Continue gracefully if pshard stats timeout.
+    #
+    # pshard_graceful_timeout: false
+
     ## @param detailed_shard_metrics - boolean - optional - default: false
     ## Enable to collect detailed shard placement metrics with `index_name` and `prirep` (primary/replica) tags.
     ## Requires `cat_allocation_stats` to be enabled.