Add inline documentation

yuvipanda · Jul 19, 2024 · fa134c0 · fa134c0
1 parent 729f48c
commit fa134c0
Showing 1 changed file with 24 additions and 7 deletions.
diff --git a/dashboards/homedirs.jsonnet b/dashboards/homedirs.jsonnet
@@ -8,26 +8,35 @@ local common = import './common.libsonnet';
 
 local homedirUsage =
   table.new('Home directory usage')
+  + table.panelOptions.withDescription(
+    |||
+      Home directory usage by various users on the hub.
+
+      Requires an installation of https://github.com/yuvipanda/prometheus-dirsize-exporter to work.
+      If this table is empty, your infrastructure administrator needs to deploy that exporter correctly.
+    |||
+  )
   + table.queryOptions.withTargets([
+    // Last Modified
     prometheus.new(
       '$PROMETHEUS_DS',
       |||
         min(dirsize_latest_mtime{namespace=~"$hub"}) by (directory) * 1000
       |||
     )
-    + prometheus.withLegendFormat('Last Modified')
-    + prometheus.withInstant(true)
+    + prometheus.withInstant(true)  // Only fetch latest value
     + prometheus.withFormat('table')
     ,
+    // Total Size
     prometheus.new(
       '$PROMETHEUS_DS',
       |||
         max(dirsize_total_size_bytes{namespace=~"$hub"}) by (directory)
       |||
     )
-    + prometheus.withLegendFormat('Total Size')
     + prometheus.withInstant(true)
     + prometheus.withFormat('table'),
+    // % of total usage
     prometheus.new(
       '$PROMETHEUS_DS',
       |||
@@ -36,19 +45,19 @@ local homedirUsage =
         ignoring (directory) group_left sum(dirsize_total_size_bytes{namespace=~"$hub"})
       |||
     )
-    + prometheus.withLegendFormat('% of total space used')
     + prometheus.withInstant(true)
     + prometheus.withFormat('table'),
+    // Total number of files
     prometheus.new(
       '$PROMETHEUS_DS',
       |||
         max(dirsize_entries_count{namespace=~"$hub"}) by (directory)
       |||
     )
-    + prometheus.withLegendFormat('Number of entries')
     + prometheus.withInstant(true)
     + prometheus.withFormat('table'),
   ])
+  // Transform table from multiple series with same key to one unified table with shared key 'directory'
   + table.queryOptions.withTransformations([
     table.queryOptions.transformation.withId('joinByField')
     + table.queryOptions.transformation.withOptions({
@@ -60,14 +69,17 @@ local homedirUsage =
     + table.queryOptions.transformation.withOptions({
       // Grafana adds an individual 'Time #N' column for each timeseries we get.
       // They all display the same time. We don't care about time *at all*, since
-      // all these are instant data query targets. So we hide all the time values.
+      // all these are instant data query targets that only display latest
+      // values. So we hide all the time values.
       excludeByName: {
         'Time 1': true,
         'Time 2': true,
         'Time 3': true,
         'Time 4': true,
       },
-      // Explicitly rename the column headers, so they do not display 'Value #N'
+      // Tables do not use the legend keys, and show Value #N for each Time #N. We
+      // explicitly rename these here. This depends on the ordering of these series
+      // above, so if the ordering changes, so must this.
       renameByName: {
         'Value #A': 'Last Modified',
         'Value #B': 'Size',
@@ -78,10 +90,12 @@ local homedirUsage =
   ])
   + {
     fieldConfig: {
+      // Set units for all the columns. These can not be set elsewhere for tables
       overrides: [
         {
           matcher: {
             id: 'byName',
+            // This is name provided by the `renameByName` transform
             options: 'Size',
           },
           properties: [
@@ -94,6 +108,7 @@ local homedirUsage =
         {
           matcher: {
             id: 'byName',
+            // This is name provided by the `renameByName` transform
             options: 'Last Modified',
           },
           properties: [
@@ -106,6 +121,7 @@ local homedirUsage =
         {
           matcher: {
             id: 'byName',
+            // This is name provided by the `renameByName` transform
             options: 'Number of Entries',
           },
           properties: [
@@ -118,6 +134,7 @@ local homedirUsage =
         {
           matcher: {
             id: 'byName',
+            // This is name provided by the `renameByName` transform
             options: '% of total space usage',
           },
           properties: [