fix: resolve review feedback

Author: darrenjaneczek

CHANGELOG.md

@@ -12,7 +12,7 @@
 * [BUGFIX] Fixed `CortexIngesterHasNotShippedBlocks` alert false positive in case an ingester instance had ingested samples in the past, then no traffic was received for a long period and then it started receiving samples again. #308
 * [CHANGE] Dashboards: added overridable `job_labels` and `cluster_labels` to the configuration object as label lists to uniquely identify jobs and clusters in the metric names and group-by lists in dashboards. #319
 * [CHANGE] Dashboards: `alert_aggregation_labels` has been removed from the configuration and overriding this value has been deprecated. Instead the labels are now defined by the `cluster_labels` list, and should be overridden accordingly through that list. #319
-* [ENHANCEMENT] Added documentation text panels and descriptions to reads and writes dashboards. 
+* [ENHANCEMENT] Added documentation text panels and descriptions to reads and writes dashboards. #324
 
 ## 1.9.0 / 2021-05-18
 

cortex-mixin/config.libsonnet

@@ -58,5 +58,11 @@
 
     // The label used to differentiate between different nodes (i.e. servers).
     per_node_label: 'instance',
+
+    // Whether certain dashboard description headers should be shown
+    show_dashboard_descriptions: {
+      writes: true,
+      reads: true,
+    },
   },
 }

cortex-mixin/dashboards/compactor.libsonnet

@@ -36,7 +36,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
           'Tenants compaction progress',
           |||
             In a multi-tenant cluster, display the progress of tenants that are compacted while compaction is running.
-            Reset to `0` after the compaction run is completed for all tenants in the shard.
+            Reset to <tt>0</tt> after the compaction run is completed for all tenants in the shard.
           |||
         ),
       )
@@ -50,7 +50,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
         $.panelDescription(
           'Compacted blocks / sec',
           |||
-            Display the amount of time that it’s taken to generate a single compacted block.
+            Rate of blocks that are generated as a result of a compaction operation.
           |||
         ),
       )
@@ -60,7 +60,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
         $.panelDescription(
           'Per-block compaction duration',
           |||
-            Rate of blocks that are generated as a result of a compaction operation.
+            Display the amount of time that it has taken to generate a single compacted block.
           |||
         ),
       )

cortex-mixin/dashboards/dashboard-utils.libsonnet

@@ -336,11 +336,10 @@ local utils = import 'mixin-utils/utils.libsonnet';
       jobMatcher: $.jobMatcher(jobName),
       component: component,
       cacheName: cacheName,
-      cacheNameReadable: std.strReplace(cacheName, '-', ' '),
     };
     super.row(title)
     .addPanel(
-      $.panel('Requests per second') +
+      $.panel('Requests / sec') +
       $.queryPanel(
         |||
           sum by(operation) (

cortex-mixin/dashboards/reads.libsonnet

@@ -4,15 +4,16 @@ local utils = import 'mixin-utils/utils.libsonnet';
   'cortex-reads.json':
     ($.dashboard('Cortex / Reads') + { uid: '8d6ba60eccc4b6eedfa329b24b1bd339' })
     .addClusterSelectorTemplates()
-    .addRow(
+    .addRowIf(
+      $._config.show_dashboard_descriptions.reads,
       ($.row('Reads dashboard description') { height: '175px', showTitle: false })
       .addPanel(
         $.textPanel('', |||
           <p>
             This dashboard shows health metrics for the Cortex read path.
             It is broken into sections for each service on the read path, and organized by the order in which the read request flows.
             <br/>
-            Incoming queries travel from the gateway → query frontend → query scheduler → querier → ingester and/or store-gateway (depending on the age of the query).
+            Incoming queries travel from the gateway → query frontend → query scheduler → querier → ingester and/or store-gateway (depending on the time range of the query).
             <br/>
             For each service, there are 3 panels showing (1) requests per second to that service, (2) average, median, and p99 latency of requests to that service, and (3) p99 latency of requests to each instance of that service.
           </p> 
@@ -42,14 +43,14 @@ local utils = import 'mixin-utils/utils.libsonnet';
               cortex_request_duration_seconds_count{
                 %(queryFrontend)s,
                 route=~"(prometheus|api_prom)_api_v1_query"
-              }[1h]
+              }[$__rate_interval]
             )
           ) + 
           sum(
             rate(
               cortex_prometheus_rule_evaluations_total{
                 %(ruler)s
-              }[1h]
+              }[$__rate_interval]
             )
           )
         ||| % {
@@ -73,7 +74,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
               cortex_request_duration_seconds_count{
                 %(queryFrontend)s,
                 route=~"(prometheus|api_prom)_api_v1_query_range"
-              }[1h]
+              }[$__rate_interval]
             )
           )
         ||| % {
@@ -132,7 +133,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
           |||
             <p>
               The query scheduler is an optional service that moves
-              the internal queue from the query frontend into a
+              the internal queue from the query-frontend into a
               separate component.
               If this service is not deployed, 
               these panels will show "No data."
@@ -241,7 +242,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
     )
     .addRowIf(
       std.member($._config.storage_engine, 'blocks'),
-      $.row('Memcached – blocks storage – block index cache (store-gateway accesses)')  // Resembles thanosMemcachedCache
+      $.row('Memcached – Blocks storage – Block index cache (store-gateway accesses)')  // Resembles thanosMemcachedCache
       .addPanel(
         $.panel('Requests / sec') +
         $.queryPanel(
@@ -314,7 +315,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
     .addRowIf(
       std.member($._config.storage_engine, 'blocks'),
       $.thanosMemcachedCache(
-        'Memcached – blocks storage – chunks cache (store-gateway accesses)',
+        'Memcached – Blocks storage – Chunks cache (store-gateway accesses)',
         $._config.job_names.store_gateway,
         'store-gateway',
         'chunks-cache'
@@ -323,7 +324,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
     .addRowIf(
       std.member($._config.storage_engine, 'blocks'),
       $.thanosMemcachedCache(
-        'Memcached – blocks storage – metadata cache (store-gateway accesses)',
+        'Memcached – Blocks storage – Metadata cache (store-gateway accesses)',
         $._config.job_names.store_gateway,
         'store-gateway',
         'metadata-cache'
@@ -332,7 +333,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
     .addRowIf(
       std.member($._config.storage_engine, 'blocks'),
       $.thanosMemcachedCache(
-        'Memcached – blocks storage – metadata cache (querier accesses)',
+        'Memcached – Blocks storage – Metadata cache (querier accesses)',
         $._config.job_names.querier,
         'querier',
         'metadata-cache'

cortex-mixin/dashboards/writes.libsonnet

@@ -4,7 +4,8 @@ local utils = import 'mixin-utils/utils.libsonnet';
   'cortex-writes.json':
     ($.dashboard('Cortex / Writes') + { uid: '0156f6d15aa234d452a33a4f13c838e3' })
     .addClusterSelectorTemplates()
-    .addRow(
+    .addRowIf(
+      $._config.show_dashboard_descriptions.writes,
       ($.row('Writes dashboard description') { height: '125px', showTitle: false })
       .addPanel(
         $.textPanel('', |||
@@ -129,7 +130,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
       )
     )
     .addRow(
-      $.row('Key-value store for the ingester ring')
+      $.row('Key-value store for the ingesters ring')
       .addPanel(
         $.panel('Requests / sec') +
         $.qpsPanel('cortex_kv_request_duration_seconds_count{%s}' % $.jobMatcher($._config.job_names.ingester))
@@ -227,7 +228,7 @@ local utils = import 'mixin-utils/utils.libsonnet';
           'Upload latency',
           |||
             The average, median (50th percentile), and 99th percentile time 
-            the ingester takes to upload blocks to object storage.
+            the ingesters take to upload blocks to object storage.
           |||
         ),
       )
@@ -256,15 +257,15 @@ local utils = import 'mixin-utils/utils.libsonnet';
         $.panelDescription(
           'Compaction latency',
           |||
-            The average, median (50th percentile), and 99th percentile time ingesters take to compact head blocks
+            The average, median (50th percentile), and 99th percentile time ingesters take to compact TSDB head blocks
             on the local filesystem.
           |||
         ),
       )
     )
     .addRowIf(
       std.member($._config.storage_engine, 'blocks'),
-      $.row('Ingester - blocks storage - TSDB write ahead log (WAL)')
+      $.row('Ingester - Blocks storage - TSDB write ahead log (WAL)')
       .addPanel(
         $.successFailurePanel(
           'WAL truncations / sec',