fix(querybuilder): give each clickhouse sql refusal its own error code (#12339)

* fix(querybuilder): give each clickhouse sql refusal its own error code

Every refusal used CodeInvalidInput, so the only way to tell why a statement was
refused was to match on the message. Counting the failures on a live deployment
meant regexing the parser's text out of the log, and grouping by cause meant
knowing which of five different messages belonged to the same underlying gap.

One code per reason instead, which arrives as exception.code on the warning that
LogIfStatementIsNotValid writes, so the failures can be grouped and alerted on
directly.

Pin the expected code on each failing case, so the mapping is checked rather
than assumed.

* chore(querybuilder): drop the comment above the error codes

The names say it.

* fix(querybuilder): separate the parser panic code from the parse failure

A panic is a parser defect worth alerting on; a parse failure is a grammar gap
that shows up in ordinary traffic. Sharing one code lumps the two together.

frontend/vite.config.ts

@@ -143,6 +143,12 @@ export default defineConfig(({ mode }): UserConfig => {
 		plugins,
 		resolve: {
 			alias: {
+				// @grafana/data imports bare CJS `lodash`, whose UMD footer checks for an
+				// AMD loader before assigning module.exports. Any third-party script that
+				// defines window.define.amd first leaves the bundled namespace empty, so
+				// every lodash method reached through it is undefined at runtime. lodash-es
+				// is the same version, real ESM, and tree-shakes.
+				lodash: 'lodash-es',
 				'@': resolve(__dirname, './src'),
 				utils: resolve(__dirname, './src/utils'),
 				types: resolve(__dirname, './src/types'),

go.mod

@@ -4,7 +4,7 @@ go 1.25.7
 
 require (
 	dario.cat/mergo v1.0.2
-	github.com/AfterShip/clickhouse-sql-parser v0.5.2
+	github.com/AfterShip/clickhouse-sql-parser v0.5.3
 	github.com/ClickHouse/clickhouse-go/v2 v2.44.0
 	github.com/DATA-DOG/go-sqlmock v1.5.2
 	github.com/SigNoz/clickhouse-go-mock v0.14.0

go.sum

@@ -66,8 +66,8 @@ dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
 dmitri.shuralyov.com/gpu/mtl v0.0.0-20190408044501-666a987793e9/go.mod h1:H6x//7gZCb22OMCxBHrMx7a5I7Hp++hsVxbQ4BYO7hU=
 filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
-github.com/AfterShip/clickhouse-sql-parser v0.5.2 h1:KCxdmvuVawVF4yl0ZS33q7olgmLZwvZG5BjWHp6o414=
-github.com/AfterShip/clickhouse-sql-parser v0.5.2/go.mod h1:Qi3qvPTfZb/aFwI5V4WFOahgjsLJa4MzVijIAfwOhDw=
+github.com/AfterShip/clickhouse-sql-parser v0.5.3 h1:6iap8XGjuSjD3w7r1UNrg66ljBugcv2P39s4eo/ZLRw=
+github.com/AfterShip/clickhouse-sql-parser v0.5.3/go.mod h1:Qi3qvPTfZb/aFwI5V4WFOahgjsLJa4MzVijIAfwOhDw=
 github.com/Azure/azure-sdk-for-go v68.0.0+incompatible h1:fcYLmCpyNYRnvJbPerq7U0hS+6+I79yEDJBqVNcqUzU=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 h1:fou+2+WFTib47nS+nz/ozhEBnvU96bKHy6LjRsY4E28=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0/go.mod h1:t76Ruy8AHvUAC8GfMWJMa0ElSbuIcO03NLpynfbgsPA=

pkg/querybuilder/clickhouse_sql.go

@@ -9,6 +9,16 @@ import (
 	"github.com/SigNoz/signoz/pkg/errors"
 )
 
+var (
+	CodeClickHouseSQLParserPanic        = errors.MustNewCode("clickhouse_sql_parser_panic")
+	CodeClickHouseSQLUnparseable        = errors.MustNewCode("clickhouse_sql_unparseable")
+	CodeClickHouseSQLNotSingleStatement = errors.MustNewCode("clickhouse_sql_not_single_statement")
+	CodeClickHouseSQLNotSelect          = errors.MustNewCode("clickhouse_sql_not_select")
+	CodeClickHouseSQLTableFunction      = errors.MustNewCode("clickhouse_sql_table_function")
+	CodeClickHouseSQLInternalDatabase   = errors.MustNewCode("clickhouse_sql_internal_database")
+	CodeClickHouseSQLReadonlyOverride   = errors.MustNewCode("clickhouse_sql_readonly_override")
+)
+
 // internalDatabases hold server metadata, credentials and grants rather than telemetry.
 var internalDatabases = map[string]struct{}{
 	"system":             {},
@@ -20,30 +30,30 @@ func ErrIfStatementIsNotValid(query string) (err error) {
 	defer func() {
 		// The parser has a history of panicking on malformed input rather than returning an error.
 		if recovered := recover(); recovered != nil {
-			err = errors.NewInvalidInputf(errors.CodeInvalidInput, "invalid ClickHouse SQL (recovered): %v", recovered)
+			err = errors.NewInvalidInputf(CodeClickHouseSQLParserPanic, "invalid ClickHouse SQL (recovered): %v", recovered)
 		}
 	}()
 
 	stmts, parseErr := chparser.NewParser(query).ParseStmts()
 	if parseErr != nil {
 		// Wrapped rather than formatted in, so that callers can recover the parser's *ParseError and read the position off it.
-		return errors.WrapInvalidInputf(parseErr, errors.CodeInvalidInput, "invalid ClickHouse SQL: %s", parseErr.Error())
+		return errors.WrapInvalidInputf(parseErr, CodeClickHouseSQLUnparseable, "invalid ClickHouse SQL: %s", parseErr.Error())
 	}
 
 	if len(stmts) != 1 {
-		return errors.NewInvalidInputf(errors.CodeInvalidInput, "ClickHouse SQL must contain exactly one statement, found %d statements", len(stmts))
+		return errors.NewInvalidInputf(CodeClickHouseSQLNotSingleStatement, "ClickHouse SQL must contain exactly one statement, found %d statements", len(stmts))
 	}
 
 	selectQuery, ok := stmts[0].(*chparser.SelectQuery)
 	if !ok {
-		return errors.NewInvalidInputf(errors.CodeInvalidInput, "only SELECT statements are allowed in ClickHouse SQL queries")
+		return errors.NewInvalidInputf(CodeClickHouseSQLNotSelect, "only SELECT statements are allowed in ClickHouse SQL queries")
 	}
 
 	visitor := &chparser.DefaultASTVisitor{Visit: func(node chparser.Expr) error {
 		switch expr := node.(type) {
 		case *chparser.TableFunctionExpr:
 			// Source table functions remain usable in ClickHouse read-only mode.
-			return errors.NewInvalidInputf(errors.CodeInvalidInput, "ClickHouse table functions are not allowed in SQL queries: %s", chparser.Format(expr.Name))
+			return errors.NewInvalidInputf(CodeClickHouseSQLTableFunction, "ClickHouse table functions are not allowed in SQL queries: %s", chparser.Format(expr.Name))
 
 		case *chparser.TableIdentifier:
 			// Reading these is unaffected by ClickHouse read-only mode.
@@ -52,13 +62,13 @@ func ErrIfStatementIsNotValid(query string) (err error) {
 			}
 
 			if _, ok := internalDatabases[strings.ToLower(expr.Database.Name)]; ok {
-				return errors.NewInvalidInputf(errors.CodeInvalidInput, "the ClickHouse %s database is not allowed in SQL queries", expr.Database.Name)
+				return errors.NewInvalidInputf(CodeClickHouseSQLInternalDatabase, "the ClickHouse %s database is not allowed in SQL queries", expr.Database.Name)
 			}
 
 		case *chparser.SettingExpr:
 			// A query-level setting takes precedence over the context setting.
 			if strings.EqualFold(expr.Name.Name, "readonly") {
-				return errors.NewInvalidInputf(errors.CodeInvalidInput, "the ClickHouse readonly setting cannot be overridden")
+				return errors.NewInvalidInputf(CodeClickHouseSQLReadonlyOverride, "the ClickHouse readonly setting cannot be overridden")
 			}
 		}
 

pkg/querybuilder/clickhouse_sql_test.go

@@ -3,6 +3,8 @@ package querybuilder
 import (
 	"testing"
 
+	"github.com/SigNoz/signoz/pkg/errors"
+
 	chparser "github.com/AfterShip/clickhouse-sql-parser/parser"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -30,10 +32,15 @@ func TestErrIfStatementIsNotValid_Pass(t *testing.T) {
 		{"TrailingUnterminatedBlockComment", "SELECT count() FROM t /* unterminated"},
 		// The rule keys on the database, not on the table name.
 		{"TableNamedSystemInTelemetryDatabase", "SELECT * FROM signoz_logs.system"},
-		{"SignedLiteralAfterClosingParen", "SELECT (toUnixTimestamp(now()) - 3600)*1000000000"},
+		{"SignedLiteralAfterClosingParenSpaced", "SELECT (toUnixTimestamp(now()) - 3600)*1000000000"},
 		// order by interval
 		{"OrderByInterval", "SELECT toStartOfInterval(timestamp, INTERVAL 1 MINUTE) AS interval ORDER BY interval"},
 		{"OrderByIntervalAndDirection", "SELECT toStartOfInterval(timestamp, INTERVAL 1 MINUTE) AS `interval` ORDER BY `interval` ASC"},
+		// Unspaced, so rejected until the parser stopped lexing a signed literal after a
+		// closing bracket. The spaced form above no longer needs to be spaced.
+		// https://github.com/AfterShip/clickhouse-sql-parser/issues/286
+		{"SignedLiteralAfterClosingParenUnspaced", "SELECT now() AS ts, toFloat64(count()) AS value FROM ( SELECT attributes_string['TableName'] AS T, attributes_string['MissingId'] AS M, max(fromUnixTimestamp64Nano(timestamp)) AS last_seen, dateDiff('minute', min(fromUnixTimestamp64Nano(timestamp)), max(fromUnixTimestamp64Nano(timestamp))) AS age_min FROM signoz_logs.distributed_logs_v2 WHERE body='missing_map_record' AND timestamp >= (toUnixTimestamp(now())-3600)*1000000000 GROUP BY T, M ) WHERE age_min >= 20 AND last_seen >= now() - toIntervalMinute(8)"},
+		{"SignedLiteralAfterClosingParenMinimal", "SELECT (1)-1"},
 		{"TrimFunction", "SELECT trimBoth('/api/endpoint/', '/');"},
 	}
 
@@ -47,49 +54,52 @@ func TestErrIfStatementIsNotValid_Pass(t *testing.T) {
 
 func TestErrIfStatementIsNotValid_Fail(t *testing.T) {
 	testCases := []struct {
-		name  string
-		query string
+		name         string
+		query        string
+		expectedCode errors.Code
 	}{
 		// Not a single statement, or not a statement at all.
-		{"Empty", ""},
-		{"UnterminatedBlockCommentOnly", "/* x"},
-		{"Unparseable", "SELECT FROM WHERE"},
-		{"MultipleStatements", "SELECT 1; DROP TABLE signoz_logs.logs_v2"},
+		{"Empty", "", CodeClickHouseSQLNotSingleStatement},
+		{"UnterminatedBlockCommentOnly", "/* x", CodeClickHouseSQLUnparseable},
+		{"Unparseable", "SELECT FROM WHERE", CodeClickHouseSQLUnparseable},
+		{"MultipleStatements", "SELECT 1; DROP TABLE signoz_logs.logs_v2", CodeClickHouseSQLNotSingleStatement},
 		// Parses, but is not a SELECT.
-		{"Drop", "DROP TABLE signoz_logs.logs_v2"},
-		{"Insert", "INSERT INTO signoz_logs.logs_v2 SELECT * FROM signoz_logs.logs_v2"},
-		{"AlterDelete", "ALTER TABLE signoz_logs.logs_v2 DELETE WHERE 1 = 1"},
-		{"CreateTable", "CREATE TABLE evil (a Int) ENGINE = Memory"},
-		{"Grant", "GRANT ALL ON *.* TO admin"},
-		{"Set", "SET readonly = 0"},
+		{"Drop", "DROP TABLE signoz_logs.logs_v2", CodeClickHouseSQLNotSelect},
+		{"Insert", "INSERT INTO signoz_logs.logs_v2 SELECT * FROM signoz_logs.logs_v2", CodeClickHouseSQLNotSelect},
+		{"AlterDelete", "ALTER TABLE signoz_logs.logs_v2 DELETE WHERE 1 = 1", CodeClickHouseSQLNotSelect},
+		{"CreateTable", "CREATE TABLE evil (a Int) ENGINE = Memory", CodeClickHouseSQLNotSelect},
+		{"Grant", "GRANT ALL ON *.* TO admin", CodeClickHouseSQLNotSelect},
+		{"Set", "SET readonly = 0", CodeClickHouseSQLNotSelect},
 		// These the parser rejects outright rather than classifying.
-		{"ShowGrants", "SHOW GRANTS"},
-		{"IntoOutfile", "SELECT * FROM t INTO OUTFILE '/tmp/x.csv'"},
+		{"ShowGrants", "SHOW GRANTS", CodeClickHouseSQLUnparseable},
+		{"IntoOutfile", "SELECT * FROM t INTO OUTFILE '/tmp/x.csv'", CodeClickHouseSQLUnparseable},
 		// Table functions, which read through something other than a telemetry table.
-		{"UrlTableFunction", "SELECT * FROM url('http://attacker.example/x', CSV, 'a String')"},
-		{"FileTableFunction", "SELECT * FROM file('/etc/passwd', CSV, 'a String')"},
-		{"ExecutableTableFunction", "SELECT * FROM executable('script.sh', CSV, 'a String')"},
-		{"TableFunctionInJoin", "SELECT * FROM t1 JOIN url('http://x', CSV, 'a String') u ON 1 = 1"},
-		{"TableFunctionInCommonTableExpression", "WITH c AS (SELECT * FROM url('http://x', CSV, 'a String')) SELECT * FROM c"},
-		{"TableFunctionInWhereSubquery", "SELECT * FROM t WHERE a IN (SELECT * FROM file('/etc/passwd', CSV, 'a String'))"},
-		{"TableFunctionInUnion", "SELECT * FROM t UNION ALL SELECT * FROM url('http://x', CSV, 'a String')"},
+		{"UrlTableFunction", "SELECT * FROM url('http://attacker.example/x', CSV, 'a String')", CodeClickHouseSQLTableFunction},
+		{"FileTableFunction", "SELECT * FROM file('/etc/passwd', CSV, 'a String')", CodeClickHouseSQLTableFunction},
+		{"ExecutableTableFunction", "SELECT * FROM executable('script.sh', CSV, 'a String')", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInJoin", "SELECT * FROM t1 JOIN url('http://x', CSV, 'a String') u ON 1 = 1", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInCommonTableExpression", "WITH c AS (SELECT * FROM url('http://x', CSV, 'a String')) SELECT * FROM c", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInWhereSubquery", "SELECT * FROM t WHERE a IN (SELECT * FROM file('/etc/passwd', CSV, 'a String'))", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInUnion", "SELECT * FROM t UNION ALL SELECT * FROM url('http://x', CSV, 'a String')", CodeClickHouseSQLTableFunction},
 		// Internal databases, which hold grants and server metadata rather than telemetry.
-		{"SystemUsers", "SELECT * FROM system.users"},
-		{"SystemUppercase", "SELECT * FROM SYSTEM.USERS"},
-		{"SystemQuoted", "SELECT count() FROM `system`.`tables`"},
-		{"SystemInSubquery", "SELECT * FROM (SELECT name FROM system.parts)"},
-		{"SystemInJoin", "SELECT * FROM signoz_logs.distributed_logs_v2 AS l JOIN system.users AS u ON 1 = 1"},
-		{"SystemInIntersect", "SELECT * FROM t INTERSECT SELECT * FROM system.users"},
-		{"InformationSchema", "SELECT * FROM information_schema.tables"},
+		{"SystemUsers", "SELECT * FROM system.users", CodeClickHouseSQLInternalDatabase},
+		{"SystemUppercase", "SELECT * FROM SYSTEM.USERS", CodeClickHouseSQLInternalDatabase},
+		{"SystemQuoted", "SELECT count() FROM `system`.`tables`", CodeClickHouseSQLInternalDatabase},
+		{"SystemInSubquery", "SELECT * FROM (SELECT name FROM system.parts)", CodeClickHouseSQLInternalDatabase},
+		{"SystemInJoin", "SELECT * FROM signoz_logs.distributed_logs_v2 AS l JOIN system.users AS u ON 1 = 1", CodeClickHouseSQLInternalDatabase},
+		{"SystemInIntersect", "SELECT * FROM t INTERSECT SELECT * FROM system.users", CodeClickHouseSQLInternalDatabase},
+		{"InformationSchema", "SELECT * FROM information_schema.tables", CodeClickHouseSQLInternalDatabase},
 		// A query-level setting takes precedence over the one the caller applies.
-		{"ReadonlySettingOverride", "SELECT * FROM t SETTINGS readonly = 0"},
-		{"ReadonlySettingOverrideAmongOthers", "SELECT * FROM t SETTINGS max_threads = 4, readonly = 0"},
+		{"ReadonlySettingOverride", "SELECT * FROM t SETTINGS readonly = 0", CodeClickHouseSQLReadonlyOverride},
+		{"ReadonlySettingOverrideAmongOthers", "SELECT * FROM t SETTINGS max_threads = 4, readonly = 0", CodeClickHouseSQLReadonlyOverride},
 	}
 
 	for _, testCase := range testCases {
 		t.Run(testCase.name, func(t *testing.T) {
 			err := ErrIfStatementIsNotValid(testCase.query)
+
 			assert.Error(t, err)
+			assert.True(t, errors.Asc(err, testCase.expectedCode), "expected code %s, got %v", testCase.expectedCode, err)
 		})
 	}
 }
@@ -122,18 +132,6 @@ func TestErrIfStatementIsNotValid_ShouldPassButFails(t *testing.T) {
 			expectedStopsAfter: "trim(BOTH '",
 			fix:                "SELECT trimBoth(replaceOne( JSONExtractString(body, 'Action'), 'health_status: ', '' ), ' ')",
 		},
-		{
-			name:               "SignedLiteralAfterClosingParen",
-			query:              "SELECT now() AS ts, toFloat64(count()) AS value FROM ( SELECT attributes_string['TableName'] AS T, attributes_string['MissingId'] AS M, max(fromUnixTimestamp64Nano(timestamp)) AS last_seen, dateDiff('minute', min(fromUnixTimestamp64Nano(timestamp)), max(fromUnixTimestamp64Nano(timestamp))) AS age_min FROM signoz_logs.distributed_logs_v2 WHERE body='missing_map_record' AND timestamp >= (toUnixTimestamp(now())-3600)*1000000000 GROUP BY T, M ) WHERE age_min >= 20 AND last_seen >= now() - toIntervalMinute(8)",
-			expectedStopsAfter: "(toUnixTimestamp(now())",
-			fix:                "SELECT (toUnixTimestamp(now()) - 3600) * 1000000000",
-		},
-		{
-			name:               "SignedLiteralAfterClosingParenMinimal",
-			query:              "SELECT (1)-1",
-			expectedStopsAfter: "(1)",
-			fix:                "SELECT (1) - 1",
-		},
 	}
 
 	for _, testCase := range testCases {

pkg/statementbuilder/auditstatementbuilder/statement_builder.go

@@ -205,7 +205,7 @@ func (b *auditQueryStatementBuilder) adjustKeys(ctx context.Context, keys map[st
 	}
 
 	for _, action := range actions {
-		b.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 
 	return query

pkg/statementbuilder/logsstatementbuilder/statement_builder.go

@@ -274,8 +274,7 @@ func (b *logQueryStatementBuilder) adjustKeys(ctx context.Context, keys map[stri
 	}
 
 	for _, action := range actions {
-		// TODO: change to debug level once we are confident about the behavior
-		b.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 
 	return query

pkg/statementbuilder/tracesstatementbuilder/statement_builder.go

@@ -127,8 +127,7 @@ func (b *traceQueryStatementBuilder) Build(
 	}
 
 	for _, action := range adjustTraceKeys(keys, &query, requestType) {
-		// TODO: change to debug level once we are confident about the behavior
-		b.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 	// Create SQL builder
 	q := sqlbuilder.NewSelectBuilder()

pkg/statementbuilder/tracesstatementbuilder/trace_operator_cte_builder.go

@@ -223,8 +223,7 @@ func (b *traceOperatorCTEBuilder) buildQueryCTE(ctx context.Context, queryName s
 	// The CTE only selects spans matching the filter. Aggregations, group by
 	// and order by run later in buildFinalQuery, so RequestTypeRaw is fine here.
 	for _, action := range adjustTraceKeys(keys, query, qbtypes.RequestTypeRaw) {
-		// TODO: change to debug level once we are confident about the behavior
-		b.stmtBuilder.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.stmtBuilder.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 
 	// Build resource filter CTE for this specific query
@@ -576,7 +575,7 @@ func (b *traceOperatorCTEBuilder) adjustOperatorKeys(ctx context.Context, keys m
 	b.operator.Order = tmp.Order
 
 	for _, action := range actions {
-		b.stmtBuilder.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.stmtBuilder.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 }