Make generated automatic feed block error messages more user-friendly

Messages are generated centrally by the cluster controller and pushed
to content nodes as part of a cluster state bundle; the distributors
nodes merely repeat back what they have been told. This changes the
cluster controller feed block error message code to be less ambiguous
and to include a URL to our public documentation about feed blocks.

Example of _old_ message:
```
disk on node 1 [storage.1.local] (0.510 > 0.500)
```
Same feed block with _new_ message:
```
disk on node 1 [storage.1.local] is 51.0% full (the configured limit is 50.0%).
See https://docs.vespa.ai/en/operations/feed-block.html
```

2 files changed, 11 insertions, 4 deletions

diff --git a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/NodeResourceExhaustion.java b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/NodeResourceExhaustion.java
index ee121d7682c..6899eaa6598 100644
--- a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/NodeResourceExhaustion.java
+++ b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/NodeResourceExhaustion.java
@@ -47,18 +47,19 @@ public class NodeResourceExhaustion {
     }
 
     public String toExhaustionAddedDescription() {
-        return String.format(Locale.US, "%s (%.3g > %.3g)", makeDescriptionPrefix(), resourceUsage.getUsage(), limit);
+        return String.format(Locale.US, "%s is %.1f%% full (the configured limit is %.1f%%)",
+                makeDescriptionPrefix(), resourceUsage.getUsage() * 100.0, limit * 100.0);
     }
 
     public String toExhaustionRemovedDescription() {
-        return String.format(Locale.US, "%s (<= %.3g)", makeDescriptionPrefix(), limit);
+        return String.format(Locale.US, "%s (<= %.1f%%)", makeDescriptionPrefix(), limit * 100.0);
     }
 
     public String toShorthandDescription() {
-        return String.format(Locale.US, "%s%s %.3g > %.3g",
+        return String.format(Locale.US, "%s%s %.1f%% > %.1f%%",
                 resourceType,
                 (resourceUsage.getName() != null ? ":" + resourceUsage.getName() : ""),
-                resourceUsage.getUsage(), limit);
+                resourceUsage.getUsage() * 100.0, limit * 100.0);
     }
 
     private String makeDescriptionPrefix() {
diff --git a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/ResourceExhaustionCalculator.java b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/ResourceExhaustionCalculator.java
index db84882cfa7..732048716bb 100644
--- a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/ResourceExhaustionCalculator.java
+++ b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/ResourceExhaustionCalculator.java
@@ -78,6 +78,11 @@ public class ResourceExhaustionCalculator {
         }
     }
 
+    public static String decoratedMessage(String msg) {
+        // Add a user-friendly documentation link to the error message
+        return "%s. See https://docs.vespa.ai/en/operations/feed-block.html".formatted(msg);
+    }
+
     public ClusterStateBundle.FeedBlock inferContentClusterFeedBlockOrNull(Collection<NodeInfo> nodeInfos) {
         if (!feedBlockEnabled) {
             return null;
@@ -94,6 +99,7 @@ public class ResourceExhaustionCalculator {
         if (exhaustions.size() > maxDescriptions) {
             description += String.format(" (... and %d more)", exhaustions.size() - maxDescriptions);
         }
+        description = decoratedMessage(description);
         // FIXME we currently will trigger a cluster state recomputation even if the number of
         // exhaustions is greater than what is returned as part of the description. Though at
         // that point, cluster state recomputations will be the least of your worries...!