address feedback

config.md

@@ -1,7 +1,7 @@
 # Honeycomb Refinery Configuration Documentation
 
 This is the documentation for the configuration file for Honeycomb's Refinery.
-It was automatically generated on 2024-12-02 at 16:12:36 UTC.
+It was automatically generated on 2024-12-02 at 16:40:52 UTC.
 
 ## The Config file
 
@@ -1023,15 +1023,16 @@ This value should be set to a bit less than the normal timeout period for shutti
 
 ### `TraceLocalityMode`
 
-TraceLocalityMode controls the how Refinery handles spans that belongs to the same trace in a clustered environment.
+TraceLocalityMode controls how Refinery handles spans that belongs to the same trace in a clustered environment.
 
 When `concentrated`, Refinery will route all spans that belong to the same trace to a single peer.
 This is the default behavior ("Trace Locality") and the way Refinery has worked in the past.
 When `distributed`, Refinery will instead keep spans on the node where they were received, and forward proxy spans that contain only the key information needed to make a trace decision.
-This can reduce the amount of traffic between peers in most cases, and can help avoid a situation where a single large trace can cause a memory overrun on a single node.
+This can reduce the amount of traffic between peers, and can help avoid a situation where a single large trace can cause a memory overrun on a single node.
 If `distributed`, the amount of traffic between peers will be reduced, but the amount of traffic between Refinery and Redis will significantly increase, because Refinery uses Redis to distribute the trace decisions to all nodes in the cluster.
 It is important to adjust the size of the Redis cluster in this case.
-NOTE: This setting is not compatible with `DryRun` when set to true.
+The total volume of network traffic in `distributed` mode should be expected to decrease unless the cluster size is very large (hundreds of nodes).
+NOTE: This setting is not compatible with `DryRun` when set to `distributed`.
 See `DryRun` for more information.
 
 - Not eligible for live reload.

config/metadata/configMeta.yaml

@@ -1346,20 +1346,20 @@ groups:
         firstversion: v2.9
         default: "concentrated"
         reload: false
-        summary: controls the how Refinery handles spans that belongs to the same trace in a clustered environment.
+        summary: controls how Refinery handles spans that belongs to the same trace in a clustered environment.
         description: >
           When `concentrated`, Refinery will route all spans that belong to the same trace to a single peer. This is the
           default behavior ("Trace Locality") and the way Refinery has worked in the past. When `distributed`, Refinery
           will instead keep spans on the node where they were received, and forward proxy spans that contain only
-          the key information needed to make a trace decision. This can reduce the amount of traffic between peers
-          in most cases, and can help avoid a situation where a single large trace can cause a memory overrun on
-          a single node.
+          the key information needed to make a trace decision. This can reduce the amount of traffic between peers,
+          and can help avoid a situation where a single large trace can cause a memory overrun on a single node.
 
           If `distributed`, the amount of traffic between peers will be reduced, but the amount of traffic between Refinery
           and Redis will significantly increase, because Refinery uses Redis to distribute the trace decisions to all
           nodes in the cluster. It is important to adjust the size of the Redis cluster in this case.
 
-          NOTE: This setting is not compatible with `DryRun` when set to true. See `DryRun` for more information.
+          The total volume of network traffic in `distributed` mode should be expected to decrease unless the cluster size is very large (hundreds of nodes).
+          NOTE: This setting is not compatible with `DryRun` when set to `distributed`. See `DryRun` for more information.
 
       - name: HealthCheckTimeout
         type: duration

config_complete.yaml

@@ -2,7 +2,7 @@
 ## Honeycomb Refinery Configuration ##
 ######################################
 #
-# created on 2024-12-02 at 16:12:35 UTC from ../../config.yaml using a template generated on 2024-12-02 at 16:12:16 UTC
+# created on 2024-12-02 at 16:40:51 UTC from ../../config.yaml using a template generated on 2024-12-02 at 16:40:45 UTC
 
 # This file contains a configuration for the Honeycomb Refinery. It is in YAML
 # format, organized into named groups, each of which contains a set of
@@ -1083,25 +1083,26 @@ Collection:
     ## Eligible for live reload.
     # ShutdownDelay: 15s
 
-    ## TraceLocalityMode controls the how Refinery handles spans that belongs
-    ## to the same trace in a clustered environment.
+    ## TraceLocalityMode controls how Refinery handles spans that belongs to
+    ## the same trace in a clustered environment.
     ##
     ## When `concentrated`, Refinery will route all spans that belong to the
     ## same trace to a single peer. This is the default behavior ("Trace
     ## Locality") and the way Refinery has worked in the past. When
     ## `distributed`, Refinery will instead keep spans on the node where they
     ## were received, and forward proxy spans that contain only the key
     ## information needed to make a trace decision. This can reduce the
-    ## amount of traffic between peers in most cases, and can help avoid a
-    ## situation where a single large trace can cause a memory overrun on a
-    ## single node.
+    ## amount of traffic between peers, and can help avoid a situation where
+    ## a single large trace can cause a memory overrun on a single node.
     ## If `distributed`, the amount of traffic between peers will be reduced,
     ## but the amount of traffic between Refinery and Redis will
     ## significantly increase, because Refinery uses Redis to distribute the
     ## trace decisions to all nodes in the cluster. It is important to adjust
     ## the size of the Redis cluster in this case.
-    ## NOTE: This setting is not compatible with `DryRun` when set to true.
-    ## See `DryRun` for more information.
+    ## The total volume of network traffic in `distributed` mode should be
+    ## expected to decrease unless the cluster size is very large (hundreds
+    ## of nodes). NOTE: This setting is not compatible with `DryRun` when set
+    ## to `distributed`. See `DryRun` for more information.
     ##
     ## default: concentrated
     ## Not eligible for live reload.

refinery_config.md

@@ -1008,15 +1008,16 @@ This value should be set to a bit less than the normal timeout period for shutti
 
 ### `TraceLocalityMode`
 
-`TraceLocalityMode` controls the how Refinery handles spans that belongs to the same trace in a clustered environment.
+`TraceLocalityMode` controls how Refinery handles spans that belongs to the same trace in a clustered environment.
 
 When `concentrated`, Refinery will route all spans that belong to the same trace to a single peer.
 This is the default behavior ("Trace Locality") and the way Refinery has worked in the past.
 When `distributed`, Refinery will instead keep spans on the node where they were received, and forward proxy spans that contain only the key information needed to make a trace decision.
-This can reduce the amount of traffic between peers in most cases, and can help avoid a situation where a single large trace can cause a memory overrun on a single node.
+This can reduce the amount of traffic between peers, and can help avoid a situation where a single large trace can cause a memory overrun on a single node.
 If `distributed`, the amount of traffic between peers will be reduced, but the amount of traffic between Refinery and Redis will significantly increase, because Refinery uses Redis to distribute the trace decisions to all nodes in the cluster.
 It is important to adjust the size of the Redis cluster in this case.
-NOTE: This setting is not compatible with `DryRun` when set to true.
+The total volume of network traffic in `distributed` mode should be expected to decrease unless the cluster size is very large (hundreds of nodes).
+NOTE: This setting is not compatible with `DryRun` when set to `distributed`.
 See `DryRun` for more information.
 
 - Not eligible for live reload.

tools/convert/configDataNames.txt

@@ -1,5 +1,5 @@
 # Names of groups and fields in the new config file format.
-# Automatically generated on 2024-12-02 at 16:12:30 UTC.
+# Automatically generated on 2024-12-02 at 16:40:46 UTC.
 
 General:
   - ConfigurationVersion

tools/convert/minimal_config.yaml

@@ -1,5 +1,5 @@
 # sample uncommented config file containing all possible fields
-# automatically generated on 2024-12-02 at 16:12:31 UTC
+# automatically generated on 2024-12-02 at 16:40:47 UTC
 General:
   ConfigurationVersion: 2
   MinRefineryVersion: "v2.0"

tools/convert/templates/configV2.tmpl

@@ -2,7 +2,7 @@
 ## Honeycomb Refinery Configuration ##
 ######################################
 #
-# created {{ now }} from {{ .Input }} using a template generated on 2024-12-02 at 16:12:16 UTC
+# created {{ now }} from {{ .Input }} using a template generated on 2024-12-02 at 16:40:45 UTC
 
 # This file contains a configuration for the Honeycomb Refinery. It is in YAML
 # format, organized into named groups, each of which contains a set of
@@ -1078,25 +1078,26 @@ Collection:
     ## Eligible for live reload.
     {{ nonDefaultOnly .Data "ShutdownDelay" "ShutdownDelay" "15s" }}
 
-    ## TraceLocalityMode controls the how Refinery handles spans that belongs
-    ## to the same trace in a clustered environment.
+    ## TraceLocalityMode controls how Refinery handles spans that belongs to
+    ## the same trace in a clustered environment.
     ##
     ## When `concentrated`, Refinery will route all spans that belong to the
     ## same trace to a single peer. This is the default behavior ("Trace
     ## Locality") and the way Refinery has worked in the past. When
     ## `distributed`, Refinery will instead keep spans on the node where they
     ## were received, and forward proxy spans that contain only the key
     ## information needed to make a trace decision. This can reduce the
-    ## amount of traffic between peers in most cases, and can help avoid a
-    ## situation where a single large trace can cause a memory overrun on a
-    ## single node.
+    ## amount of traffic between peers, and can help avoid a situation where
+    ## a single large trace can cause a memory overrun on a single node.
     ## If `distributed`, the amount of traffic between peers will be reduced,
     ## but the amount of traffic between Refinery and Redis will
     ## significantly increase, because Refinery uses Redis to distribute the
     ## trace decisions to all nodes in the cluster. It is important to adjust
     ## the size of the Redis cluster in this case.
-    ## NOTE: This setting is not compatible with `DryRun` when set to true.
-    ## See `DryRun` for more information.
+    ## The total volume of network traffic in `distributed` mode should be
+    ## expected to decrease unless the cluster size is very large (hundreds
+    ## of nodes). NOTE: This setting is not compatible with `DryRun` when set
+    ## to `distributed`. See `DryRun` for more information.
     ##
     ## default: concentrated
     ## Not eligible for live reload.