refactor(observability): simplify SelectBest config matching and update default configs

fanhua-bytedance · fanhua-bytedance · commit a48b68bbf139 · 2026-04-27T14:10:54.000+08:00
- Rewrite SelectBest to use two-phase direct matching instead of bit-score approach
- Reduce default column extract configs from 3 to 2: (0,*,llm_span) and (0,prompt,root_span)
- Change span_list_type SQL query from wildcard IN to exact match
- Update tests with 20 cases for 100% SelectBest coverage
diff --git a/backend/modules/observability/domain/trace/entity/column_extract_config.go b/backend/modules/observability/domain/trace/entity/column_extract_config.go
@@ -50,85 +50,27 @@ func (c *ColumnExtractConfig) Extract(content string, column string) string {
 // ColumnExtractConfigs is a list of ColumnExtractConfig with selection logic.
 type ColumnExtractConfigs []*ColumnExtractConfig
 
-// SelectBest selects the best matching config using a scoring strategy.
-//
-// Priority dimensions (highest to lowest weight):
-//  1. Workspace: target workspace > default (wsID=0). Cross-workspace configs are excluded.
-//  2. Agent: exact agent match > empty agent (wildcard).
-//  3. SpanListType: exact match > wildcard '*'.
-//  4. PlatformType: exact match > wildcard '*'.
-//
-// Returns nil if no config matches.
 func (configs ColumnExtractConfigs) SelectBest(workspaceId int64, agentName, platformType, spanListType string) *ColumnExtractConfig {
-	var (
-		best      *ColumnExtractConfig
-		bestScore int
-	)
-
+	var bestConfig *ColumnExtractConfig
 	for _, cfg := range configs {
-		score := configScore(cfg, workspaceId, agentName, platformType, spanListType)
-		if score < 0 {
-			continue // not a valid match
-		}
-		if best == nil || score > bestScore {
-			best = cfg
-			bestScore = score
+		if cfg.WorkspaceID == workspaceId && cfg.PlatformType == platformType && cfg.SpanListType == spanListType && cfg.AgentName == agentName {
+			bestConfig = cfg
+			break
+		} else if cfg.WorkspaceID == workspaceId && cfg.PlatformType == platformType && cfg.SpanListType == spanListType && cfg.AgentName == "" {
+			bestConfig = cfg
 		}
 	}
-
-	return best
-}
-
-// configScore computes a match score for a config. Returns -1 if the config doesn't match.
-// Higher score = better match. Score layout (4 bits):
-//
-//	bit 3 (8): workspace match (target ws=1, default ws=0)
-//	bit 2 (4): agent match (exact=1, empty=0)
-//	bit 1 (2): spanListType match (exact=1, wildcard=0)
-//	bit 0 (1): platformType match (exact=1, wildcard=0)
-func configScore(cfg *ColumnExtractConfig, workspaceId int64, agentName, platformType, spanListType string) int {
-	// workspace: must be target or default(0), reject cross-workspace
-	isTarget := cfg.WorkspaceID == workspaceId
-	isDefault := cfg.WorkspaceID == 0
-	if !isTarget && !isDefault {
-		return -1
-	}
-
-	// agent: must be exact match or empty wildcard
-	agentMatch := agentName != "" && cfg.AgentName == agentName
-	agentEmpty := cfg.AgentName == ""
-	if !agentMatch && !agentEmpty {
-		return -1
-	}
-
-	// platformType: must be exact or wildcard '*'
-	platformExact := cfg.PlatformType == platformType
-	platformWild := cfg.PlatformType == "*"
-	if !platformExact && !platformWild {
-		return -1
-	}
-
-	// spanListType: must be exact or wildcard '*'
-	spanExact := cfg.SpanListType == spanListType
-	spanWild := cfg.SpanListType == "*"
-	if !spanExact && !spanWild {
-		return -1
-	}
-
-	score := 0
-	if isTarget {
-		score |= 8
-	}
-	if agentMatch {
-		score |= 4
-	}
-	if platformExact {
-		score |= 1
-	}
-	if spanExact {
-		score |= 2
+	// Fallback to  default
+	if bestConfig == nil {
+		for _, cfg := range configs {
+			if cfg.WorkspaceID == 0 && cfg.AgentName == "" && cfg.SpanListType == spanListType &&
+				(cfg.PlatformType == platformType || cfg.PlatformType == "*") {
+				bestConfig = cfg
+				break
+			}
+		}
 	}
-	return score
+	return bestConfig
 }
 
 func extractByJSONPath(content, jsonPath string) string {
diff --git a/backend/modules/observability/domain/trace/entity/column_extract_config_test.go b/backend/modules/observability/domain/trace/entity/column_extract_config_test.go
@@ -27,10 +27,9 @@ func TestColumnExtractConfigs_SelectBest(t *testing.T) {
 		// workspace-specific configs
 		makeConfig(42, "my_bot", "coze_loop", "llm_span"),
 		makeConfig(42, "", "coze_loop", "llm_span"),
-		// default configs (wsID=0, with wildcards)
-		makeConfig(0, "", "*", "llm_span"), // all platform llm_span default
-		makeConfig(0, "", "prompt", "*"),   // prompt platform default
-		makeConfig(0, "", "*", "*"),        // universal fallback
+		// default configs (wsID=0)
+		makeConfig(0, "", "*", "llm_span"),       // all platform llm_span default
+		makeConfig(0, "", "prompt", "root_span"), // prompt root_span default
 	}
 
 	tests := []struct {
@@ -83,19 +82,19 @@ func TestColumnExtractConfigs_SelectBest(t *testing.T) {
 			wantSpan:     "llm_span",
 		},
 		{
-			name:         "no ws match, prompt platform -> default prompt, *",
+			name:         "no ws match, prompt + root_span -> default prompt, root_span",
 			configs:      allConfigs,
 			workspaceId:  999,
 			agentName:    "",
 			platformType: "prompt",
-			spanListType: "all_span",
+			spanListType: "root_span",
 			wantWsID:     0,
 			wantAgent:    "",
 			wantPlatform: "prompt",
-			wantSpan:     "*",
+			wantSpan:     "root_span",
 		},
 		{
-			name:         "prompt + llm_span: spanList exact (*,llm_span) wins over platform exact (prompt,*)",
+			name:         "prompt + llm_span: spanList exact (*,llm_span) wins",
 			configs:      allConfigs,
 			workspaceId:  999,
 			agentName:    "",
@@ -105,19 +104,17 @@ func TestColumnExtractConfigs_SelectBest(t *testing.T) {
 			wantAgent:    "",
 			wantPlatform: "*",
 			wantSpan:     "llm_span",
-			// score: (*,llm_span) = 0+0+2+0 = 2; (prompt,*) = 0+0+0+1 = 1 -> llm_span wins
 		},
 		{
-			name:         "unknown platform + unknown spanList -> universal fallback",
-			configs:      allConfigs,
+			name: "unknown platform + unknown spanList -> no match",
+			// DB query with platform_type IN ('custom','*') AND span_list_type IN ('custom_span','*')
+			// returns nothing since no universal fallback exists
+			configs:      ColumnExtractConfigs{},
 			workspaceId:  999,
 			agentName:    "",
 			platformType: "custom",
 			spanListType: "custom_span",
-			wantWsID:     0,
-			wantAgent:    "",
-			wantPlatform: "*",
-			wantSpan:     "*",
+			wantNil:      true,
 		},
 		{
 			name:         "empty configs returns nil",
@@ -177,10 +174,10 @@ func TestColumnExtractConfigs_SelectBest(t *testing.T) {
 			wantNil:      true,
 		},
 		{
-			name: "ws match + spanList match but agent and platform mismatch -> fallback to universal",
+			name: "ws match + agent and platform mismatch -> fallback to default spanList match",
 			configs: ColumnExtractConfigs{
-				makeConfig(42, "bot_a", "prompt", "llm_span"), // agent mismatch, platform mismatch
-				makeConfig(0, "", "*", "*"),                   // universal fallback
+				makeConfig(42, "bot_a", "prompt", "llm_span"), // agent mismatch
+				makeConfig(0, "", "*", "llm_span"),            // default with spanList match
 			},
 			workspaceId:  42,
 			agentName:    "bot_x",
@@ -189,7 +186,122 @@ func TestColumnExtractConfigs_SelectBest(t *testing.T) {
 			wantWsID:     0,
 			wantAgent:    "",
 			wantPlatform: "*",
-			wantSpan:     "*",
+			wantSpan:     "llm_span",
+		},
+		{
+			name: "exact agent wins over empty agent even when empty agent appears first",
+			configs: ColumnExtractConfigs{
+				makeConfig(42, "", "coze_loop", "llm_span"),
+				makeConfig(42, "my_bot", "coze_loop", "llm_span"),
+			},
+			workspaceId:  42,
+			agentName:    "my_bot",
+			platformType: "coze_loop",
+			spanListType: "llm_span",
+			wantWsID:     42,
+			wantAgent:    "my_bot",
+			wantPlatform: "coze_loop",
+			wantSpan:     "llm_span",
+		},
+		{
+			name: "ws match but spanList mismatch -> fallback to default",
+			configs: ColumnExtractConfigs{
+				makeConfig(42, "", "coze_loop", "llm_span"),
+				makeConfig(0, "", "*", "root_span"),
+			},
+			workspaceId:  42,
+			agentName:    "",
+			platformType: "coze_loop",
+			spanListType: "root_span",
+			wantWsID:     0,
+			wantAgent:    "",
+			wantPlatform: "*",
+			wantSpan:     "root_span",
+		},
+		{
+			name: "ws match but platform mismatch -> fallback to default wildcard platform",
+			configs: ColumnExtractConfigs{
+				makeConfig(42, "", "prompt", "llm_span"),
+				makeConfig(0, "", "*", "llm_span"),
+			},
+			workspaceId:  42,
+			agentName:    "",
+			platformType: "coze_loop",
+			spanListType: "llm_span",
+			wantWsID:     0,
+			wantAgent:    "",
+			wantPlatform: "*",
+			wantSpan:     "llm_span",
+		},
+		{
+			name: "fallback: first matching config wins (order dependent)",
+			configs: ColumnExtractConfigs{
+				makeConfig(0, "", "*", "root_span"),
+				makeConfig(0, "", "prompt", "root_span"),
+			},
+			workspaceId:  999,
+			agentName:    "",
+			platformType: "prompt",
+			spanListType: "root_span",
+			wantWsID:     0,
+			wantAgent:    "",
+			wantPlatform: "*",
+			wantSpan:     "root_span",
+		},
+		{
+			name: "fallback: exact platform wins when it appears first",
+			configs: ColumnExtractConfigs{
+				makeConfig(0, "", "prompt", "root_span"),
+				makeConfig(0, "", "*", "root_span"),
+			},
+			workspaceId:  999,
+			agentName:    "",
+			platformType: "prompt",
+			spanListType: "root_span",
+			wantWsID:     0,
+			wantAgent:    "",
+			wantPlatform: "prompt",
+			wantSpan:     "root_span",
+		},
+		{
+			name: "workspaceId=0 matches default configs directly",
+			configs: ColumnExtractConfigs{
+				makeConfig(0, "", "*", "llm_span"),
+				makeConfig(0, "", "prompt", "root_span"),
+			},
+			workspaceId:  0,
+			agentName:    "",
+			platformType: "coze_loop",
+			spanListType: "llm_span",
+			wantWsID:     0,
+			wantAgent:    "",
+			wantPlatform: "*",
+			wantSpan:     "llm_span",
+		},
+		{
+			name: "single config exact match",
+			configs: ColumnExtractConfigs{
+				makeConfig(42, "bot", "coze_loop", "llm_span"),
+			},
+			workspaceId:  42,
+			agentName:    "bot",
+			platformType: "coze_loop",
+			spanListType: "llm_span",
+			wantWsID:     42,
+			wantAgent:    "bot",
+			wantPlatform: "coze_loop",
+			wantSpan:     "llm_span",
+		},
+		{
+			name: "single config no match -> nil",
+			configs: ColumnExtractConfigs{
+				makeConfig(42, "", "coze_loop", "llm_span"),
+			},
+			workspaceId:  42,
+			agentName:    "",
+			platformType: "coze_loop",
+			spanListType: "root_span",
+			wantNil:      true,
 		},
 	}
 
@@ -209,44 +321,6 @@ func TestColumnExtractConfigs_SelectBest(t *testing.T) {
 	}
 }
 
-func TestConfigScore(t *testing.T) {
-	cfg := &ColumnExtractConfig{
-		WorkspaceID: 42, AgentName: "bot", PlatformType: "coze_loop", SpanListType: "llm_span",
-	}
-	// Full exact match = 8+4+2+1 = 15
-	require.Equal(t, 15, configScore(cfg, 42, "bot", "coze_loop", "llm_span"))
-
-	// Cross-workspace = -1
-	require.Equal(t, -1, configScore(cfg, 999, "bot", "coze_loop", "llm_span"))
-
-	// Agent mismatch (non-empty agent in config, different query agent) = -1
-	require.Equal(t, -1, configScore(cfg, 42, "other", "coze_loop", "llm_span"))
-
-	// Default ws=0, wildcard platform/span
-	defaultCfg := &ColumnExtractConfig{
-		WorkspaceID: 0, AgentName: "", PlatformType: "*", SpanListType: "*",
-	}
-	// score = 0 (default ws) + 0 (empty agent) + 0 (wildcard platform) + 0 (wildcard span) = 0
-	require.Equal(t, 0, configScore(defaultCfg, 42, "bot", "coze_loop", "llm_span"))
-
-	// Default ws=0, exact span
-	llmDefault := &ColumnExtractConfig{
-		WorkspaceID: 0, AgentName: "", PlatformType: "*", SpanListType: "llm_span",
-	}
-	// score = 0 + 0 + 2 + 0 = 2
-	require.Equal(t, 2, configScore(llmDefault, 42, "bot", "coze_loop", "llm_span"))
-
-	// Default ws=0, exact platform
-	promptDefault := &ColumnExtractConfig{
-		WorkspaceID: 0, AgentName: "", PlatformType: "prompt", SpanListType: "*",
-	}
-	// score = 0 + 0 + 0 + 1 = 1
-	require.Equal(t, 1, configScore(promptDefault, 42, "", "prompt", "all_span"))
-
-	// Platform mismatch, not wildcard = -1
-	require.Equal(t, -1, configScore(promptDefault, 42, "", "coze_loop", "llm_span"))
-}
-
 func TestColumnExtractConfig_Extract(t *testing.T) {
 	cfg := &ColumnExtractConfig{
 		Columns: []ColumnExtractRule{
diff --git a/backend/modules/observability/domain/trace/service/trace/span_processor/clip_processor_test.go b/backend/modules/observability/domain/trace/service/trace/span_processor/clip_processor_test.go
@@ -313,7 +313,7 @@ func TestClipProcessor_WithDBConfig(t *testing.T) {
 				{
 					WorkspaceID:  0,
 					PlatformType: "*",
-					SpanListType: "*",
+					SpanListType: string(loop_span.SpanListTypeLLMSpan),
 					Columns: []entity.ColumnExtractRule{
 						{Column: "input", JSONPath: "$..content"},
 						{Column: "output", JSONPath: "$..content"},
@@ -388,7 +388,7 @@ func TestClipProcessor_WithDBConfigLongContent(t *testing.T) {
 			{
 				WorkspaceID:  0,
 				PlatformType: "*",
-				SpanListType: "*",
+				SpanListType: string(loop_span.SpanListTypeLLMSpan),
 				Columns: []entity.ColumnExtractRule{
 					{Column: "input", JSONPath: "$.messages[0].content"},
 				},
@@ -420,7 +420,7 @@ func TestClipProcessor_DefaultConfigSelection(t *testing.T) {
 		WorkspaceID:  0,
 		AgentName:    "",
 		PlatformType: "*",
-		SpanListType: "*",
+		SpanListType: string(loop_span.SpanListTypeLLMSpan),
 		Columns: []entity.ColumnExtractRule{
 			{Column: "input", JSONPath: "$..content"},
 			{Column: "output", JSONPath: "$..content"},
diff --git a/backend/modules/observability/infra/repo/mysql/column_extract_config.go b/backend/modules/observability/infra/repo/mysql/column_extract_config.go
@@ -77,7 +77,7 @@ func (t ColumnExtractConfigDaoImpl) ListColumnExtractConfigs(ctx context.Context
 	err := t.dbMgr.NewSession(ctx).WithContext(ctx).
 		Where("workspace_id IN (?)", []int64{0, workspaceID}).
 		Where("platform_type IN (?, '*')", platformType).
-		Where("span_list_type IN (?, '*')", spanListType).
+		Where("span_list_type = ?", spanListType).
 		Where("is_deleted = ?", false).
 		Find(&pos).Error
 	if err != nil {
diff --git a/release/deployment/docker-compose/bootstrap/mysql-init/init-sql/observability_column_extract_config.sql b/release/deployment/docker-compose/bootstrap/mysql-init/init-sql/observability_column_extract_config.sql
@@ -23,6 +23,5 @@ CREATE TABLE IF NOT EXISTS `observability_column_extract_config`
 INSERT INTO `observability_column_extract_config` (`id`, `workspace_id`, `platform_type`, `span_list_type`, `agent_name`, `config`, `created_by`, `updated_by`)
 VALUES
     (1, 0, '*', 'llm_span', '', '[{"Column":"input","JSONPath":"$.messages[-1:].content"},{"Column":"output","JSONPath":"$.choices[0].message.content"}]', 'system', 'system'),
-    (2, 0, 'prompt', '*', '', '[{"Column":"input","JSONPath":"$.query.Content"},{"Column":"output","JSONPath":"$.choices[0].message.content"}]', 'system', 'system'),
-    (3, 0, '*', '*', '', '[{"Column":"input","JSONPath":"$..content"},{"Column":"output","JSONPath":"$..content"}]', 'system', 'system')
+    (2, 0, 'prompt', 'root_span', '', '[{"Column":"input","JSONPath":"$.query.Content"},{"Column":"output","JSONPath":"$.choices[0].message.content"}]', 'system', 'system')
 ON DUPLICATE KEY UPDATE `id` = `id`;
diff --git a/release/deployment/helm-chart/charts/app/bootstrap/init/mysql/init-sql/observability_column_extract_config.sql b/release/deployment/helm-chart/charts/app/bootstrap/init/mysql/init-sql/observability_column_extract_config.sql
@@ -23,6 +23,5 @@ CREATE TABLE IF NOT EXISTS `observability_column_extract_config`
 INSERT INTO `observability_column_extract_config` (`id`, `workspace_id`, `platform_type`, `span_list_type`, `agent_name`, `config`, `created_by`, `updated_by`)
 VALUES
     (1, 0, '*', 'llm_span', '', '[{"Column":"input","JSONPath":"$.messages[-1:].content"},{"Column":"output","JSONPath":"$.choices[0].message.content"}]', 'system', 'system'),
-    (2, 0, 'prompt', '*', '', '[{"Column":"input","JSONPath":"$.query.Content"},{"Column":"output","JSONPath":"$.choices[0].message.content"}]', 'system', 'system'),
-    (3, 0, '*', '*', '', '[{"Column":"input","JSONPath":"$..content"},{"Column":"output","JSONPath":"$..content"}]', 'system', 'system')
+    (2, 0, 'prompt', 'root_span', '', '[{"Column":"input","JSONPath":"$.query.Content"},{"Column":"output","JSONPath":"$.choices[0].message.content"}]', 'system', 'system')
 ON DUPLICATE KEY UPDATE `id` = `id`;
