mark disable_compat_1.9 to deprecate in 1.13, change default to true (#12675)

Co-authored-by: R.B. Boyer <4903+rboyer@users.noreply.github.com>

.changelog/12675.txt

@@ -0,0 +1,3 @@
+```release-note:breaking-change
+telemetry: the disable_compat_1.9 option now defaults to true. 1.9 style `consul.http...` metrics can still be enabled by setting `disable_compat_1.9 = false`. However, we will remove these metrics in 1.13.
+```

agent/agent.go

@@ -698,7 +698,7 @@ func (a *Agent) Start(ctx context.Context) error {
 	// DEPRECATED: Warn users if they're emitting deprecated metrics. Remove this warning and the flagged metrics in a
 	// future release of Consul.
 	if !a.config.Telemetry.DisableCompatOneNine {
-		a.logger.Warn("DEPRECATED Backwards compatibility with pre-1.9 metrics enabled. These metrics will be removed in a future version of Consul. Set `telemetry { disable_compat_1.9 = true }` to disable them.")
+		a.logger.Warn("DEPRECATED Backwards compatibility with pre-1.9 metrics enabled. These metrics will be removed in Consul 1.13. Consider not using this flag and rework instrumentation for 1.10 style http metrics.")
 	}
 
 	if a.tlsConfigurator.Cert() != nil {
@@ -3797,7 +3797,7 @@ func (a *Agent) reloadConfig(autoReload bool) error {
 	// DEPRECATED: Warn users on reload if they're emitting deprecated metrics. Remove this warning and the flagged
 	// metrics in a future release of Consul.
 	if !a.config.Telemetry.DisableCompatOneNine {
-		a.logger.Warn("DEPRECATED Backwards compatibility with pre-1.9 metrics enabled. These metrics will be removed in a future version of Consul. Set `telemetry { disable_compat_1.9 = true }` to disable them.")
+		a.logger.Warn("DEPRECATED Backwards compatibility with pre-1.9 metrics enabled. These metrics will be removed in Consul 1.13. Consider not using this flag and rework instrumentation for 1.10 style http metrics.")
 	}
 
 	return a.reloadConfigInternal(newCfg)

agent/config/builder.go

@@ -910,7 +910,7 @@ func (b *builder) build() (rt RuntimeConfig, err error) {
 			CirconusCheckTags:                  stringVal(c.Telemetry.CirconusCheckTags),
 			CirconusSubmissionInterval:         stringVal(c.Telemetry.CirconusSubmissionInterval),
 			CirconusSubmissionURL:              stringVal(c.Telemetry.CirconusSubmissionURL),
-			DisableCompatOneNine:               boolVal(c.Telemetry.DisableCompatOneNine),
+			DisableCompatOneNine:               boolValWithDefault(c.Telemetry.DisableCompatOneNine, true),
 			DisableHostname:                    boolVal(c.Telemetry.DisableHostname),
 			DogstatsdAddr:                      stringVal(c.Telemetry.DogstatsdAddr),
 			DogstatsdTags:                      c.Telemetry.DogstatsdTags,

agent/http.go

@@ -228,8 +228,7 @@ func (s *HTTPHandlers) handler(enableDebug bool) http.Handler {
 			labels := []metrics.Label{{Name: "method", Value: req.Method}, {Name: "path", Value: path_label}}
 			metrics.MeasureSinceWithLabels([]string{"api", "http"}, start, labels)
 
-			// DEPRECATED Emit pre-1.9 metric as `consul.http...` to maintain backwards compatibility. Enabled by
-			// default. Users may set `telemetry { disable_compat_1.9 = true }`
+			// DEPRECATED Emit pre-1.9 metric as `consul.http...`. This will be removed in 1.13.
 			if !s.agent.config.Telemetry.DisableCompatOneNine {
 				key := append([]string{"http", req.Method}, parts...)
 				metrics.MeasureSince(key, start)

agent/metrics_test.go

@@ -255,6 +255,67 @@ func TestHTTPHandlers_AgentMetrics_ConsulAutopilot_Prometheus(t *testing.T) {
 	})
 }
 
+// TestHTTPHandlers_AgentMetrics_Disable1Dot9MetricsChange adds testing around the 1.9 style metrics
+// https://www.consul.io/docs/agent/options#telemetry-disable_compat_1.9
+func TestHTTPHandlers_AgentMetrics_Disable1Dot9MetricsChange(t *testing.T) {
+	skipIfShortTesting(t)
+	// This test cannot use t.Parallel() since we modify global state, ie the global metrics instance
+
+	// 1.9 style http metrics looked like this:
+	// agent_http_2_http_GET_v1_agent_members{quantile="0.5"} 0.1329520046710968
+	t.Run("check that no consul.http metrics are emitted by default", func(t *testing.T) {
+		hcl := `
+		telemetry = {
+			prometheus_retention_time = "5s"
+			disable_hostname = true
+			metrics_prefix = "agent_http"
+		}
+	`
+
+		a := StartTestAgent(t, TestAgent{HCL: hcl})
+		defer a.Shutdown()
+
+		// we have to use the `a.srv.handler()` to actually trigger the wrapped function
+		uri := fmt.Sprintf("http://%s%s", a.HTTPAddr(), "/v1/agent/members")
+		req, err := http.NewRequest("GET", uri, nil)
+		require.NoError(t, err)
+		resp := httptest.NewRecorder()
+		handler := a.srv.handler(true)
+		handler.ServeHTTP(resp, req)
+
+		respRec := httptest.NewRecorder()
+		recordPromMetrics(t, a, respRec)
+
+		assertMetricNotExists(t, respRec, "agent_http_http_GET_v1_agent_members")
+	})
+
+	t.Run("check that we can still turn on consul.http metrics", func(t *testing.T) {
+		hcl := `
+		telemetry = {
+			prometheus_retention_time = "5s",
+			disable_compat_1.9 = false
+			metrics_prefix = "agent_http_2"
+		}
+		`
+
+		a := StartTestAgent(t, TestAgent{HCL: hcl})
+		defer a.Shutdown()
+
+		uri := fmt.Sprintf("http://%s%s", a.HTTPAddr(), "/v1/agent/members")
+		req, err := http.NewRequest("GET", uri, nil)
+		require.NoError(t, err)
+		resp := httptest.NewRecorder()
+
+		handler := a.srv.handler(true)
+		handler.ServeHTTP(resp, req)
+
+		respRec := httptest.NewRecorder()
+		recordPromMetrics(t, a, respRec)
+
+		assertMetricExists(t, respRec, "agent_http_2_http_GET_v1_agent_members")
+	})
+}
+
 func TestHTTPHandlers_AgentMetrics_TLSCertExpiry_Prometheus(t *testing.T) {
 	skipIfShortTesting(t)
 	// This test cannot use t.Parallel() since we modify global state, ie the global metrics instance

website/content/docs/agent/options.mdx

@@ -2175,7 +2175,7 @@ There are also a number of common configuration options supported by all provide
     geo location or datacenter, dc:sfo). By default, this is left blank and not used.
 
   - `disable_compat_1.9` ((#telemetry-disable_compat_1.9))
-    This allows users to disable metrics deprecated in 1.9 so they are no longer emitted, saving on performance and storage in large deployments. Defaults to false.
+    This allows users to disable metrics deprecated in 1.9 so they are no longer emitted, improving performance and reducing storage in large deployments. As of 1.12 this defaults to `true` and will be removed, along with 1.9 style http metrics in 1.13.
 
   - `disable_hostname` ((#telemetry-disable_hostname))
     This controls whether or not to prepend runtime telemetry with the machine's

website/content/docs/upgrading/upgrade-specific.mdx

@@ -14,6 +14,18 @@ provided for their upgrades as a result of new features or changed behavior.
 This page is used to document those details separately from the standard
 upgrade flow.
 
+## Consul 1.12.0
+
+### 1.9 Telemetry Compatibility
+
+#### Changing the default behavior for option
+
+The [`disable_compat_19`](/docs/agent/options#telemetry-disable_compat_1.9) telemetry configuration option now defaults
+to `true`. In prior Consul versions (1.10.x through 1.11.x), the config defaulted to `false`. If you require 1.9 style
+`consul.http...` metrics, you may enable them by setting the flag to `false`. However, be advised that these metrics, as
+well as the flag will be removed in upcoming Consul 1.13. We recommend changing your instrumentation to use 1.10 and later
+style `consul.api.http...` metrics and removing the configuration flag from your setup.
+
 ## Consul 1.11.0
 
 ### 1.10 Compatibility <EnterpriseAlert inline />