maint: Update main documentation with 2.8.3 release (#1374)

## Which problem is this PR solving? - Updates main branch to include documentation from 2.8.3 release ## Short description of the changes - update changelog - update release notes - run `make all`. --------- Co-authored-by: Mike Goldsmith <goldsmith.mike@gmail.com>
honeycombio · Oct 10, 2024 · 4b93287 · 4b93287
1 parent 6b9389d
commit 4b93287
Show file tree

Hide file tree

Showing 12 changed files with 140 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Refinery Changelog
 
+## 2.8.3 2024-10-08
+
+### Changes 
+
+- fix: Only set incoming user agent if not already present (#1366) | [Mike Goldsmith](https://github.com/MikeGoldsmith)
+- fix: Put a limit on the size of sampler keys (#1364) | [Kent Quirk](https://github.com/kentquirk)
+- feat: Record original user agent for spans and logs (#1358) | [Mike Goldsmith](https://github.com/MikeGoldsmith)
+- feat: Make collector health check timeout configurable (#1371) | [Yingrong Zhao](https://github.com/vinozzZ)
+- fix: ConvertNumeric now handles bools (#1336) | [Kent Quirk](https://github.com/kentquirk)
 
 ## 2.8.2 2024-09-13
 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -2,6 +2,16 @@
 
 While [CHANGELOG.md](./CHANGELOG.md) contains detailed documentation and links to all the source code changes in a given release, this document is intended to be aimed at a more comprehensible version of the contents of the release from the point of view of users of Refinery.
 
+## Version 2.8.3
+
+This is a bug fix release and includes the follow changes+~+:
+* Fixes a bug when building sampler key using a very high cardinality field. The fix is to only take the first 100 unique field values.
+* Fixes a bug so the `is_alive` and `is_ready` metrics now report either 0 or 1 correctly.
+
+It also adds support for Refinery to record the original sender user agent in event data under the key `meta.refinery.incoming_user_agent` adds a configurtion option for the health check timeout.
+
+It also adds support for configuring the timeout of the Collection health check subsystem. If your readiness or liveness probes are failing often due to the `collector` subsystem, you can increase `Collection.HealthCheckTimeout` to give the `collector` subsystem more time before it is considered unhealthy.
+
 ## Version 2.8.2
 
 This is a bug fix release.

diff --git a/collect/collect.go b/collect/collect.go
@@ -129,6 +129,7 @@ var inMemCollectorMetrics = []metrics.Metadata{
 	{Name: "trace_kept_sample_rate", Type: metrics.Histogram, Unit: metrics.Dimensionless, Description: "sample rate of kept traces"},
 	{Name: "trace_aggregate_sample_rate", Type: metrics.Histogram, Unit: metrics.Dimensionless, Description: "aggregate sample rate of both kept and dropped traces"},
 	{Name: "collector_redistribute_traces_duration_ms", Type: metrics.Histogram, Unit: metrics.Milliseconds, Description: "duration of redistributing traces to peers"},
+	{Name: "collector_collect_loop_duration_ms", Type: metrics.Gauge, Unit: metrics.Milliseconds, Description: "duration of the collect loop, the primary event processing goroutine"},
 }
 
 func (i *InMemCollector) Start() error {

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-09-13 at 18:50:43 UTC.
+It was automatically generated on 2024-10-10 at 17:01:39 UTC.
 
 ## The Config file
 
@@ -192,7 +192,7 @@ The exact behavior depends on the value of `SendKeyMode`.
 
 SendKeyMode controls how SendKey is used to replace or augment API keys used in incoming telemetry.
 
-Controls how SendKey is used to replace or supply API keys used in incoming telemetry.
+controls how SendKey is used to replace or supply API keys used in incoming telemetry.
 If `AcceptOnlyListedKeys` is `true`, then `SendKeys` will only be used for events with keys listed in `ReceiveKeys`.
 `none` uses the incoming key for all telemetry (default).
 `all` overwrites all keys, even missing ones, with `SendKey`.
@@ -982,6 +982,27 @@ This value should be set to a bit less than the normal timeout period for shutti
 - Type: `duration`
 - Default: `15s`
 
+### `EnableTraceLocality`
+
+EnableTraceLocality controls whether all spans that belongs to the same trace are sent to a single Refinery for processing.
+
+If `true`, Refinery's will route all spans that belongs to the same trace to a single peer.
+
+- Eligible for live reload.
+- Type: `bool`
+
+### `HealthCheckTimeout`
+
+HealthCheckTimeout controls the maximum duration allowed for collection health checks to complete.
+
+The `HealthCheckTimeout` setting specifies the maximum duration allowed for the health checks of the collection subsystems to complete.
+If a subsystem does not respond within this timeout period, it will be marked as unhealthy.
+This timeout value should be set carefully to ensure that transient delays do not lead to unnecessary failure detection while still allowing for timely identification of actual health issues.
+
+- Not eligible for live reload.
+- Type: `duration`
+- Default: `3s`
+
 ## Buffer Sizes
 
 `BufferSizes` contains the settings that are relevant to the sizes of communications buffers.

diff --git a/config_complete.yaml b/config_complete.yaml
@@ -2,7 +2,7 @@
 ## Honeycomb Refinery Configuration ##
 ######################################
 #
-# created on 2024-09-13 at 18:50:42 UTC from ../../config.yaml using a template generated on 2024-09-13 at 18:50:40 UTC
+# created on 2024-10-10 at 17:01:39 UTC from ../../config.yaml using a template generated on 2024-10-10 at 17:01:33 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
@@ -176,7 +176,7 @@ AccessKeys:
     ## SendKeyMode controls how SendKey is used to replace or augment API
     ## keys used in incoming telemetry.
     ##
-    ## Controls how SendKey is used to replace or supply API keys used in
+    ## controls how SendKey is used to replace or supply API keys used in
     ## incoming telemetry. If `AcceptOnlyListedKeys` is `true`, then
     ## `SendKeys` will only be used for events with keys listed in
     ## `ReceiveKeys`.
@@ -1036,6 +1036,31 @@ Collection:
     ## Eligible for live reload.
     # ShutdownDelay: 15s
 
+    ## EnableTraceLocality controls whether all spans that belongs to the
+    ## same trace are sent to a single Refinery for processing.
+    ##
+    ## If `true`, Refinery's will route all spans that belongs to the same
+    ## trace to a single peer.
+    ##
+    ## Eligible for live reload.
+    # EnableTraceLocality: false
+
+    ## HealthCheckTimeout controls the maximum duration allowed for
+    ## collection health checks to complete.
+    ##
+    ## The `HealthCheckTimeout` setting specifies the maximum duration
+    ## allowed for the health checks of the collection subsystems to
+    ## complete. If a subsystem does not respond within this timeout period,
+    ## it will be marked as unhealthy. This timeout value should be set
+    ## carefully to ensure that transient delays do not lead to unnecessary
+    ## failure detection while still allowing for timely identification of
+    ## actual health issues.
+    ##
+    ## Accepts a duration string with units, like "3s".
+    ## default: 3s
+    ## Not eligible for live reload.
+    # HealthCheckTimeout: 3s
+
 ##################
 ## Buffer Sizes ##
 ##################
@@ -1110,8 +1135,8 @@ Specialized:
     ##
     ## Eligible for live reload.
     # AdditionalAttributes:
-      #  ClusterName: MyCluster
       #  environment: production
+      #  ClusterName: MyCluster
 
 ###############
 ## ID Fields ##

diff --git a/metrics.md b/metrics.md
@@ -1,7 +1,7 @@
 # Honeycomb Refinery Metrics Documentation
 
 This document contains the description of various metrics used in Refinery.
-It was automatically generated on 2024-09-27 at 16:19:55 UTC.
+It was automatically generated on 2024-10-10 at 17:01:38 UTC.
 
 Note: This document does not include metrics defined in the dynsampler-go dependency, as those metrics are generated dynamically at runtime. As a result, certain metrics may be missing or incomplete in this document, but they will still be available during execution with their full names.
 
@@ -58,6 +58,8 @@ This table includes metrics with fully defined names.
 | dropped_from_stress | Counter | Dimensionless | number of traces dropped due to stress relief |
 | trace_kept_sample_rate | Histogram | Dimensionless | sample rate of kept traces |
 | trace_aggregate_sample_rate | Histogram | Dimensionless | aggregate sample rate of both kept and dropped traces |
+| collector_redistribute_traces_duration_ms | Histogram | Milliseconds | duration of redistributing traces to peers |
+| collector_collect_loop_duration_ms | Gauge | Milliseconds | duration of the collect loop, the primary event processing goroutine |
 | cluster_stress_level | Gauge | Dimensionless | The overall stress level of the cluster |
 | individual_stress_level | Gauge | Dimensionless | The stress level of the individual node |
 | stress_level | Gauge | Dimensionless | The stress level that's being used to determine whether to activate stress relief |

diff --git a/refinery_config.md b/refinery_config.md
@@ -168,7 +168,7 @@ The exact behavior depends on the value of `SendKeyMode`.
 
 `SendKeyMode` controls how SendKey is used to replace or augment API keys used in incoming telemetry.
 
-Controls how SendKey is used to replace or supply API keys used in incoming telemetry.
+controls how SendKey is used to replace or supply API keys used in incoming telemetry.
 If `AcceptOnlyListedKeys` is `true`, then `SendKeys` will only be used for events with keys listed in `ReceiveKeys`.
 `none` uses the incoming key for all telemetry (default).
 `all` overwrites all keys, even missing ones, with `SendKey`.
@@ -967,6 +967,27 @@ This value should be set to a bit less than the normal timeout period for shutti
 - Type: `duration`
 - Default: `15s`
 
+### `EnableTraceLocality`
+
+`EnableTraceLocality` controls whether all spans that belongs to the same trace are sent to a single Refinery for processing.
+
+If `true`, Refinery's will route all spans that belongs to the same trace to a single peer.
+
+- Eligible for live reload.
+- Type: `bool`
+
+### `HealthCheckTimeout`
+
+`HealthCheckTimeout` controls the maximum duration allowed for collection health checks to complete.
+
+The `HealthCheckTimeout` setting specifies the maximum duration allowed for the health checks of the collection subsystems to complete.
+If a subsystem does not respond within this timeout period, it will be marked as unhealthy.
+This timeout value should be set carefully to ensure that transient delays do not lead to unnecessary failure detection while still allowing for timely identification of actual health issues.
+
+- Not eligible for live reload.
+- Type: `duration`
+- Default: `3s`
+
 ## Buffer Sizes
 
 `BufferSizes` contains the settings that are relevant to the sizes of communications buffers.

diff --git a/rules.md b/rules.md
@@ -1,7 +1,7 @@
 # Honeycomb Refinery Rules Documentation
 
 This is the documentation for the rules configuration for Honeycomb's Refinery.
-It was automatically generated on 2024-09-03 at 19:48:56 UTC.
+It was automatically generated on 2024-10-10 at 17:01:40 UTC.
 
 ## The Rules file
 

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-09-03 at 19:48:53 UTC.
+# Automatically generated on 2024-10-10 at 17:01:34 UTC.
 
 General:
   - ConfigurationVersion
@@ -188,6 +188,10 @@ Collection:
 
   - ShutdownDelay
 
+  - EnableTraceLocality
+
+  - HealthCheckTimeout
+
 
 BufferSizes:
   - UpstreamBufferSize

diff --git a/tools/convert/metricsMeta.yaml b/tools/convert/metricsMeta.yaml
@@ -191,6 +191,14 @@ complete:
       type: Histogram
       unit: Dimensionless
       description: aggregate sample rate of both kept and dropped traces
+    - name: collector_redistribute_traces_duration_ms
+      type: Histogram
+      unit: Milliseconds
+      description: duration of redistributing traces to peers
+    - name: collector_collect_loop_duration_ms
+      type: Gauge
+      unit: Milliseconds
+      description: duration of the collect loop, the primary event processing goroutine
     - name: cluster_stress_level
       type: Gauge
       unit: Dimensionless

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-09-03 at 19:48:53 UTC
+# automatically generated on 2024-10-10 at 17:01:35 UTC
 General:
   ConfigurationVersion: 2
   MinRefineryVersion: "v2.0"
@@ -103,6 +103,8 @@ Collection:
   MaxAlloc: 0
   DisableRedistribution: false
   ShutdownDelay: 15s
+  EnableTraceLocality: false
+  HealthCheckTimeout: 3s
 BufferSizes:
   UpstreamBufferSize: 10_000
   PeerBufferSize: 100_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-09-13 at 18:50:40 UTC
+# created {{ now }} from {{ .Input }} using a template generated on 2024-10-10 at 17:01:33 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
@@ -175,7 +175,7 @@ AccessKeys:
     ## SendKeyMode controls how SendKey is used to replace or augment API
     ## keys used in incoming telemetry.
     ##
-    ## Controls how SendKey is used to replace or supply API keys used in
+    ## controls how SendKey is used to replace or supply API keys used in
     ## incoming telemetry. If `AcceptOnlyListedKeys` is `true`, then
     ## `SendKeys` will only be used for events with keys listed in
     ## `ReceiveKeys`.
@@ -1031,6 +1031,31 @@ Collection:
     ## Eligible for live reload.
     {{ nonDefaultOnly .Data "ShutdownDelay" "ShutdownDelay" "15s" }}
 
+    ## EnableTraceLocality controls whether all spans that belongs to the
+    ## same trace are sent to a single Refinery for processing.
+    ##
+    ## If `true`, Refinery's will route all spans that belongs to the same
+    ## trace to a single peer.
+    ##
+    ## Eligible for live reload.
+    {{ nonDefaultOnly .Data "EnableTraceLocality" "EnableTraceLocality" false }}
+
+    ## HealthCheckTimeout controls the maximum duration allowed for
+    ## collection health checks to complete.
+    ##
+    ## The `HealthCheckTimeout` setting specifies the maximum duration
+    ## allowed for the health checks of the collection subsystems to
+    ## complete. If a subsystem does not respond within this timeout period,
+    ## it will be marked as unhealthy. This timeout value should be set
+    ## carefully to ensure that transient delays do not lead to unnecessary
+    ## failure detection while still allowing for timely identification of
+    ## actual health issues.
+    ##
+    ## Accepts a duration string with units, like "3s".
+    ## default: 3s
+    ## Not eligible for live reload.
+    {{ nonDefaultOnly .Data "HealthCheckTimeout" "HealthCheckTimeout" "3s" }}
+
 ##################
 ## Buffer Sizes ##
 ##################