generate docs

honeycombio · Dec 2, 2024 · 7d674ad · 7d674ad
1 parent dcae950
commit 7d674ad
Show file tree

Hide file tree

Showing 6 changed files with 63 additions and 57 deletions.
diff --git a/config.md b/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-11-26 at 18:43:37 UTC.
+It was automatically generated on 2024-12-02 at 16:12:36 UTC.
 
 ## The Config file
 
@@ -402,7 +402,7 @@ This is useful for evaluating sampling rules.
 When DryRun is enabled, traces is decorated with `meta.refinery.
 dryrun.kept` that is set to `true` or `false`, based on whether the trace would be kept or dropped.
 In addition, `SampleRate` will be set to the incoming rate for all traces, and the field `meta.refinery.dryrun.sample_rate` will be set to the sample rate that would have been used.
-NOTE: This setting is not compatible with `DisableTraceLocality=true`, because drop trace decisions shared among peers do not contain all the relevant information needed to send traces to Honeycomb.
+NOTE: This setting is not compatible with `TraceCache=distributed`, because drop trace decisions shared among peers do not contain all the relevant information needed to send traces to Honeycomb.
 
 - Eligible for live reload.
 - Type: `bool`
@@ -1021,21 +1021,22 @@ This value should be set to a bit less than the normal timeout period for shutti
 - Type: `duration`
 - Default: `15s`
 
-### `DisableTraceLocality`
+### `TraceLocalityMode`
 
-DisableTraceLocality controls whether all spans that belongs to the same trace are sent to a single Refinery for processing.
+TraceLocalityMode controls the how Refinery handles spans that belongs to the same trace in a clustered environment.
 
-When `false`, Refinery will route all spans that belong to the same trace to a single peer.
+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 `true`, 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.
+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.
-If `true`, 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.
+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.
 
 - Not eligible for live reload.
-- Type: `bool`
+- Type: `string`
+- Default: `concentrated`
 
 ### `HealthCheckTimeout`
 

diff --git a/config_complete.yaml b/config_complete.yaml
@@ -2,7 +2,7 @@
 ## Honeycomb Refinery Configuration ##
 ######################################
 #
-# created on 2024-11-22 at 17:59:57 UTC from ../../config.yaml using a template generated on 2024-11-22 at 17:59:50 UTC
+# 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
 
 # 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
@@ -427,7 +427,7 @@ Debugging:
     ## to the incoming rate for all traces, and the field
     ## `meta.refinery.dryrun.sample_rate` will be set to the sample rate that
     ## would have been used.
-    ## NOTE: This setting is not compatible with `DisableTraceLocality=true`,
+    ## NOTE: This setting is not compatible with `TraceCache=distributed`,
     ## because drop trace decisions shared among peers do not contain all the
     ## relevant information needed to send traces to Honeycomb.
     ##
@@ -1083,27 +1083,29 @@ Collection:
     ## Eligible for live reload.
     # ShutdownDelay: 15s
 
-    ## DisableTraceLocality controls whether all spans that belongs to the
-    ## same trace are sent to a single Refinery for processing.
-    ##
-    ## When `false`, 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 `true`,
-    ## 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.
-    ## If `true`, 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.
+    ## TraceLocalityMode controls the 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.
+    ## 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.
     ##
+    ## default: concentrated
     ## Not eligible for live reload.
-    # DisableTraceLocality: false
+    # TraceLocalityMode: concentrated
 
     ## HealthCheckTimeout controls the maximum duration allowed for
     ## collection health checks to complete.

diff --git a/refinery_config.md b/refinery_config.md
@@ -381,7 +381,7 @@ This is useful for evaluating sampling rules.
 When DryRun is enabled, traces is decorated with `meta.refinery.
 dryrun.kept` that is set to `true` or `false`, based on whether the trace would be kept or dropped.
 In addition, `SampleRate` will be set to the incoming rate for all traces, and the field `meta.refinery.dryrun.sample_rate` will be set to the sample rate that would have been used.
-NOTE: This setting is not compatible with `DisableTraceLocality=true`, because drop trace decisions shared among peers do not contain all the relevant information needed to send traces to Honeycomb.
+NOTE: This setting is not compatible with `TraceCache=distributed`, because drop trace decisions shared among peers do not contain all the relevant information needed to send traces to Honeycomb.
 
 - Eligible for live reload.
 - Type: `bool`
@@ -1006,21 +1006,22 @@ This value should be set to a bit less than the normal timeout period for shutti
 - Type: `duration`
 - Default: `15s`
 
-### `DisableTraceLocality`
+### `TraceLocalityMode`
 
-`DisableTraceLocality` controls whether all spans that belongs to the same trace are sent to a single Refinery for processing.
+`TraceLocalityMode` controls the how Refinery handles spans that belongs to the same trace in a clustered environment.
 
-When `false`, Refinery will route all spans that belong to the same trace to a single peer.
+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 `true`, 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.
+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.
-If `true`, 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.
+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.
 
 - Not eligible for live reload.
-- Type: `bool`
+- Type: `string`
+- Default: `concentrated`
 
 ### `HealthCheckTimeout`
 

diff --git a/tools/convert/configDataNames.txt b/tools/convert/configDataNames.txt
@@ -1,5 +1,5 @@
 # Names of groups and fields in the new config file format.
-# Automatically generated on 2024-11-22 at 17:59:51 UTC.
+# Automatically generated on 2024-12-02 at 16:12:30 UTC.
 
 General:
   - ConfigurationVersion
@@ -194,7 +194,7 @@ Collection:
 
   - ShutdownDelay
 
-  - DisableTraceLocality
+  - TraceLocalityMode
 
   - HealthCheckTimeout
 

diff --git a/tools/convert/minimal_config.yaml b/tools/convert/minimal_config.yaml
@@ -1,5 +1,5 @@
 # sample uncommented config file containing all possible fields
-# automatically generated on 2024-11-22 at 18:35:03 UTC
+# automatically generated on 2024-12-02 at 16:12:31 UTC
 General:
   ConfigurationVersion: 2
   MinRefineryVersion: "v2.0"
@@ -103,7 +103,7 @@ Collection:
   DisableRedistribution: false
   RedistributionDelay: 30s
   ShutdownDelay: 15s
-  DisableTraceLocality: false
+  TraceLocalityMode: concentrated
   HealthCheckTimeout: 3s
 BufferSizes:
   UpstreamBufferSize: 10_000

diff --git a/tools/convert/templates/configV2.tmpl b/tools/convert/templates/configV2.tmpl
@@ -2,7 +2,7 @@
 ## Honeycomb Refinery Configuration ##
 ######################################
 #
-# created {{ now }} from {{ .Input }} using a template generated on 2024-11-22 at 17:59:50 UTC
+# created {{ now }} from {{ .Input }} using a template generated on 2024-12-02 at 16:12:16 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
@@ -425,7 +425,7 @@ Debugging:
     ## to the incoming rate for all traces, and the field
     ## `meta.refinery.dryrun.sample_rate` will be set to the sample rate that
     ## would have been used.
-    ## NOTE: This setting is not compatible with `DisableTraceLocality=true`,
+    ## NOTE: This setting is not compatible with `TraceCache=distributed`,
     ## because drop trace decisions shared among peers do not contain all the
     ## relevant information needed to send traces to Honeycomb.
     ##
@@ -1078,27 +1078,29 @@ Collection:
     ## Eligible for live reload.
     {{ nonDefaultOnly .Data "ShutdownDelay" "ShutdownDelay" "15s" }}
 
-    ## DisableTraceLocality controls whether all spans that belongs to the
-    ## same trace are sent to a single Refinery for processing.
-    ##
-    ## When `false`, 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 `true`,
-    ## 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.
-    ## If `true`, 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.
+    ## TraceLocalityMode controls the 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.
+    ## 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.
     ##
+    ## default: concentrated
     ## Not eligible for live reload.
-    {{ nonDefaultOnly .Data "DisableTraceLocality" "DisableTraceLocality" false }}
+    {{ nonDefaultOnly .Data "TraceLocalityMode" "TraceLocalityMode" "concentrated" }}
 
     ## HealthCheckTimeout controls the maximum duration allowed for
     ## collection health checks to complete.