docs: Document important_events filter configuration

Context:
The important_events feature added in the previous commit has no
user-facing documentation. Operators need to know the YAML syntax,
the semantics of each field, the output attribute name, and how the
feature relates to summary.yml so they can distinguish verbatim
capture from aggregated metrics.

Implementation:
config-filter-settings.md gains a new "Important Events" section
with YAML syntax, field descriptions, and a worked example showing
gvfs-helper error capture. The filter syntax summary at the bottom
is extended with the important_events block so the complete schema
appears in one place. configure-custom-collector.md documents the
filter: pathname key (previously undocumented in the receiver config
example) and adds a cross-reference to important_events. The summary
example YAML adds a note directing readers to filter.yml for verbatim
value capture, distinguishing it from the aggregated summary output.

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

Author: derrickstolee

Docs/Examples/summary_example.yml

@@ -44,3 +44,6 @@ region_timers:
 #     "batchTime": 12.3
 #   }
 # }
+#
+# To also capture specific data event values verbatim in the summary,
+# add important_events rules to your filter.yml instead.

Docs/config-filter-settings.md

@@ -254,6 +254,47 @@ the `ruleset_key`.)
 
 
 
+## Important Events
+
+In addition to controlling verbosity, the `filter.yml` file can
+declare a list of data events that should always be captured verbatim,
+regardless of the active detail level.  This lets operators guarantee
+that specific Trace2 data values are always surfaced in the OTEL
+process span even when verbose telemetry is disabled.
+
+Each rule matches data events by `category` (exact match) and
+`key_prefix` (prefix match on the event's key field).  All matching
+values are collected into an array under the specified `field_name` in
+the `trace2.process.important_events` span attribute.
+
+```
+important_events:
+  - category: <category-string>
+    key_prefix: <key-prefix-string>
+    field_name: <field-name>
+  ...
+```
+
+For example, to always capture error details from a `gvfs-helper`
+subprocess regardless of how verbosity is configured:
+
+```
+important_events:
+  - category: "gvfs-helper"
+    key_prefix: "error/"
+    field_name: "gvfs_helper_errors"
+```
+
+This would produce the following in the OTEL process span:
+
+```
+"trace2.process.important_events": {
+  "gvfs_helper_errors": ["(curl:35) SSL connect error [hard_fail]"]
+}
+```
+
+
+
 ## Filter Settings Syntax
 
 Now that all of the concepts have been introduced, we can describe
@@ -277,6 +318,12 @@ rulesets:
 
 defaults:
   ruleset: <ruleset-name> | <detail-level>
+
+important_events:
+  - category: <category-string>
+    key_prefix: <key-prefix-string>
+    field_name: <summary-field-name>
+  ...
 ```
 
 The value of the `defaults.ruleset` parameter will be used when a Git

Docs/configure-custom-collector.md

@@ -46,6 +46,7 @@ receivers:
     pipe:   <windows-named-pipe-pathname>
     pii:    <pii-settings-pathname>
     filter: <filter-settings-pathname>
+    summary: <summary-settings-pathname>
 ```
 
 For example:
@@ -57,6 +58,7 @@ receivers:
     pipe:   "//./pipe/my-collector.pipe"
     pii:    "/usr/local/my-collector/pii.yml"
     filter: "/usr/local/my-collector/filter.yml"
+    summary: "/usr/local/my-collector/summary.yml"
 ```
 
 ### `<unix-domain-socket-pathname>` (Required on Unix)
@@ -117,3 +119,22 @@ generated OTEL telemetry data.  This is optional.  If omitted,
 summary-level telemetry will be emitted.
 
 See [config filter settings](./config-filter-settings.md) for details.
+
+### `<summary-settings-pathname>` (Optional)
+
+The pathname to a `summary.yml` file controlling which trace2 events
+are aggregated into the `trace2.process.summary` attribute on the OTEL
+process span.  This is optional.  If omitted, no aggregated summary
+metrics are emitted.
+
+The summary is emitted at all detail levels (including `dl:summary`),
+making it useful for surfacing aggregated statistics without requiring
+verbose telemetry.
+
+See the [summary example](./Examples/summary_example.yml) for a
+complete example configuration.
+
+To capture specific data event values verbatim (emitted in a separate
+`trace2.process.important_events` span attribute), use the
+`important_events` section of the filter settings.  See
+[config filter settings](./config-filter-settings.md) for details.