Merge pull request #150 from nblumhardt/suppress-instrumentation-scope

Provide a hook to call `OpenTelemetry.SuppressInstrumentationScope.Begin`

Author: nblumhardt

README.md

@@ -183,6 +183,20 @@ Serilog `LogEvent`               | OpenTelemetry `Span` | Comments
 `Properties["SpanStartTimestamp"]` | `StartTimeUnixNano`  | Value must be of type `DateTime`; .NET provides 100-nanosecond precision     |
 `Timestamp`                | `EndTimeUnixNano`    | .NET provides 100-nanosecond precision |
 
+## Suppressing other instrumentation
+
+If the sink is used in an application that also instruments HTTP or gRPC requests using the OpenTelemetry libraries,
+this can be suppressed for outbound requests made by the sink using `OnBeginSuppressInstrumentation`:
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .WriteTo.OpenTelemetry(options =>
+    {
+        options.OnBeginSuppressInstrumentation =
+            OpenTelemetry.SuppressInstrumentationScope.Begin;
+        // ...
+```
+
 ## Example
 
 The `example/Example` subdirectory contains an example application that logs

src/Serilog.Sinks.OpenTelemetry/.DS_Store

@@ -43,7 +43,7 @@ public static class OpenTelemetryLoggerConfigurationExtensions
     /// Send log events to an OTLP exporter.
     /// </summary>
     /// <param name="loggerSinkConfiguration">
-    /// The `WriteTo` configuration object.
+    /// The <c>WriteTo</c> configuration object.
     /// </param>
     /// <param name="configure">The configuration callback.</param>
     /// <param name="ignoreEnvironment">If false the configuration will be overridden with values
@@ -69,7 +69,10 @@ public static LoggerConfiguration OpenTelemetry(
             tracesEndpoint: options.TracesEndpoint,
             protocol: options.Protocol,
             headers: new Dictionary<string, string>(options.Headers),
-            httpMessageHandler: options.HttpMessageHandler ?? CreateDefaultHttpMessageHandler());
+            httpMessageHandler: options.HttpMessageHandler ?? CreateDefaultHttpMessageHandler(),
+            onBeginSuppressInstrumentation: options.OnBeginSuppressInstrumentation != null ?
+                () => options.OnBeginSuppressInstrumentation(true)
+                : null);
 
         ILogEventSink? logsSink = null, tracesSink = null;
 
@@ -103,7 +106,7 @@ public static LoggerConfiguration OpenTelemetry(
     /// Send log events to an OTLP exporter.
     /// </summary>
     /// <param name="loggerSinkConfiguration">
-    /// The `WriteTo` configuration object.
+    /// The <c>WriteTo</c> configuration object.
     /// </param>
     /// <param name="endpoint">
     /// The full URL of the OTLP exporter endpoint.
@@ -156,7 +159,7 @@ public static LoggerConfiguration OpenTelemetry(
     /// Audit to an OTLP exporter, waiting for each event to be acknowledged, and propagating errors to the caller.
     /// </summary>
     /// <param name="loggerAuditSinkConfiguration">
-    /// The `AuditTo` configuration object.
+    /// The <c>AuditTo</c> configuration object.
     /// </param>
     /// <param name="configure">The configuration callback.</param>
     public static LoggerConfiguration OpenTelemetry(
@@ -173,7 +176,10 @@ public static LoggerConfiguration OpenTelemetry(
             tracesEndpoint: options.TracesEndpoint,
             protocol: options.Protocol,
             headers: new Dictionary<string, string>(options.Headers),
-            httpMessageHandler: options.HttpMessageHandler ?? CreateDefaultHttpMessageHandler());
+            httpMessageHandler: options.HttpMessageHandler ?? CreateDefaultHttpMessageHandler(),
+            onBeginSuppressInstrumentation: options.OnBeginSuppressInstrumentation != null ?
+                () => options.OnBeginSuppressInstrumentation(true)
+                : null);
 
         ILogEventSink? logsSink = null, tracesSink = null;
 

src/Serilog.Sinks.OpenTelemetry/OpenTelemetryLoggerConfigurationExtensions.cs

@@ -2,7 +2,7 @@
     <PropertyGroup>
         <Description>This Serilog sink transforms Serilog events into OpenTelemetry
             logs and sends them to an OTLP (gRPC or HTTP) endpoint.</Description>
-        <VersionPrefix>4.0.1</VersionPrefix>
+        <VersionPrefix>4.1.0</VersionPrefix>
         <Authors>Serilog Contributors</Authors>
         <!-- .NET Framework version targeting is frozen at these two TFMs. -->
         <TargetFrameworks Condition=" '$(OS)' == 'Windows_NT'">net471;net462</TargetFrameworks>

src/Serilog.Sinks.OpenTelemetry/Serilog.Sinks.OpenTelemetry.csproj

@@ -21,13 +21,18 @@ public static IExporter Create(
         string? tracesEndpoint,
         OtlpProtocol protocol,
         IReadOnlyDictionary<string, string> headers,
-        HttpMessageHandler? httpMessageHandler)
+        HttpMessageHandler? httpMessageHandler,
+        Func<IDisposable>? onBeginSuppressInstrumentation)
     {
-        return protocol switch
+        var exporter = protocol switch
         {
-            OtlpProtocol.HttpProtobuf => new HttpExporter(logsEndpoint, tracesEndpoint, headers, httpMessageHandler),
+            OtlpProtocol.HttpProtobuf => (IExporter)new HttpExporter(logsEndpoint, tracesEndpoint, headers, httpMessageHandler),
             OtlpProtocol.Grpc => new GrpcExporter(logsEndpoint, tracesEndpoint, headers, httpMessageHandler),
             _ => throw new NotSupportedException($"OTLP protocol {protocol} is unsupported.")
         };
+
+        return onBeginSuppressInstrumentation != null
+            ? new InstrumentationSuppressingExporter(exporter, onBeginSuppressInstrumentation)
+            : exporter;
     }
-}
+}

src/Serilog.Sinks.OpenTelemetry/Sinks/OpenTelemetry/Exporters/Exporter.cs

@@ -0,0 +1,70 @@
+// Copyright © Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using OpenTelemetry.Proto.Collector.Logs.V1;
+using OpenTelemetry.Proto.Collector.Trace.V1;
+
+namespace Serilog.Sinks.OpenTelemetry.Exporters;
+
+/// <summary>
+/// Uses a callback to suppress instrumentation while telemetry is being exported by the wrapped exporter.
+/// </summary>
+sealed class InstrumentationSuppressingExporter : IExporter, IDisposable
+{
+    readonly IExporter _exporter;
+    readonly Func<IDisposable> _onBeginSuppressInstrumentation;
+
+    public InstrumentationSuppressingExporter(IExporter exporter, Func<IDisposable> onBeginSuppressInstrumentation)
+    {
+        _exporter = exporter;
+        _onBeginSuppressInstrumentation = onBeginSuppressInstrumentation;
+    }
+
+    public void Export(ExportLogsServiceRequest request)
+    {
+        using (_onBeginSuppressInstrumentation())
+        {
+            _exporter.Export(request);
+        }
+    }
+
+    public async Task ExportAsync(ExportLogsServiceRequest request)
+    {
+        using (_onBeginSuppressInstrumentation())
+        {
+            await _exporter.ExportAsync(request);
+        }
+    }
+
+    public void Export(ExportTraceServiceRequest request)
+    {
+        using (_onBeginSuppressInstrumentation())
+        {
+            _exporter.Export(request);
+        }
+    }
+
+    public async Task ExportAsync(ExportTraceServiceRequest request)
+    {
+        using (_onBeginSuppressInstrumentation())
+        {
+            await _exporter.ExportAsync(request);
+        }
+    }
+
+    public void Dispose()
+    {
+        (_exporter as IDisposable)?.Dispose();
+    }
+}

src/Serilog.Sinks.OpenTelemetry/Sinks/OpenTelemetry/Exporters/InstrumentationSuppressingExporter.cs

@@ -158,4 +158,16 @@ public string? TracesEndpoint
     /// to be changed at runtime.
     /// </summary>
     public LoggingLevelSwitch? LevelSwitch { get; set; }
+    
+    /// <summary>
+    /// A callback used by the sink before triggering behaviors that may themselves generate log or trace information.
+    /// Set this value to <c>OpenTelemetry.SuppressInstrumentationScope.Begin</c> when using this sink in applications
+    /// that instrument HTTP or gRPC requests using OpenTelemetry.
+    /// </summary>
+    /// <example>
+    /// options.OnBeginSuppressInstrumentation = OpenTelemetry.SuppressInstrumentationScope.Begin;
+    /// </example>
+    /// <remarks>This callback accepts a <c langword="bool"/> in order to match the signature of the OpenTelemetry SDK method
+    /// that is typically assigned to it. The sink always provides the callback with the value <c langword="true" />.</remarks>
+    public Func<bool, IDisposable>? OnBeginSuppressInstrumentation { get; set; }
 }

src/Serilog.Sinks.OpenTelemetry/Sinks/OpenTelemetry/OpenTelemetrySinkOptions.cs

@@ -0,0 +1,24 @@
+using OpenTelemetry.Proto.Collector.Logs.V1;
+using Serilog.Sinks.OpenTelemetry.Exporters;
+using Serilog.Sinks.OpenTelemetry.Tests.Support;
+using Xunit;
+
+namespace Serilog.Sinks.OpenTelemetry.Tests;
+
+public class InstrumentationSuppressingExporterTests
+{
+    [Fact]
+    public void RequestsAreNotInstrumentedWhenSuppressed()
+    {
+        var exporter = new CollectingExporter();
+        
+        exporter.Export(new ExportLogsServiceRequest());
+        Assert.Equal(1, exporter.InstrumentedRequestCount);
+        Assert.Single(exporter.ExportLogsServiceRequests);
+
+        var wrapper = new InstrumentationSuppressingExporter(exporter, TestSuppressInstrumentationScope.Begin);
+        wrapper.Export(new ExportLogsServiceRequest());
+        Assert.Equal(1, exporter.InstrumentedRequestCount);
+        Assert.Equal(2, exporter.ExportLogsServiceRequests.Count);
+    }
+}

test/Serilog.Sinks.OpenTelemetry.Tests/InstrumentationSuppressingExporterTests.cs

@@ -38,6 +38,7 @@ namespace Serilog.Sinks.OpenTelemetry
         public Serilog.Sinks.OpenTelemetry.IncludedData IncludedData { get; set; }
         public Serilog.Core.LoggingLevelSwitch? LevelSwitch { get; set; }
         public string? LogsEndpoint { get; set; }
+        public System.Func<bool, System.IDisposable>? OnBeginSuppressInstrumentation { get; set; }
         public Serilog.Sinks.OpenTelemetry.OtlpProtocol Protocol { get; set; }
         public System.Collections.Generic.IDictionary<string, object> ResourceAttributes { get; set; }
         public Serilog.Events.LogEventLevel RestrictedToMinimumLevel { get; set; }

test/Serilog.Sinks.OpenTelemetry.Tests/PublicApiVisibilityTests.approved.txt

@@ -5,28 +5,33 @@ namespace Serilog.Sinks.OpenTelemetry.Tests.Support;
 
 class CollectingExporter: IExporter
 {
+    public int InstrumentedRequestCount { get; private set; }
     public List<ExportLogsServiceRequest> ExportLogsServiceRequests { get; } = new();
     public List<ExportTraceServiceRequest> ExportTraceServiceRequests { get; } = new();
 
     public void Export(ExportLogsServiceRequest request)
     {
+        if (!TestSuppressInstrumentationScope.IsSuppressed) InstrumentedRequestCount++;
         ExportLogsServiceRequests.Add(request);
     }
 
     public Task ExportAsync(ExportLogsServiceRequest request)
     {
+        if (!TestSuppressInstrumentationScope.IsSuppressed) InstrumentedRequestCount++;
         Export(request);
         return Task.CompletedTask;
     }
 
     public void Export(ExportTraceServiceRequest request)
     {
+        if (!TestSuppressInstrumentationScope.IsSuppressed) InstrumentedRequestCount++;
         ExportTraceServiceRequests.Add(request);
     }
 
     public Task ExportAsync(ExportTraceServiceRequest request)
     {
+        if (!TestSuppressInstrumentationScope.IsSuppressed) InstrumentedRequestCount++;
         Export(request);
         return Task.CompletedTask;
     }
-}
+}