[receiver/mysql] Tune query plan obfuscation (#46760)

This PR addresses over-obfuscation of MySQL query plans and simplifies
the logic for determining whether a query should be EXPLAINed.
                                                            
**Fix over-obfuscation of query plans** — The query plan obfuscator was
previously redacting structural plan metadata (access types, key names,
table names, etc.) that is needed for query plan analysis. The
obfuscation settings have been tuned to target only sensitive
values (query text fragments, cost estimates, row estimates, condition
expressions) while preserving the structural fields that describe the
execution strategy. Support has been added for both MySQL EXPLAIN
FORMAT=JSON v1 and v2 output formats.

**Simplify explainability detection** — The decision of whether to
EXPLAIN a query is now based on the `digestText` (the normalized query
template) rather than the raw sample statement, and truncation detection
uses a `HasSuffix("...")` check on the sample statement
instead of a byte-length comparison against `@@max_digest_length`. This
removes a dependency on querying the DB at connection time.

  #### Link to tracking issue
Fixes
#46629

  #### Testing

- Added `TestIsQueryExplainable` covering all supported DML keywords,
unsupported statements, case-insensitivity, leading whitespace, and edge
cases.
- Added `TestBuildExplainStatement` covering plain queries, whitespace
trimming, and statements with comments.
- Updated `TestScrape` expected output to reflect revised obfuscation
settings.
- Obfuscation behavior validated against both v1 and v2 MySQL EXPLAIN
FORMAT=JSON output via test fixtures.

  #### Documentation

No documentation changes — this fixes existing behavior rather than
introducing new configuration options.

Author: cjksplunk

.chloggen/46629-MySQL-obfuscate-query_plan.yaml

@@ -0,0 +1,28 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type:
+  enhancement
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component:
+  receiver/mysql
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note:
+  Add and tune obfuscation of sensitive properties in both V1 and V2 JSON query plans.
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [46629,46587]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Configure and test obfuscation for V1 and V2 plans, including tests of queries retrieved from the performance schema that are truncated and cannot be obfuscated.
+  The importance of obfuscation can be very context dependent; sensitive PII, banking, and authorization data may reside in the same database as less sensitive data, and it can be vital to ensure that what is expected to be obfuscated is always obfuscated. Significant additional testing has been added around query plan obfuscation to ensure that this is enforced and to provide assurance and reference to users about what specifically is obfuscated and what is not.
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/mysqlreceiver/client.go

@@ -32,7 +32,7 @@ type client interface {
 	getReplicaStatusStats() ([]replicaStatusStats, error)
 	getQuerySamples(uint64) ([]querySample, error)
 	getTopQueries(uint64, uint64) ([]topQuery, error)
-	explainQuery(statement, schema string, logger *zap.Logger) string
+	explainQuery(digestText, sampleStatement, schema, digest string, logger *zap.Logger) string
 	Close() error
 }
 
@@ -791,30 +791,32 @@ func (c *mySQLClient) getQuerySamples(limit uint64) ([]querySample, error) {
 	return samples, nil
 }
 
-func (c *mySQLClient) explainQuery(statement, schema string, logger *zap.Logger) string {
-	if strings.HasSuffix(statement, "...") {
-		logger.Warn("statement is truncated, skipping explain", zap.String("statement", statement))
+func (c *mySQLClient) explainQuery(digestText, sampleStatement, schema, digest string, logger *zap.Logger) string {
+	if strings.HasSuffix(sampleStatement, "...") {
+		logger.Debug("statement is truncated, skipping explain", zap.String("digest_text", digestText))
 		return ""
 	}
-
-	if !isQueryExplainable(statement) {
-		logger.Debug("statement is not explainable, skipping explain query", zap.String("statement", statement))
+	if !isQueryExplainable(digestText) {
+		logger.Debug("statement is not explainable, skipping explain query", zap.String("digest", digest))
 		return ""
 	}
 
 	if schema != "" {
-		if _, err := c.client.Exec(fmt.Sprintf("/* otel-collector-ignore */ USE %s;", schema)); err != nil {
-			logger.Error(fmt.Sprintf("unable to use schema: %s", schema), zap.Error(err))
+		if _, err := c.client.Exec(fmt.Sprintf("/* otel-collector-ignore */ USE `%s`;", strings.ReplaceAll(schema, "`", "``"))); err != nil {
+			logger.Warn(fmt.Sprintf("unable to use schema: %s", schema), zap.String("digest", digest), zap.Error(err))
 			return ""
 		}
 	}
 
 	var plan string
-	err := c.client.QueryRow(fmt.Sprintf("EXPLAIN FORMAT=json %s", statement)).Scan(&plan)
+	err := c.client.QueryRow("EXPLAIN FORMAT=json " + strings.TrimSpace(sampleStatement)).Scan(&plan)
 	if err != nil {
-		logger.Error("unable to execute explain statement", zap.Error(err))
+		logger.Warn("unable to execute explain statement", zap.String("digest", digest), zap.Error(err))
 		return ""
 	}
+	if plan == "" {
+		logger.Warn("explain query returned empty plan", zap.String("digest", digest))
+	}
 	return plan
 }
 

receiver/mysqlreceiver/client_test.go

@@ -0,0 +1,119 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package mysqlreceiver
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"go.uber.org/zap"
+)
+
+func TestIsQueryExplainable(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected bool
+	}{
+		// Supported keywords — plain queries
+		{
+			name:     "select is explainable",
+			input:    "SELECT * FROM t",
+			expected: true,
+		},
+		{
+			name:     "delete is explainable",
+			input:    "DELETE FROM t WHERE id = 1",
+			expected: true,
+		},
+		{
+			name:     "insert is explainable",
+			input:    "INSERT INTO t VALUES (1)",
+			expected: true,
+		},
+		{
+			name:     "replace is explainable",
+			input:    "REPLACE INTO t VALUES (1)",
+			expected: true,
+		},
+		{
+			name:     "update is explainable",
+			input:    "UPDATE t SET col = 1",
+			expected: true,
+		},
+		// Case-insensitive matching
+		{
+			name:     "mixed-case SELECT is explainable",
+			input:    "Select * FROM t",
+			expected: true,
+		},
+		// Leading whitespace
+		{
+			name:     "leading whitespace before SELECT is explainable",
+			input:    "   SELECT * FROM t",
+			expected: true,
+		},
+		// Unsupported statements
+		{
+			name:     "show is not explainable",
+			input:    "SHOW TABLES",
+			expected: false,
+		},
+		{
+			name:     "create is not explainable",
+			input:    "CREATE TABLE t (id INT)",
+			expected: false,
+		},
+		{
+			name:     "drop is not explainable",
+			input:    "DROP TABLE t",
+			expected: false,
+		},
+		{
+			name:     "empty string is not explainable",
+			input:    "",
+			expected: false,
+		},
+		// Truncated statements (handled upstream, but isQueryExplainable itself
+		// should not crash; the trailing "..." doesn’t match any keyword)
+		{
+			name:     "truncated statement that starts with SELECT is still type-explainable",
+			input:    "SELECT * FROM very_long_table_na...",
+			expected: true, // still starts with SELECT
+		},
+		// Any leading block comment makes the query not explainable; digest_text
+		// from performance_schema does not include them, so this won't arise in practice.
+		{
+			name:     "leading block comment before SELECT is not explainable",
+			input:    "/* a comment */ SELECT * FROM t",
+			expected: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.expected, isQueryExplainable(tt.input))
+		})
+	}
+}
+
+// TestExplainQueryEarlyExits verifies that explainQuery returns "" without
+// hitting the database when the sample statement is truncated or the digest
+// text is not an explainable statement type.
+func TestExplainQueryEarlyExits(t *testing.T) {
+	// mySQLClient with a nil DB — safe because both early-exit paths return
+	// before any database call is made.
+	c := &mySQLClient{}
+	logger := zap.NewNop()
+
+	t.Run("truncated sample statement returns empty", func(t *testing.T) {
+		result := c.explainQuery("SELECT * FROM t", "SELECT * FROM very_long_table_na...", "", "digest1", logger)
+		assert.Empty(t, result)
+	})
+
+	t.Run("non-explainable digest text returns empty", func(t *testing.T) {
+		result := c.explainQuery("SHOW TABLES", "SHOW TABLES", "", "digest2", logger)
+		assert.Empty(t, result)
+	})
+}

receiver/mysqlreceiver/metadata.yaml

@@ -827,6 +827,8 @@ metrics:
 
 tests:
   config:
+    tls:
+      insecure: true
   goleak:
     ignore:
       any:

receiver/mysqlreceiver/obfuscate.go

@@ -10,8 +10,7 @@ import (
 var (
 	obfuscateSQLConfig = obfuscate.SQLConfig{DBMS: "mysql"}
 	obfuscatorConfig   = obfuscate.Config{
-		SQLExecPlan:          defaultSQLPlanObfuscateSettings,
-		SQLExecPlanNormalize: defaultSQLPlanNormalizeSettings,
+		SQLExecPlan: defaultSQLPlanObfuscateSettings,
 	}
 )
 
@@ -30,57 +29,57 @@ func (o *obfuscator) obfuscateSQLString(sql string) (string, error) {
 }
 
 func (o *obfuscator) obfuscatePlan(plan string) (string, error) {
-	obfuscated, err := (*obfuscate.Obfuscator)(o).ObfuscateSQLExecPlan(plan, true)
+	obfuscated, err := (*obfuscate.Obfuscator)(o).ObfuscateSQLExecPlan(plan, false)
 	if err != nil {
 		return "", err
 	}
 	return obfuscated, nil
 }
 
-// defaultSQLPlanNormalizeSettings are the default JSON obfuscator settings for both obfuscating and normalizing SQL
-// execution plans
-var defaultSQLPlanNormalizeSettings = obfuscate.JSONConfig{
+// For further information, see https://dev.mysql.com/doc/refman/8.4/en/explain.html
+// MySQL 8.4 EXPLAIN FORMAT=JSON produces two formats depending on explain_json_format_version:
+//   - Version 1 (default): query_block → ordering_operation → table → attached_condition
+//   - Version 2: top-level query + inputs array, each node has condition/operation/access_type etc.
+var defaultSQLPlanObfuscateSettings = obfuscate.JSONConfig{
 	Enabled: true,
 	ObfuscateSQLValues: []string{
-		// mysql
+		// v2: the full query text
+		"query",
+		// v2: SQL condition expression on a filter node
+		"condition",
+		// v2: human-readable description of a plan node (e.g. "Filter: (...)", "Table scan on ...")
+		"operation",
+		// v1: SQL condition expression attached to a table scan
 		"attached_condition",
 	},
 	KeepValues: []string{
-		// mysql
-		"access_type",
-		"backward_index_scan",
-		"cacheable",
-		"delete",
-		"dependent",
-		"first_match",
-		"key",
-		"key_length",
-		"possible_keys",
-		"ref",
+		// v1 structural fields
+		"cost_info",
+		"ordering_operation",
+		"query_block",
+		"query_plan",
+		"query_type",
 		"select_id",
-		"table_name",
-		"update",
+		"table",
 		"used_columns",
-		"used_key_parts",
-		"using_MRR",
 		"using_filesort",
-		"using_index",
-		"using_join_buffer",
-		"using_temporary_table",
+		// v2 structural fields
+		"access_type",
+		"covering",
+		"estimated_rows",
+		"estimated_total_cost",
+		"filter_columns",
+		"index_access_type",
+		"index_name",
+		"inputs",
+		"json_schema_version",
+		"limit",
+		"limit_offset",
+		"per_chunk_limit",
+		"ranges",
+		"row_ids",
+		"schema_name",
+		"sort_fields",
+		"table_name",
 	},
 }
-
-// defaultSQLPlanObfuscateSettings builds upon sqlPlanNormalizeSettings by including cost & row estimates in the keep
-// list
-var defaultSQLPlanObfuscateSettings = obfuscate.JSONConfig{
-	Enabled: true,
-	KeepValues: append([]string{
-		// mysql
-		"cost_info",
-		"filtered",
-		"rows_examined_per_join",
-		"rows_examined_per_scan",
-		"rows_produced_per_join",
-	}, defaultSQLPlanNormalizeSettings.KeepValues...),
-	ObfuscateSQLValues: defaultSQLPlanNormalizeSettings.ObfuscateSQLValues,
-}