Document EnrichmentLogProcessor more comprehensively open-telemetry#3266 (comment)

Author: stefanobaghino

examples/logs-advanced/src/main.rs

@@ -57,6 +57,42 @@ fn main() {
     let _ = provider.shutdown();
 }
 
+/// A log processor that enriches log records with additional attributes before
+/// delegating to an underlying processor.
+///
+/// # Why Wrapping Instead of Chaining?
+///
+/// If this were implemented as a standalone processor in a chain (e.g.,
+/// EnrichmentProcessor -> SimpleLogProcessor), the performance benefits of the
+/// `event_enabled` check would be nullified. Here's why:
+///
+/// - The `event_enabled` method is crucial for performance - it allows processors
+///   to skip expensive operations for logs that will ultimately be filtered out
+/// - A standalone EnrichmentProcessor would need to implement `event_enabled`,
+///   but it has no knowledge of downstream filtering logic
+/// - It would have to return `true` by default, causing unnecessary enrichment
+///   work even for logs that the downstream processor will discard
+///
+/// By wrapping the underlying processor, we ensure that:
+///
+/// 1. **Performance**: The wrapped processor makes the authoritative decision
+///    about whether a log should be processed via `event_enabled`
+/// 2. **Correctness**: All filtering logic from the underlying processor is
+///    properly honored without duplication
+/// 3. **Transparency**: The enrichment is applied only when logs will actually
+///    be processed, avoiding waste
+///
+/// ## Delegation Requirements
+///
+/// Because this processor wraps another, it **must delegate all trait methods**
+/// to the underlying processor, including:
+/// - `shutdown_with_timeout` / `shutdown` - For proper resource cleanup
+/// - `set_resource` - To propagate resource information
+/// - `force_flush` - To ensure data consistency
+/// - `event_enabled` - To maintain filtering logic
+///
+/// This ensures the underlying processor receives all necessary lifecycle events
+/// and configuration updates.
 #[derive(Debug)]
 pub struct EnrichmentLogProcessor<P: LogProcessor> {
     /// The wrapped processor that will receive enriched log records
@@ -93,11 +129,6 @@ impl<P: LogProcessor> LogProcessor for EnrichmentLogProcessor<P> {
 
     #[cfg(feature = "spec_unstable_logs_enabled")]
     fn event_enabled(&self, level: Severity, target: &str, name: Option<&str>) -> bool {
-        // It is important to call the delegate's event_enabled method to ensure that
-        // any filtering or logic implemented by downstream processors is respected so
-        // that no unnecessary work is done, causing an unwanted performance issue.
-        // Skipping this call could result in logs being emitted that should have been filtered out
-        // or in bypassing other custom logic in the processor chain.
         self.delegate.event_enabled(level, target, name)
     }
 }