feat: add config for whether to log sampling rate transitions for adaptive sampling rate

docs/drift/configuration.md

@@ -335,6 +335,12 @@ For authentication in cloud mode, either use:
       <td><code>0.001</code> in <code>adaptive</code> mode; unset in <code>fixed</code> mode</td>
       <td>Lower bound for adaptive sampling after load shedding is applied. This is only defaulted in <code>adaptive</code> mode and remains unset in <code>fixed</code> mode.</td>
     </tr>
+    <tr>
+      <td><code>recording.sampling.log_transitions</code></td>
+      <td>boolean</td>
+      <td><code>true</code></td>
+      <td>Whether the SDK should emit adaptive sampling transition logs. This is SDK-facing only and can be overridden by <code>TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS</code>.</td>
+    </tr>
     <tr>
       <td><code>recording.sampling_rate</code></td>
       <td>number</td>
@@ -471,6 +477,7 @@ Configuration for code coverage collection. See [`docs/drift/coverage.md`](cover
 - `TUSK_API_URL` → `tusk_api.url`
 - `TUSK_RESULTS_DIR` → `results.dir`
 - `TUSK_RECORDING_SAMPLING_RATE` → `recording.sampling_rate`
+- `TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS` → `recording.sampling.log_transitions`
 
 ## Minimal config examples
 

internal/config/config.go

@@ -90,9 +90,10 @@ type ComparisonConfig struct {
 }
 
 type RecordingSamplingConfig struct {
-	Mode     string   `koanf:"mode"`
-	BaseRate *float64 `koanf:"base_rate"`
-	MinRate  *float64 `koanf:"min_rate"`
+	Mode           string   `koanf:"mode"`
+	BaseRate       *float64 `koanf:"base_rate"`
+	MinRate        *float64 `koanf:"min_rate"`
+	LogTransitions *bool    `koanf:"log_transitions"`
 }
 
 type RecordingConfig struct {
@@ -159,12 +160,13 @@ func Load(configFile string) error {
 
 	// Support environment variable overrides for specific config keys
 	envOverrides := map[string]string{
-		"TUSK_TRACES_DIR":              "traces.dir",
-		"TUSK_API_URL":                 "tusk_api.url",
-		"TUSK_AUTH0_DOMAIN":            "tusk_api.auth0_domain",
-		"TUSK_AUTH0_CLIENT_ID":         "tusk_api.auth0_client_id",
-		"TUSK_RESULTS_DIR":             "results.dir",
-		"TUSK_RECORDING_SAMPLING_RATE": "recording.sampling_rate",
+		"TUSK_TRACES_DIR":                         "traces.dir",
+		"TUSK_API_URL":                            "tusk_api.url",
+		"TUSK_AUTH0_DOMAIN":                       "tusk_api.auth0_domain",
+		"TUSK_AUTH0_CLIENT_ID":                    "tusk_api.auth0_client_id",
+		"TUSK_RESULTS_DIR":                        "results.dir",
+		"TUSK_RECORDING_SAMPLING_RATE":            "recording.sampling_rate",
+		"TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS": "recording.sampling.log_transitions",
 	}
 
 	for envKey, configKey := range envOverrides {
@@ -245,6 +247,10 @@ func parseAndValidate() (*Config, error) {
 		minRate := 0.001
 		cfg.Recording.Sampling.MinRate = &minRate
 	}
+	if cfg.Recording.Sampling.LogTransitions == nil {
+		defaultLogTransitions := true
+		cfg.Recording.Sampling.LogTransitions = &defaultLogTransitions
+	}
 	if cfg.Recording.ExportSpans == nil {
 		defaultExportSpans := false
 		cfg.Recording.ExportSpans = &defaultExportSpans

internal/config/config_test.go

@@ -31,6 +31,7 @@ recording:
     mode: adaptive
     base_rate: 0.25
     min_rate: 0.05
+    log_transitions: false
 `), 0o600))
 
 	require.NoError(t, Load(configPath))
@@ -42,6 +43,8 @@ recording:
 	assert.Equal(t, 0.25, *cfg.Recording.Sampling.BaseRate)
 	require.NotNil(t, cfg.Recording.Sampling.MinRate)
 	assert.Equal(t, 0.05, *cfg.Recording.Sampling.MinRate)
+	require.NotNil(t, cfg.Recording.Sampling.LogTransitions)
+	assert.False(t, *cfg.Recording.Sampling.LogTransitions)
 	assert.Equal(t, 0.25, cfg.Recording.SamplingRate)
 }
 
@@ -69,6 +72,7 @@ recording:
 func TestRecordingSamplingRateEnvOverrideBeatsNestedBaseRate(t *testing.T) {
 	defer Invalidate()
 	t.Setenv("TUSK_RECORDING_SAMPLING_RATE", "0.5")
+	t.Setenv("TUSK_RECORDING_SAMPLING_LOG_TRANSITIONS", "false")
 
 	tmpDir := t.TempDir()
 	configPath := filepath.Join(tmpDir, "config.yaml")
@@ -78,6 +82,7 @@ recording:
     mode: adaptive
     base_rate: 0.25
     min_rate: 0.05
+    log_transitions: true
 `), 0o600))
 
 	require.NoError(t, Load(configPath))
@@ -90,6 +95,8 @@ recording:
 	assert.Equal(t, "adaptive", cfg.Recording.Sampling.Mode)
 	require.NotNil(t, cfg.Recording.Sampling.MinRate)
 	assert.Equal(t, 0.05, *cfg.Recording.Sampling.MinRate)
+	require.NotNil(t, cfg.Recording.Sampling.LogTransitions)
+	assert.False(t, *cfg.Recording.Sampling.LogTransitions)
 }
 
 func TestValidateRejectsInvalidRecordingSamplingMode(t *testing.T) {