v0.34.0 doc sweep and update

internal/config/config.go

@@ -15,7 +15,6 @@ type Config struct {
 	// Selected file path is runtime metadata, never a configurable override.
 	ConfigFile string `toml:"-"`
 
-	// Existing fields
 	Logging   *LogConfig       `toml:"logging"`
 	Pipelines []PipelineConfig `toml:"pipelines"`
 }
@@ -79,15 +78,15 @@ type HeartbeatConfig struct {
 	Enabled          bool   `toml:"enabled" help:"send heartbeats"`
 	IntervalMS       int64  `toml:"interval_ms" default:"1000" lw:"min=100" help:"milliseconds between heartbeats"`
 	IncludeTimestamp bool   `toml:"include_timestamp" help:"stamp each heartbeat with its time"`
-	IncludeStats     bool   `toml:"include_stats" help:"add the pipeline's counters"`
-	Format           string `toml:"format" default:"txt" lw:"enum=txt|json|raw" help:"heartbeat format"`
+	IncludeStats     bool   `toml:"include_stats" help:"add type, beat_count and, from the second beat, the measured interval_ms"`
+	Format           string `toml:"format" default:"txt" lw:"enum=txt|json|raw" help:"no effect: heartbeats use the flow's format"`
 }
 
 // FormatConfig is how a pipeline writes its entries
 type FormatConfig struct {
 	Type            string `toml:"type" default:"raw" lw:"enum=raw|txt|json" help:"entry format"`
 	Flags           int64  `toml:"flags,omitempty" lw:"zero=by type" help:"formatter flags"`
-	TimestampFormat string `toml:"timestamp_format,omitempty" lw:"zero=RFC 3339" help:"Go time layout of timestamps"`
+	TimestampFormat string `toml:"timestamp_format,omitempty" lw:"zero=RFC 3339 with nanoseconds" help:"Go time layout of timestamps"`
 	SanitizerPolicy string `toml:"sanitizer_policy,omitempty" lw:"enum=raw|json|txt|shell,zero=by type" help:"how control characters are escaped"`
 }
 
@@ -143,7 +142,7 @@ type PluginSourceConfig struct {
 	ID         string         `toml:"id"`
 	Type       string         `toml:"type"`
 	Config     map[string]any `toml:"config"`
-	ConfigFile string         `toml:"config_file,omitempty"` // TODO: support for include/source mechanism for nested config
+	ConfigFile string         `toml:"config_file,omitempty"` // accepted, never read
 }
 
 // NullSourceOptions defines settings for a null source (no configuration needed)
@@ -152,10 +151,10 @@ type NullSourceOptions struct{}
 // RandomSourceOptions defines settings for a random log generator source
 type RandomSourceOptions struct {
 	IntervalMS int64  `toml:"interval_ms" default:"500" lw:"min=1" help:"milliseconds between entries"`
-	JitterMS   int64  `toml:"jitter_ms" lw:"min=0,zero=none" help:"random milliseconds added to the interval, at most the interval"`
+	JitterMS   int64  `toml:"jitter_ms" lw:"min=0,zero=none" help:"milliseconds the interval varies by, half each way; at most the interval"`
 	Format     string `toml:"format" default:"txt" lw:"enum=raw|txt|json" help:"entry format"`
-	Length     int64  `toml:"length" default:"20" lw:"min=1" help:"message characters"`
-	Special    bool   `toml:"special" help:"mix in control characters"`
+	Length     int64  `toml:"length" default:"20" lw:"min=1" help:"bytes of random text"`
+	Special    bool   `toml:"special" help:"mix in control and non-ASCII bytes"`
 }
 
 // FileSourceOptions defines settings for a file-based source
@@ -209,7 +208,7 @@ type PluginSinkConfig struct {
 	ID         string         `toml:"id"`
 	Type       string         `toml:"type"`
 	Config     map[string]any `toml:"config"`
-	ConfigFile string         `toml:"config_file,omitempty"` // TODO: support for include/source mechanism for nested config
+	ConfigFile string         `toml:"config_file,omitempty"` // accepted, never read
 }
 
 // NullSinkOptions defines settings for a null sink (no configuration needed)
@@ -230,7 +229,7 @@ type FileSinkOptions struct {
 	MaxSizeMB       int64   `toml:"max_size_mb" default:"100" lw:"min=1" help:"size at which a file rotates"`
 	MaxTotalSizeMB  int64   `toml:"max_total_size_mb" default:"1000" lw:"min=1" help:"size of all files, beyond which the oldest go"`
 	MinDiskFreeMB   int64   `toml:"min_disk_free_mb" lw:"zero=none" help:"free space kept on the disk; negative means 100"`
-	RetentionHours  float64 `toml:"retention_hours" default:"168" lw:"min=0" help:"hours a file is kept"`
+	RetentionHours  float64 `toml:"retention_hours" default:"168" lw:"min=0,zero=kept" help:"hours a .log file is kept; 0 keeps them"`
 	BufferSize      int64   `toml:"buffer_size" default:"1000" lw:"min=1" help:"entries queued"`
 	FlushIntervalMs int64   `toml:"flush_interval_ms" default:"100" lw:"min=1" help:"milliseconds between flushes"`
 }

internal/config/schema.go

@@ -42,13 +42,13 @@ type Plugin struct {
 var plugins = []Plugin{
 	{"source", "console", Local, false, true, "Standard input, line by line", reflect.TypeFor[ConsoleSourceOptions]()},
 	{"source", "file", Local, false, false, "Follow the files of a directory that match a pattern", reflect.TypeFor[FileSourceOptions]()},
-	{"source", "random", Local, false, false, "Random entries, for tests", reflect.TypeFor[RandomSourceOptions]()},
-	{"source", "null", Local, false, false, "Nothing, ever", reflect.TypeFor[NullSourceOptions]()},
+	{"source", "random", Local, false, false, "Generated entries, to check a deployment before real logs", reflect.TypeFor[RandomSourceOptions]()},
+	{"source", "null", Local, false, false, "Nothing; holds a source's place until one is chosen", reflect.TypeFor[NullSourceOptions]()},
 	{"source", "tcp_chain", ChainListener, false, false, "Entries from tcp_chain sinks of other instances", reflect.TypeFor[TCPChainSourceOptions]()},
 	{"source", "http_chain", ChainListener, true, false, "Entry batches from http_chain sinks of other instances", reflect.TypeFor[HTTPChainSourceOptions]()},
 	{"sink", "console", Local, false, false, "Standard output or standard error", reflect.TypeFor[ConsoleSinkOptions]()},
 	{"sink", "file", Local, false, false, "Rotating files", reflect.TypeFor[FileSinkOptions]()},
-	{"sink", "null", Local, false, false, "Discard", reflect.TypeFor[NullSinkOptions]()},
+	{"sink", "null", Local, false, false, "Discards; holds a sink's place until one is chosen", reflect.TypeFor[NullSinkOptions]()},
 	{"sink", "tcp", Listener, false, false, "Serve entries to TCP clients, one per line", reflect.TypeFor[TCPSinkOptions]()},
 	{"sink", "http", Listener, true, false, "Serve entries as server-sent events, with a browser viewer", reflect.TypeFor[HTTPSinkOptions]()},
 	{"sink", "tcp_chain", Dialer, false, false, "Forward entries to a tcp_chain source", reflect.TypeFor[TCPChainSinkOptions]()},

internal/config/schema_test.go

@@ -32,10 +32,11 @@ func TestEveryRowDecodesFromItsRequiredKeys(t *testing.T) {
 	}
 }
 
-// A zero number takes the default unless zero means something there, a switch
-// that defaults on stays off when set off, a negative number is refused, and
-// what moved from the constructors keeps its meaning: min_disk_free_mb below
-// zero is the default, a backoff maximum below the minimum the default maximum
+// A zero number takes the default unless zero means something there (a file
+// sink's retention_hours 0 keeps files), a switch that defaults on stays off
+// when set off, a negative number is refused, and what moved from the
+// constructors keeps its meaning: min_disk_free_mb below zero is the default,
+// a backoff maximum below the minimum the default maximum
 func TestZeroDefaultsAndNegatives(t *testing.T) {
 	tcp, err := Decode[TCPSinkOptions]("sink", "tcp", map[string]any{"port": int64(1), "buffer_size": int64(0), "keep_alive": false})
 	if err != nil || tcp.BufferSize != 1000 || tcp.KeepAlive || tcp.Host != "0.0.0.0" {
@@ -55,6 +56,16 @@ func TestZeroDefaultsAndNegatives(t *testing.T) {
 			t.Errorf("min_disk_free_mb %v: %+v %v, want %d", in, file, err, want)
 		}
 	}
+	for in, want := range map[any]float64{nil: 168, int64(0): 0, 0.0: 0, 2.5: 2.5} {
+		m := map[string]any{"directory": "d", "name": "n", "retention_hours": in}
+		if in == nil {
+			delete(m, "retention_hours")
+		}
+		file, err := Decode[FileSinkOptions]("sink", "file", m)
+		if err != nil || file.RetentionHours != want {
+			t.Errorf("retention_hours %v: %+v %v, want %v", in, file, err, want)
+		}
+	}
 	chain, err := Decode[TCPChainSinkOptions]("sink", "tcp_chain", map[string]any{"host": "h", "port": int64(1), "backoff_min_ms": int64(800), "backoff_max_ms": int64(700)})
 	if err != nil || chain.BackoffMaxMS != 30000 {
 		t.Fatalf("backoff maximum below the minimum: %+v %v", chain, err)