maint: Respond to docs feedback. (#931)

## Which problem is this PR solving? - Respond to docs feedback on [this PR](honeycombio/docs#2013) ## Short description of the changes - Update metadata - Regenerate files
honeycombio · Dec 4, 2023 · f43cfb1 · f43cfb1
1 parent 942ebb1
commit f43cfb1
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 46 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 2023-12-04 at 18:06:13 UTC.
+It was automatically generated on 2023-12-04 at 22:34:13 UTC.
 
 ## The Config file
 
@@ -207,7 +207,11 @@ If `true` and `AddCountsToRoot` is set to false, then Refinery will add `meta.sp
 
 AddCountsToRoot controls whether to add metadata fields to root spans that indicates the number of child spans, span events, span links, and honeycomb events.
 
-If `true`, then Refinery will ignore the `AddSpanCountToRoot` setting and add the following fields to the root span based on the values at the time the sampling decision was made: - `meta.span_count`: the number of child spans on the trace - `meta.span_event_count`: the number of span events on the trace - `meta.span_link_count`: the number of span links on the trace - `meta.event_count`: the number of honeycomb events on the trace
+If `true`, then Refinery will ignore the `AddSpanCountToRoot` setting and add the following fields to the root span based on the values at the time the sampling decision was made:
+- `meta.span_count`: the number of child spans on the trace
+- `meta.span_event_count`: the number of span events on the trace
+- `meta.span_link_count`: the number of span links on the trace
+- `meta.event_count`: the number of honeycomb events on the trace
 
 - Eligible for live reload.
 - Type: `bool`
@@ -442,7 +446,7 @@ Structured controls whether to use structured logging.
 
 ### `SamplerEnabled`
 
-SamplerEnabled controls whether logs are sampled before sending to stdout.
+SamplerEnabled controls whether logs are sampled before sending to `stdout`.
 
 The sample rate is controlled by the `SamplerThroughput` setting.
 
@@ -453,7 +457,7 @@ The sample rate is controlled by the `SamplerThroughput` setting.
 
 SamplerThroughput is the sampling throughput for logs in events per second.
 
-The sampling algorithm attempts to make sure that the average throughput approximates this value, while also ensuring that all unique logs arrive at stdout at least once per sampling period.
+The sampling algorithm attempts to make sure that the average throughput approximates this value, while also ensuring that all unique logs arrive at `stdout` at least once per sampling period.
 
 - Not eligible for live reload.
 - Type: `float`
@@ -796,7 +800,7 @@ The peer span queue serves as a buffer for spans redirected from other peers bef
 In the event that this queue reaches its capacity, any subsequent spans will be discarded.
 The size of this queue is contingent upon the number of peers within the cluster.
 Specifically, with N peers, the queue's span capacity is determined by (N-1)/N of the total number of spans.
-Its minimum value should be at least three times the CacheCapacity.
+Its minimum value should be at least three times the `CacheCapacity`.
 
 - Not eligible for live reload.
 - Type: `int`
@@ -808,7 +812,7 @@ IncomingQueueSize is the number of in-flight spans to keep in the incoming span
 
 The incoming span queue is used to buffer spans before they are processed.
 If this queue fills up, then subsequent spans will be dropped.
-Its minimum value should be at least three times the CacheCapacity.
+Its minimum value should be at least three times the `CacheCapacity`.
 
 - Not eligible for live reload.
 - Type: `int`
@@ -821,7 +825,7 @@ AvailableMemory is the amount of system memory available to the Refinery process
 This value will typically be set through an environment variable controlled by the container or deploy script.
 If this value is zero or not set, then `MaxMemoryPercentage` cannot be used to calculate the maximum allocation and `MaxAlloc` will be used instead.
 If set, then this must be a memory size.
-Sizes with standard unit suffixes (`MB`, `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.) are supported.
+Sizes with standard unit suffixes (such as `MB` and `GiB`) and Kubernetes units (such as `M` and `Gi`) are supported.
 Fractional values with a suffix are supported.
 If `AvailableMemory` is set, `Collections.MaxAlloc` must not be defined.
 
@@ -850,7 +854,7 @@ Useful values for this setting are generally in the range of 70-90.
 MaxAlloc is the maximum number of bytes that should be allocated by the Collector.
 
 If set, then this must be a memory size.
-Sizes with standard unit suffixes (`MB`, `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.) are supported.
+Sizes with standard unit suffixes (such as `MB` and `GiB`) and Kubernetes units (such as `M` and `Gi`) are supported.
 Fractional values with a suffix are supported.
 See `MaxMemoryPercentage` for more details.
 If set, `Collections.AvailableMemory` must not be defined.

diff --git a/config/metadata/configMeta.yaml b/config/metadata/configMeta.yaml
@@ -232,9 +232,13 @@ groups:
         description: >
           If `true`, then Refinery will ignore the `AddSpanCountToRoot` setting and add the following fields to the root
           span based on the values at the time the sampling decision was made:
+
           - `meta.span_count`: the number of child spans on the trace
+
           - `meta.span_event_count`: the number of span events on the trace
+
           - `meta.span_link_count`: the number of span links on the trace
+
           - `meta.event_count`: the number of honeycomb events on the trace
 
       - name: AddHostMetadataToTrace
@@ -521,7 +525,7 @@ groups:
         valuetype: nondefault
         default: false
         reload: false
-        summary: controls whether logs are sampled before sending to stdout.
+        summary: controls whether logs are sampled before sending to `stdout`.
         description: >
           The sample rate is controlled by the `SamplerThroughput` setting.
 
@@ -535,7 +539,7 @@ groups:
         description: >
           The sampling algorithm attempts to make sure that the average
           throughput approximates this value, while also ensuring that all
-          unique logs arrive at stdout at least once per sampling
+          unique logs arrive at `stdout` at least once per sampling
           period.
   - name: PrometheusMetrics
     title: "Prometheus Metrics"
@@ -1008,7 +1012,7 @@ groups:
           In the event that this queue reaches its capacity, any subsequent spans will be discarded. The size of this
           queue is contingent upon the number of peers within the cluster. Specifically, with N peers, the queue's span
           capacity is determined by (N-1)/N of the total number of spans.
-          Its minimum value should be at least three times the CacheCapacity.
+          Its minimum value should be at least three times the `CacheCapacity`.
 
       - name: IncomingQueueSize
         type: int
@@ -1019,7 +1023,7 @@ groups:
         description: >
           The incoming span queue is used to buffer spans before they are processed.
           If this queue fills up, then subsequent spans will be dropped.
-          Its minimum value should be at least three times the CacheCapacity.
+          Its minimum value should be at least three times the `CacheCapacity`.
 
       - name: AvailableMemory
         type: memorysize
@@ -1032,12 +1036,12 @@ groups:
         description: >
           This value will typically be set through an environment variable
           controlled by the container or deploy script. If this value is zero or
-          not set, then `MaxMemoryPercentage` cannot be used to calculate the maximum
-          allocation and `MaxAlloc` will be used instead. If set, then this must
-          be a memory size. Sizes with standard unit suffixes (`MB`, `GiB`,
-          etc.) and Kubernetes units (`M`, `Gi`, etc.) are supported. Fractional
-          values with a suffix are supported. If `AvailableMemory` is set,
-          `Collections.MaxAlloc` must not be defined.
+          not set, then `MaxMemoryPercentage` cannot be used to calculate the
+          maximum allocation and `MaxAlloc` will be used instead. If set, then
+          this must be a memory size. Sizes with standard unit suffixes (such as
+          `MB` and `GiB`) and Kubernetes units (such as `M` and `Gi`) are
+          supported. Fractional values with a suffix are supported. If
+          `AvailableMemory` is set, `Collections.MaxAlloc` must not be defined.
 
       - name: MaxMemoryPercentage
         type: percentage
@@ -1073,10 +1077,10 @@ groups:
         summary: is the maximum number of bytes that should be allocated by the Collector.
         description: >
           If set, then this must be a memory size. Sizes with standard unit
-          suffixes (`MB`, `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.)
-          are supported. Fractional values with a suffix are supported. See
-          `MaxMemoryPercentage` for more details. If set, `Collections.AvailableMemory`
-          must not be defined.
+          suffixes (such as `MB` and `GiB`) and Kubernetes units (such as `M`
+          and `Gi`) are supported. Fractional values with a suffix are
+          supported. See `MaxMemoryPercentage` for more details. If set,
+          `Collections.AvailableMemory` must not be defined.
 
   - name: BufferSizes
     title: "Buffer Sizes"

diff --git a/refinery_config.md b/refinery_config.md
@@ -185,7 +185,11 @@ If `true` and `AddCountsToRoot` is set to false, then Refinery will add `meta.sp
 
 `AddCountsToRoot` controls whether to add metadata fields to root spans that indicates the number of child spans, span events, span links, and honeycomb events.
 
-If `true`, then Refinery will ignore the `AddSpanCountToRoot` setting and add the following fields to the root span based on the values at the time the sampling decision was made: - `meta.span_count`: the number of child spans on the trace - `meta.span_event_count`: the number of span events on the trace - `meta.span_link_count`: the number of span links on the trace - `meta.event_count`: the number of honeycomb events on the trace
+If `true`, then Refinery will ignore the `AddSpanCountToRoot` setting and add the following fields to the root span based on the values at the time the sampling decision was made:
+- `meta.span_count`: the number of child spans on the trace
+- `meta.span_event_count`: the number of span events on the trace
+- `meta.span_link_count`: the number of span links on the trace
+- `meta.event_count`: the number of honeycomb events on the trace
 
 - Eligible for live reload.
 - Type: `bool`
@@ -425,7 +429,7 @@ Only used if `Logger.Type` is "stdout".
 
 ### `SamplerEnabled`
 
-`SamplerEnabled` controls whether logs are sampled before sending to stdout.
+`SamplerEnabled` controls whether logs are sampled before sending to `stdout`.
 
 The sample rate is controlled by the `SamplerThroughput` setting.
 
@@ -436,7 +440,7 @@ The sample rate is controlled by the `SamplerThroughput` setting.
 
 `SamplerThroughput` is the sampling throughput for logs in events per second.
 
-The sampling algorithm attempts to make sure that the average throughput approximates this value, while also ensuring that all unique logs arrive at stdout at least once per sampling period.
+The sampling algorithm attempts to make sure that the average throughput approximates this value, while also ensuring that all unique logs arrive at `stdout` at least once per sampling period.
 
 - Not eligible for live reload.
 - Type: `float`
@@ -781,7 +785,7 @@ The peer span queue serves as a buffer for spans redirected from other peers bef
 In the event that this queue reaches its capacity, any subsequent spans will be discarded.
 The size of this queue is contingent upon the number of peers within the cluster.
 Specifically, with N peers, the queue's span capacity is determined by (N-1)/N of the total number of spans.
-Its minimum value should be at least three times the CacheCapacity.
+Its minimum value should be at least three times the `CacheCapacity`.
 
 - Not eligible for live reload.
 - Type: `int`
@@ -793,7 +797,7 @@ Its minimum value should be at least three times the CacheCapacity.
 
 The incoming span queue is used to buffer spans before they are processed.
 If this queue fills up, then subsequent spans will be dropped.
-Its minimum value should be at least three times the CacheCapacity.
+Its minimum value should be at least three times the `CacheCapacity`.
 
 - Not eligible for live reload.
 - Type: `int`
@@ -806,7 +810,7 @@ Its minimum value should be at least three times the CacheCapacity.
 This value will typically be set through an environment variable controlled by the container or deploy script.
 If this value is zero or not set, then `MaxMemoryPercentage` cannot be used to calculate the maximum allocation and `MaxAlloc` will be used instead.
 If set, then this must be a memory size.
-Sizes with standard unit suffixes (`MB`, `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.) are supported.
+Sizes with standard unit suffixes (such as `MB` and `GiB`) and Kubernetes units (such as `M` and `Gi`) are supported.
 Fractional values with a suffix are supported.
 If `AvailableMemory` is set, `Collections.MaxAlloc` must not be defined.
 
@@ -835,7 +839,7 @@ Useful values for this setting are generally in the range of 70-90.
 `MaxAlloc` is the maximum number of bytes that should be allocated by the Collector.
 
 If set, then this must be a memory size.
-Sizes with standard unit suffixes (`MB`, `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.) are supported.
+Sizes with standard unit suffixes (such as `MB` and `GiB`) and Kubernetes units (such as `M` and `Gi`) are supported.
 Fractional values with a suffix are supported.
 See `MaxMemoryPercentage` for more details.
 If set, `Collections.AvailableMemory` must not be defined.

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 2023-12-04 at 18:06:10 UTC
+# created {{ now }} from {{ .Input }} using a template generated on 2023-12-04 at 22:34:11 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
@@ -205,11 +205,11 @@ RefineryTelemetry:
     ##
     ## If `true`, then Refinery will ignore the `AddSpanCountToRoot` setting
     ## and add the following fields to the root span based on the values at
-    ## the time the sampling decision was made: - `meta.span_count`: the
-    ## number of child spans on the trace - `meta.span_event_count`: the
-    ## number of span events on the trace - `meta.span_link_count`: the
-    ## number of span links on the trace - `meta.event_count`: the number of
-    ## honeycomb events on the trace
+    ## the time the sampling decision was made:
+    ## - `meta.span_count`: the number of child spans on the trace
+    ## - `meta.span_event_count`: the number of span events on the trace
+    ## - `meta.span_link_count`: the number of span links on the trace
+    ## - `meta.event_count`: the number of honeycomb events on the trace
     ##
     ## Eligible for live reload.
     {{ nonDefaultOnly .Data "AddCountsToRoot" "AddCountsToRoot" false }}
@@ -455,7 +455,7 @@ StdoutLogger:
     {{ nonDefaultOnly .Data "Structured" "Structured" false }}
 
     ## SamplerEnabled controls whether logs are sampled before sending to
-    ## stdout.
+    ## `stdout`.
     ##
     ## The sample rate is controlled by the `SamplerThroughput` setting.
     ##
@@ -467,7 +467,7 @@ StdoutLogger:
     ##
     ## The sampling algorithm attempts to make sure that the average
     ## throughput approximates this value, while also ensuring that all
-    ## unique logs arrive at stdout at least once per sampling period.
+    ## unique logs arrive at `stdout` at least once per sampling period.
     ##
     ## default: 10
     ## Not eligible for live reload.
@@ -818,7 +818,7 @@ Collection:
     ## queue is contingent upon the number of peers within the cluster.
     ## Specifically, with N peers, the queue's span capacity is determined by
     ## (N-1)/N of the total number of spans. Its minimum value should be at
-    ## least three times the CacheCapacity.
+    ## least three times the `CacheCapacity`.
     ##
     ## default: 30000
     ## Not eligible for live reload.
@@ -830,7 +830,7 @@ Collection:
     ## The incoming span queue is used to buffer spans before they are
     ## processed. If this queue fills up, then subsequent spans will be
     ## dropped. Its minimum value should be at least three times the
-    ## CacheCapacity.
+    ## `CacheCapacity`.
     ##
     ## default: 30000
     ## Not eligible for live reload.
@@ -843,10 +843,10 @@ Collection:
     ## controlled by the container or deploy script. If this value is zero or
     ## not set, then `MaxMemoryPercentage` cannot be used to calculate the
     ## maximum allocation and `MaxAlloc` will be used instead. If set, then
-    ## this must be a memory size. Sizes with standard unit suffixes (`MB`,
-    ## `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.) are supported.
-    ## Fractional values with a suffix are supported. If `AvailableMemory` is
-    ## set, `Collections.MaxAlloc` must not be defined.
+    ## this must be a memory size. Sizes with standard unit suffixes (such as
+    ## `MB` and `GiB`) and Kubernetes units (such as `M` and `Gi`) are
+    ## supported. Fractional values with a suffix are supported. If
+    ## `AvailableMemory` is set, `Collections.MaxAlloc` must not be defined.
     ##
     ## Eligible for live reload.
     {{ memorysize .Data "AvailableMemory" "AvailableMemory" "4.5Gb" }}
@@ -870,9 +870,9 @@ Collection:
     ## the Collector.
     ##
     ## If set, then this must be a memory size. Sizes with standard unit
-    ## suffixes (`MB`, `GiB`, etc.) and Kubernetes units (`M`, `Gi`, etc.)
-    ## are supported. Fractional values with a suffix are supported. See
-    ## `MaxMemoryPercentage` for more details. If set,
+    ## suffixes (such as `MB` and `GiB`) and Kubernetes units (such as `M`
+    ## and `Gi`) are supported. Fractional values with a suffix are
+    ## supported. See `MaxMemoryPercentage` for more details. If set,
     ## `Collections.AvailableMemory` must not be defined.
     ##
     ## Eligible for live reload.