Add global config option for convert_classic_histograms_to_nhcb

Addresses the global part of https://github.com/prometheus/prometheus/issues/13532 Signed-off-by: chardch <otwordsne@gmail.com>
2025-08-07 06:37:17 +02:00 · 2025-03-17 15:57:14 -07:00 · 2025-03-17 15:57:14 -07:00 · 2f59d38054
commit 2f59d38054
parent 7d73c1d3f8
9 changed files with 582 additions and 479 deletions
--- a/config/config.go
+++ b/config/config.go
@ -168,6 +168,7 @@ var (
 		// When native histogram feature flag is enabled, ScrapeProtocols default
 		// changes to DefaultNativeHistogramScrapeProtocols.
 		ScrapeProtocols:                DefaultScrapeProtocols,
+		ConvertClassicHistogramsToNHCB: false,
 	}

 	DefaultRuntimeConfig = RuntimeConfig{
@ -486,6 +487,8 @@ type GlobalConfig struct {
 	// blank in config files but must have a value if a ScrepeConfig is created
 	// programmatically.
 	MetricNameEscapingScheme string `yaml:"metric_name_escaping_scheme,omitempty"`
+	// Whether to convert all scraped classic histograms into native histograms with custom buckets.
+	ConvertClassicHistogramsToNHCB bool `yaml:"convert_classic_histograms_to_nhcb,omitempty"`
 }

 // ScrapeProtocol represents supported protocol for scraping metrics.
@ -641,7 +644,8 @@ func (c *GlobalConfig) isZero() bool {
 		c.RuleQueryOffset == 0 &&
 		c.QueryLogFile == "" &&
 		c.ScrapeFailureLogFile == "" &&
-		c.ScrapeProtocols == nil
+		c.ScrapeProtocols == nil &&
+		!c.ConvertClassicHistogramsToNHCB
 }

 // RuntimeConfig configures the values for the process behavior.
@ -688,7 +692,7 @@ type ScrapeConfig struct {
 	// Whether to scrape a classic histogram, even if it is also exposed as a native histogram.
 	AlwaysScrapeClassicHistograms bool `yaml:"always_scrape_classic_histograms,omitempty"`
 	// Whether to convert all scraped classic histograms into a native histogram with custom buckets.
-	ConvertClassicHistogramsToNHCB bool `yaml:"convert_classic_histograms_to_nhcb,omitempty"`
+	ConvertClassicHistogramsToNHCB *bool `yaml:"convert_classic_histograms_to_nhcb,omitempty"`
 	// File to which scrape failures are logged.
 	ScrapeFailureLogFile string `yaml:"scrape_failure_log_file,omitempty"`
 	// The HTTP resource path on which to fetch metrics from targets.
@ -895,6 +899,11 @@ func (c *ScrapeConfig) Validate(globalConfig GlobalConfig) error {
 		return fmt.Errorf("unknown scrape config name escaping method specified, must be one of '%s', '%s', '%s', or '%s', got %s", model.AllowUTF8, model.EscapeUnderscores, model.EscapeDots, model.EscapeValues, c.MetricNameValidationScheme)
 	}

+	if c.ConvertClassicHistogramsToNHCB == nil {
+		globalVal := &globalConfig.ConvertClassicHistogramsToNHCB
+		c.ConvertClassicHistogramsToNHCB = globalVal
+	}
+
 	return nil
 }

@ -917,6 +926,11 @@ func ToValidationScheme(s string) (validationScheme model.ValidationScheme, err
 	return validationScheme, nil
 }

+// ConvertClassicHistogramsToNHCBEnabled returns whether to convert classic histograms to NHCB
+func (c *ScrapeConfig) ConvertClassicHistogramsToNHCBEnabled() bool {
+	return c.ConvertClassicHistogramsToNHCB != nil && *c.ConvertClassicHistogramsToNHCB
+}
+
 // StorageConfig configures runtime reloadable configuration options.
 type StorageConfig struct {
 	TSDBConfig      *TSDBConfig      `yaml:"tsdb,omitempty"`
--- a/config/config_test.go
+++ b/config/config_test.go
@ -69,6 +69,10 @@ func mustParseURL(u string) *config.URL {
 	return &config.URL{URL: parsed}
 }

+func boolPtr(b bool) *bool {
+	return &b
+}
+
 const (
 	globBodySizeLimit         = 15 * units.MiB
 	globSampleLimit           = 1500
@ -98,6 +102,7 @@ var expectedConf = &Config{
 		LabelNameLengthLimit:           globLabelNameLengthLimit,
 		LabelValueLengthLimit:          globLabelValueLengthLimit,
 		ScrapeProtocols:                DefaultGlobalConfig.ScrapeProtocols,
+		ConvertClassicHistogramsToNHCB: false,
 	},

 	Runtime: RuntimeConfig{
@ -218,6 +223,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           "testdata/fail_prom.log",
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath: DefaultScrapeConfig.MetricsPath,
 			Scheme:      DefaultScrapeConfig.Scheme,
@ -333,6 +339,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			HTTPClientConfig: config.HTTPClientConfig{
 				BasicAuth: &config.BasicAuth{
@ -433,6 +440,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -491,6 +499,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath: "/metrics",
 			Scheme:      "http",
@ -527,6 +536,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -569,6 +579,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath: DefaultScrapeConfig.MetricsPath,
 			Scheme:      DefaultScrapeConfig.Scheme,
@ -611,6 +622,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -643,6 +655,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -683,6 +696,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -720,6 +734,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -764,6 +779,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -798,6 +814,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -835,6 +852,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -865,6 +883,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -898,6 +917,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      "/federate",
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -931,6 +951,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -964,6 +985,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -994,6 +1016,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1032,6 +1055,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1069,6 +1093,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1103,6 +1128,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1136,6 +1162,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1173,6 +1200,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1213,6 +1241,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1272,6 +1301,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1302,6 +1332,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			HTTPClientConfig: config.DefaultHTTPClientConfig,
 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
@ -1343,6 +1374,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			HTTPClientConfig: config.DefaultHTTPClientConfig,
 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
@ -1390,6 +1422,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1428,6 +1461,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			HTTPClientConfig: config.DefaultHTTPClientConfig,
 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
@ -1446,6 +1480,7 @@ var expectedConf = &Config{
 		},
 		{
 			JobName: "ionos",
+
 			HonorTimestamps:                true,
 			ScrapeInterval:                 model.Duration(15 * time.Second),
 			ScrapeTimeout:                  DefaultGlobalConfig.ScrapeTimeout,
@ -1460,6 +1495,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -1495,6 +1531,7 @@ var expectedConf = &Config{
 			ScrapeFailureLogFile:           globScrapeFailureLogFile,
 			MetricNameValidationScheme:     UTF8ValidationConfig,
 			MetricNameEscapingScheme:       model.AllowUTF8,
+			ConvertClassicHistogramsToNHCB: boolPtr(false),

 			MetricsPath:      DefaultScrapeConfig.MetricsPath,
 			Scheme:           DefaultScrapeConfig.Scheme,
@ -2317,7 +2354,7 @@ func TestEmptyGlobalBlock(t *testing.T) {
 }

 func TestGetScrapeConfigs(t *testing.T) {
-	sc := func(jobName string, scrapeInterval, scrapeTimeout model.Duration) *ScrapeConfig {
+	sc := func(jobName string, scrapeInterval, scrapeTimeout model.Duration, convertClassicHistToNHCB bool) *ScrapeConfig {
 		return &ScrapeConfig{
 			JobName:                    jobName,
 			HonorTimestamps:            true,
@ -2343,6 +2380,7 @@ func TestGetScrapeConfigs(t *testing.T) {
 					},
 				},
 			},
+			ConvertClassicHistogramsToNHCB: boolPtr(convertClassicHistToNHCB),
 		}
 	}

@ -2355,20 +2393,20 @@ func TestGetScrapeConfigs(t *testing.T) {
 		{
 			name:           "An included config file should be a valid global config.",
 			configFile:     "testdata/scrape_config_files.good.yml",
-			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second))},
+			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second), false)},
 		},
 		{
 			name:           "A global config that only include a scrape config file.",
 			configFile:     "testdata/scrape_config_files_only.good.yml",
-			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second))},
+			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second), false)},
 		},
 		{
 			name:       "A global config that combine scrape config files and scrape configs.",
 			configFile: "testdata/scrape_config_files_combined.good.yml",
 			expectedResult: []*ScrapeConfig{
-				sc("node", model.Duration(60*time.Second), model.Duration(10*time.Second)),
-				sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second)),
-				sc("alertmanager", model.Duration(60*time.Second), model.Duration(10*time.Second)),
+				sc("node", model.Duration(60*time.Second), model.Duration(10*time.Second), false),
+				sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second), false),
+				sc("alertmanager", model.Duration(60*time.Second), model.Duration(10*time.Second), false),
 			},
 		},
 		{
@ -2384,6 +2422,7 @@ func TestGetScrapeConfigs(t *testing.T) {
 					ScrapeProtocols:                DefaultGlobalConfig.ScrapeProtocols,
 					MetricNameValidationScheme:     UTF8ValidationConfig,
 					MetricNameEscapingScheme:       model.AllowUTF8,
+					ConvertClassicHistogramsToNHCB: boolPtr(false),

 					MetricsPath: DefaultScrapeConfig.MetricsPath,
 					Scheme:      DefaultScrapeConfig.Scheme,
@ -2419,6 +2458,7 @@ func TestGetScrapeConfigs(t *testing.T) {
 					ScrapeProtocols:                DefaultGlobalConfig.ScrapeProtocols,
 					MetricNameValidationScheme:     UTF8ValidationConfig,
 					MetricNameEscapingScheme:       model.AllowUTF8,
+					ConvertClassicHistogramsToNHCB: boolPtr(false),

 					HTTPClientConfig: config.HTTPClientConfig{
 						TLSConfig: config.TLSConfig{
@ -2466,6 +2506,21 @@ func TestGetScrapeConfigs(t *testing.T) {
 			configFile:    "testdata/scrape_config_files_global.bad.yml",
 			expectedError: `scrape timeout greater than scrape interval for scrape config with job name "prometheus"`,
 		},
+		{
+			name:           "A global config that enables convert classic histograms to nhcb.",
+			configFile:     "testdata/global_convert_classic_hist_to_nhcb.good.yml",
+			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second), true)},
+		},
+		{
+			name:           "A global config that enables convert classic histograms to nhcb and scrape config that disables the conversion",
+			configFile:     "testdata/local_disable_convert_classic_hist_to_nhcb.good.yml",
+			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second), false)},
+		},
+		{
+			name:           "A global config that disables convert classic histograms to nhcb and scrape config that enables the conversion",
+			configFile:     "testdata/local_convert_classic_hist_to_nhcb.good.yml",
+			expectedResult: []*ScrapeConfig{sc("prometheus", model.Duration(60*time.Second), model.Duration(10*time.Second), true)},
+		},
 	}

 	for _, tc := range testCases {
--- a/config/testdata/global_convert_classic_hist_to_nhcb.good.yml
+++ b/config/testdata/global_convert_classic_hist_to_nhcb.good.yml
@ -0,0 +1,6 @@
+global:
+  convert_classic_histograms_to_nhcb: true
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ['localhost:8080']
--- a/config/testdata/local_convert_classic_hist_to_nhcb.good.yml
+++ b/config/testdata/local_convert_classic_hist_to_nhcb.good.yml
@ -0,0 +1,7 @@
+global:
+  convert_classic_histograms_to_nhcb: false
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ['localhost:8080']
+    convert_classic_histograms_to_nhcb: true
--- a/config/testdata/local_disable_convert_classic_hist_to_nhcb.good.yml
+++ b/config/testdata/local_disable_convert_classic_hist_to_nhcb.good.yml
@ -0,0 +1,7 @@
+global:
+  convert_classic_histograms_to_nhcb: true
+scrape_configs:
+  - job_name: prometheus
+    static_configs:
+      - targets: ['localhost:8080']
+    convert_classic_histograms_to_nhcb: false
--- a/docs/configuration/configuration.md
+++ b/docs/configuration/configuration.md
@ -140,6 +140,10 @@ global:
  # and underscores.
  [ metric_name_validation_scheme <string> | default "utf8" ]

+  # Specifies whether to convert all scraped classic histograms into native
+  # histograms with custom buckets.
+  [ convert_classic_histograms_to_nhcb <bool> | default = false]
+
 runtime:
  # Configure the Go garbage collector GOGC parameter
  # See: https://tip.golang.org/doc/gc-guide#GOGC
@ -531,6 +535,11 @@ metric_relabel_configs:
 # 0 results in the smallest supported factor (which is currently ~1.0027 or
 # schema 8, but might change in the future).
 [ native_histogram_min_bucket_factor: <float> | default = 0 ]
+
+# Specifies whether to convert scraped classic histograms from this into
+# native histogram with custom buckets.
+[ convert_classic_histograms_to_nhcb <bool> | default = false 
+or global.convert_classic_histograms_to_nhcb if unset]
 ```

 Where `<job_name>` must be unique across all scrape configurations.
--- a/scrape/manager.go
+++ b/scrape/manager.go
@ -176,7 +176,7 @@ func (m *Manager) reload() {
 				m.logger.Error("error reloading target set", "err", "invalid config id:"+setName)
 				continue
 			}
-			if scrapeConfig.ConvertClassicHistogramsToNHCB && m.opts.EnableCreatedTimestampZeroIngestion {
+			if scrapeConfig.ConvertClassicHistogramsToNHCBEnabled() && m.opts.EnableCreatedTimestampZeroIngestion {
 				// TODO(krajorama): fix https://github.com/prometheus/prometheus/issues/15137
 				m.logger.Error("error reloading target set", "err", "cannot convert classic histograms to native histograms with custom buckets and ingest created timestamp zero samples at the same time due to https://github.com/prometheus/prometheus/issues/15137")
 				continue
--- a/scrape/scrape.go
+++ b/scrape/scrape.go
@ -367,7 +367,7 @@ func (sp *scrapePool) restartLoops(reuseCache bool) {
 		mrc                      = sp.config.MetricRelabelConfigs
 		fallbackScrapeProtocol   = sp.config.ScrapeFallbackProtocol.HeaderMediaType()
 		alwaysScrapeClassicHist  = sp.config.AlwaysScrapeClassicHistograms
-		convertClassicHistToNHCB = sp.config.ConvertClassicHistogramsToNHCB
+		convertClassicHistToNHCB = sp.config.ConvertClassicHistogramsToNHCBEnabled()
 	)

 	sp.targetMtx.Lock()
@ -523,7 +523,7 @@ func (sp *scrapePool) sync(targets []*Target) {
 		mrc                      = sp.config.MetricRelabelConfigs
 		fallbackScrapeProtocol   = sp.config.ScrapeFallbackProtocol.HeaderMediaType()
 		alwaysScrapeClassicHist  = sp.config.AlwaysScrapeClassicHistograms
-		convertClassicHistToNHCB = sp.config.ConvertClassicHistogramsToNHCB
+		convertClassicHistToNHCB = sp.config.ConvertClassicHistogramsToNHCB != nil && *sp.config.ConvertClassicHistogramsToNHCB
 	)

 	sp.targetMtx.Lock()
--- a/scrape/scrape_test.go
+++ b/scrape/scrape_test.go
@ -4631,26 +4631,31 @@ metric: <
 		require.Equal(t, expectedCount, count, "number of histogram series not as expected")
 	}

+	tru := true
+	fals := false
 	for metricsTextName, metricsText := range metricsTexts {
 		for name, tc := range map[string]struct {
 			alwaysScrapeClassicHistograms bool
-			convertClassicHistToNHCB      bool
+			convertClassicHistToNHCB      *bool
 		}{
 			"convert with scrape": {
 				alwaysScrapeClassicHistograms: true,
-				convertClassicHistToNHCB:      true,
+				convertClassicHistToNHCB:      &tru,
 			},
 			"convert without scrape": {
 				alwaysScrapeClassicHistograms: false,
-				convertClassicHistToNHCB:      true,
+				convertClassicHistToNHCB:      &tru,
 			},
 			"scrape without convert": {
 				alwaysScrapeClassicHistograms: true,
-				convertClassicHistToNHCB:      false,
+				convertClassicHistToNHCB:      &fals,
+			},
+			"scrape with nil convert": {
+				alwaysScrapeClassicHistograms: true,
 			},
 			"neither scrape nor convert": {
 				alwaysScrapeClassicHistograms: false,
-				convertClassicHistToNHCB:      false,
+				convertClassicHistToNHCB:      &fals,
 			},
 		} {
 			var expectedClassicHistCount, expectedNativeHistCount int
@ -4664,17 +4669,17 @@ metric: <
 				}
 			} else if metricsText.hasClassic {
 				switch {
-				case tc.alwaysScrapeClassicHistograms && tc.convertClassicHistToNHCB:
+				case tc.convertClassicHistToNHCB == nil || !*tc.convertClassicHistToNHCB:
+					expectedClassicHistCount = 1
+					expectedNativeHistCount = 0
+				case tc.alwaysScrapeClassicHistograms && *tc.convertClassicHistToNHCB:
 					expectedClassicHistCount = 1
 					expectedNativeHistCount = 1
 					expectCustomBuckets = true
-				case !tc.alwaysScrapeClassicHistograms && tc.convertClassicHistToNHCB:
+				case !tc.alwaysScrapeClassicHistograms && *tc.convertClassicHistToNHCB:
 					expectedClassicHistCount = 0
 					expectedNativeHistCount = 1
 					expectCustomBuckets = true
-				case !tc.convertClassicHistToNHCB:
-					expectedClassicHistCount = 1
-					expectedNativeHistCount = 0
 				}
 			}