Logs: Scope improvements

[CodeBlanch]

Issue 1: Scopes + Batching

There is an issue in the current scope API where if you capture a LogRecord, say for batching, the active scopes may have changed by the time the exporter runs.

• LogRecord.BufferLogScopes has been introduced to copy the active scopes into a buffer which can be inspected outside of the log lifecycle. This is now used by the BatchLogRecordExportProcessor. Made opt-in because a processor like SimpleLogRecordExportProcessor doesn't need the buffering and can use the ForEachScope call directly in the allocation-free form provided by the .NET API. LogRecord.ScopeProvider is now cleared after Processor.OnEnd is called to prevent accidental misuse.

Issue 2: Working with Scopes

• The API today exposes the ability to loop over the scopes as objects. To be slightly more helpful we also now expose an enumerator which will return the individual KeyValuePair<string, object>s inside each scope. This makes it more aligned with the state parsing mechanism already in there. Can be done without allocation.

Usage Example

Sub-item Enumeration:

                logRecord.ForEachScope(ProcessScopeItem, this);

                static void ProcessScopeItem(LogRecordScope scope, ConsoleLogRecordExporter exporter)
                {
                    foreach (KeyValuePair<string, object> scopeItem in scope)
                    {
                        exporter.WriteLine($"[Scope]:{scopeItem.Key.PadRight(RightPaddingLength)}{scopeItem.Value}");
                    }
                }

API Changes

// Existing
public sealed class LogRecord
{
   // Signature changed.
   public void ForEachScope<TState>(Action<LogRecordScope, TState> callback, TState state);
}

// New
public readonly struct LogRecordScope
{
        public object Scope { get; }

        public Enumerator GetEnumerator() => new Enumerator(this.Scope);

        // For enumerating sub-items on the scope.
        public struct Enumerator : IEnumerator<KeyValuePair<string, object>>
}

TODOs

• Unit tests.
• CHANGELOG.md updated for non-trivial changes
• Changes in public API reviewed

[codecov]

Codecov Report

Merging #2026 (e3c5ecd) into main (c28efc3) will decrease coverage by 0.05%.
The diff coverage is 85.45%.

@@            Coverage Diff             @@
##             main    #2026      +/-   ##
==========================================
- Coverage   83.90%   83.84%   -0.06%     
==========================================
  Files         192      193       +1     
  Lines        6195     6247      +52     
==========================================
+ Hits         5198     5238      +40     
- Misses        997     1009      +12     

Impacted Files	Coverage Δ
src/OpenTelemetry/BatchLogRecordExportProcessor.cs	0.00% <0.00%> (ø)
src/OpenTelemetry/Logs/LogRecordScope.cs	82.60% <82.60%> (ø)
src/OpenTelemetry/Logs/LogRecord.cs	93.84% <96.42%> (+1.34%)	⬆️
src/OpenTelemetry/Logs/OpenTelemetryLogger.cs	94.11% <100.00%> (+0.17%)	⬆️
...rc/OpenTelemetry/SimpleLogRecordExportProcessor.cs	0.00% <0.00%> (-100.00%)	⬇️
...lemetry/Internal/SelfDiagnosticsConfigRefresher.cs	86.91% <0.00%> (-2.81%)	⬇️
...ZPages/Implementation/ZPagesExporterEventSource.cs	62.50% <0.00%> (+6.25%)	⬆️

[CodeBlanch]

Updates based on SIG discussion today:

• BufferLogScopes is now internal.
• Removed depth tracking from LogRecordScope.
• Made LogRecordScope readonly struct instead of readonly ref struct and removed the delegate.

[reyang]

LGTM.

[cijothomas]

Thanks!