feat: Add important_events capture to filter settings

Context:
Operators monitoring Git processes that run gvfs-helper subcommands
need visibility into specific data event values (error strings, curl
codes, etc.) even when verbose telemetry is disabled. At dl:summary
level all data events are currently dropped, so there is no way to
guarantee critical diagnostic values surface in the OTEL process span
without enabling expensive full-verbose collection site-wide.

Justification:
The rules live in filter.yml, not summary.yml, because capture is a
filtering concern: it determines which data events are guaranteed to
appear regardless of detail level, paralleling how filter rules
control verbosity. The captured values are stored in their own OTEL
attribute (trace2.process.important_events) separate from
trace2.process.summary, keeping aggregated metrics distinct from
verbatim strings. The capture call in apply__data_generic runs before
any early-return paths so that orphaned nested events (nesting > 1
with an empty region stack) are never silently dropped.

Implementation:
ImportantEventRule (category exact match, key_prefix prefix match,
field_name output key) is added to FilterSettings and validated in
parseFilterSettingsFromBuffer. TrProcess gains an importantEvents map
that is allocated only when rules exist, so the nil check in
apply__important_events serves as a fast no-op when the feature is
unconfigured. apply__important_events in filter_settings.go matches
each data event against the configured rules and appends matching
values. emitProcessSpan emits trace2.process.important_events as a
JSON object whenever the map is non-empty, at all detail levels.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: derrickstolee

evt_apply.go

@@ -830,6 +830,14 @@ func apply__data_generic(tr2 *trace2Dataset, evt *TrEvent) (err error) {
 	// nesting level n-1 is stored at regionStack[n-2] (assuming the
 	// Git process properly sets things up).
 
+	// Capture matching data values into importantEvents regardless of
+	// nesting level. This must run before any early returns below
+	// so that capture is not skipped when region attachment fails.
+	apply__important_events(tr2,
+		evt.pm_generic_data.mf_category,
+		evt.pm_generic_data.mf_key,
+		evt.pm_generic_data.mf_generic_value)
+
 	if evt.pm_generic_data.mf_nesting <= 1 {
 		tr2.process.setGenericDataValue(evt.pm_generic_data.mf_category,
 			evt.pm_generic_data.mf_key, evt.pm_generic_data.mf_generic_value)

filter_settings.go

@@ -10,16 +10,36 @@ import (
 // look for in the Trace2 event stream to help us decide how to
 // filter data for a particular command.
 type FilterSettings struct {
-	Keynames  FilterKeynames  `mapstructure:"keynames"`
-	Nicknames FilterNicknames `mapstructure:"nicknames"`
-	Rulesets  FilterRulesets  `mapstructure:"rulesets"`
-	Defaults  FilterDefaults  `mapstructure:"defaults"`
+	Keynames        FilterKeynames   `mapstructure:"keynames"`
+	Nicknames       FilterNicknames  `mapstructure:"nicknames"`
+	Rulesets        FilterRulesets   `mapstructure:"rulesets"`
+	Defaults        FilterDefaults   `mapstructure:"defaults"`
+	ImportantEvents []ImportantEventRule `mapstructure:"important_events"`
 
 	// The set of custom rulesets defined in YML are each parsed
 	// and loaded into definitions so that we can use them.
 	rulesetDefs map[string]*RulesetDefinition
 }
 
+// ImportantEventRule defines a rule for promoting values from data events
+// that match a specific (category, key prefix) pair into the process
+// summary, regardless of the active detail level. This lets operators
+// guarantee that certain data event values are always captured and
+// surfaced in the OTEL process span even when verbose telemetry is
+// disabled. Multiple matching values are collected into an array.
+type ImportantEventRule struct {
+	// Category is the data event category to match (exact match)
+	Category string `mapstructure:"category"`
+
+	// KeyPrefix is the string prefix to match at the beginning of
+	// the data event's key field
+	KeyPrefix string `mapstructure:"key_prefix"`
+
+	// FieldName is the name of the field in the summary object
+	// where matched values will be stored (always as an array)
+	FieldName string `mapstructure:"field_name"`
+}
+
 // FilterKeynames defines the names of the Git config settings that
 // will be used in `def_param` events to send repository/worktree
 // data to us.  This lets a site have their own namespace for
@@ -100,9 +120,52 @@ func parseFilterSettingsFromBuffer(data []byte, path string) (*FilterSettings, e
 		}
 	}
 
+	fieldNames := make(map[string]bool)
+	for i, rule := range fs.ImportantEvents {
+		if len(rule.Category) == 0 {
+			return nil, fmt.Errorf("important_events[%d]: category cannot be empty", i)
+		}
+		if len(rule.KeyPrefix) == 0 {
+			return nil, fmt.Errorf("important_events[%d]: key_prefix cannot be empty", i)
+		}
+		if len(rule.FieldName) == 0 {
+			return nil, fmt.Errorf("important_events[%d]: field_name cannot be empty", i)
+		}
+		if fieldNames[rule.FieldName] {
+			return nil, fmt.Errorf("important_events[%d]: duplicate field_name '%s'", i, rule.FieldName)
+		}
+		fieldNames[rule.FieldName] = true
+	}
+
 	return fs, nil
 }
 
+// apply__important_events checks if a data event matches any configured
+// important_events rules and appends the event's value to the
+// importantEvents map if a match is found. Matching events are captured
+// regardless of nesting level or detail level.
+func apply__important_events(tr2 *trace2Dataset, category string, key string, value interface{}) {
+	if tr2.process.importantEvents == nil {
+		return
+	}
+
+	if tr2.rcvr_base == nil || tr2.rcvr_base.RcvrConfig == nil {
+		return
+	}
+
+	fs := tr2.rcvr_base.RcvrConfig.filterSettings
+	if fs == nil {
+		return
+	}
+
+	for _, rule := range fs.ImportantEvents {
+		if category == rule.Category && strings.HasPrefix(key, rule.KeyPrefix) {
+			tr2.process.importantEvents[rule.FieldName] = append(
+				tr2.process.importantEvents[rule.FieldName], value)
+		}
+	}
+}
+
 // Add a ruleset to the filter settings.  This is primarily for writing test code.
 func (fs *FilterSettings) addRuleset(rs_name string, path string, rsdef *RulesetDefinition) {
 	if fs.Rulesets == nil {

filter_settings_test.go

@@ -290,6 +290,81 @@ func x_TryLoadRuleset(t *testing.T, fs *FilterSettings, name string, path string
 
 // //////////////////////////////////////////////////////////////
 
+// //////////////////////////////////////////////////////////////
+// important_events validation tests
+
+func Test_ImportantEvents_Valid(t *testing.T) {
+	yml := `
+important_events:
+  - category: "gvfs-helper"
+    key_prefix: "error/"
+    field_name: "gvfs_helper_errors"
+  - category: "network"
+    key_prefix: "timeout/"
+    field_name: "network_timeouts"
+`
+	fs, err := parseFilterSettingsFromBuffer([]byte(yml), "test.yml")
+	assert.NoError(t, err)
+	assert.NotNil(t, fs)
+	assert.Equal(t, 2, len(fs.ImportantEvents))
+	assert.Equal(t, "gvfs-helper", fs.ImportantEvents[0].Category)
+	assert.Equal(t, "error/", fs.ImportantEvents[0].KeyPrefix)
+	assert.Equal(t, "gvfs_helper_errors", fs.ImportantEvents[0].FieldName)
+}
+
+func Test_ImportantEvents_EmptyCategory_Rejected(t *testing.T) {
+	yml := `
+important_events:
+  - category: ""
+    key_prefix: "error/"
+    field_name: "errors"
+`
+	_, err := parseFilterSettingsFromBuffer([]byte(yml), "test.yml")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "category cannot be empty")
+}
+
+func Test_ImportantEvents_EmptyKeyPrefix_Rejected(t *testing.T) {
+	yml := `
+important_events:
+  - category: "gvfs-helper"
+    key_prefix: ""
+    field_name: "errors"
+`
+	_, err := parseFilterSettingsFromBuffer([]byte(yml), "test.yml")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "key_prefix cannot be empty")
+}
+
+func Test_ImportantEvents_EmptyFieldName_Rejected(t *testing.T) {
+	yml := `
+important_events:
+  - category: "gvfs-helper"
+    key_prefix: "error/"
+    field_name: ""
+`
+	_, err := parseFilterSettingsFromBuffer([]byte(yml), "test.yml")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "field_name cannot be empty")
+}
+
+func Test_ImportantEvents_DuplicateFieldName_Rejected(t *testing.T) {
+	yml := `
+important_events:
+  - category: "gvfs-helper"
+    key_prefix: "error/"
+    field_name: "shared_name"
+  - category: "network"
+    key_prefix: "timeout/"
+    field_name: "shared_name"
+`
+	_, err := parseFilterSettingsFromBuffer([]byte(yml), "test.yml")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "duplicate field_name")
+}
+
+// //////////////////////////////////////////////////////////////
+
 func Test_Nil_Nil_FilterSettings(t *testing.T) {
 
 	dl, dl_debug := computeDetailLevel(nil, nil, x_qn)