Merge pull request #153 from serilog/dev

4.1.0 Release

Author: nblumhardt

README.md

@@ -45,7 +45,7 @@ setups, and looks like:
 ```csharp
 Log.Logger = new LoggerConfiguration()
     .WriteTo.OpenTelemetry(
-        endpoint: "http://127.0.0.1:4318/v1/logs",
+        endpoint: "http://127.0.0.1:4318",
         protocol: OtlpProtocol.HttpProtobuf)
     .CreateLogger();
 ```
@@ -57,7 +57,7 @@ configuration, which looks like:
 Log.Logger = new LoggerConfiguration()
     .WriteTo.OpenTelemetry(options =>
     {
-        options.Endpoint = "http://127.0.0.1:4318/v1/logs";
+        options.Endpoint = "http://127.0.0.1:4318";
         options.Protocol = OtlpProtocol.HttpProtobuf;
     })
     .CreateLogger();
@@ -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

example/Example/Program.cs

@@ -63,7 +63,7 @@ static void SendLogs(ILogger logger, string protocol)
 static Logger CreateLogger(OtlpProtocol protocol)
 {
     var endpoint = protocol == OtlpProtocol.HttpProtobuf ?
-        "http://localhost:4318/v1/logs" :
+        "http://localhost:4318" :
         "http://localhost:4317";
 
     return new LoggerConfiguration()

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
@@ -54,22 +54,46 @@ public static LoggerConfiguration OpenTelemetry(
         Action<BatchedOpenTelemetrySinkOptions> configure,
         bool ignoreEnvironment = false)
     {
+        return loggerSinkConfiguration.OpenTelemetry(
+            configure,
+            ignoreEnvironment ? null : Environment.GetEnvironmentVariable
+        );
+    }
+
+    /// <summary>
+    /// Send log events to an OTLP exporter.
+    /// </summary>
+    /// <param name="loggerSinkConfiguration">
+    /// The `WriteTo` configuration object.
+    /// </param>
+    /// <param name="configure">The configuration callback.</param>
+    /// <param name="getConfigurationVariable">Provides <see href="https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/">OTLP Exporter
+    /// Configuration variables</see> that will override other options when present.</param>
+    public static LoggerConfiguration OpenTelemetry(
+        this LoggerSinkConfiguration loggerSinkConfiguration,
+        Action<BatchedOpenTelemetrySinkOptions> configure,
+        Func<string, string?>? getConfigurationVariable)
+    {
+        if (loggerSinkConfiguration == null) throw new ArgumentNullException(nameof(loggerSinkConfiguration));
         if (configure == null) throw new ArgumentNullException(nameof(configure));
 
         var options = new BatchedOpenTelemetrySinkOptions();
         configure(options);
 
-        if (!ignoreEnvironment)
+        if (getConfigurationVariable != null)
         {
-            OpenTelemetryEnvironment.Configure(options, Environment.GetEnvironmentVariable);
+            OpenTelemetryEnvironment.Configure(options, getConfigurationVariable);
         }
 
         var exporter = Exporter.Create(
             logsEndpoint: options.LogsEndpoint,
             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 +127,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 +180,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 +197,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.0</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

@@ -22,23 +22,23 @@ static class OpenTelemetryEnvironment
     const string ResourceAttributesVarName = "OTEL_RESOURCE_ATTRIBUTES";
     const string ServiceNameVarName = "OTEL_SERVICE_NAME";
 
-    public static void Configure(BatchedOpenTelemetrySinkOptions options, Func<string, string?> getEnvironmentVariable)
+    public static void Configure(BatchedOpenTelemetrySinkOptions options, Func<string, string?> getConfigurationVariable)
     {
-        options.Protocol = getEnvironmentVariable(ProtocolVarName) switch
+        options.Protocol = getConfigurationVariable(ProtocolVarName) switch
         {
             "http/protobuf" => OtlpProtocol.HttpProtobuf,
             "grpc" => OtlpProtocol.Grpc,
             _ => options.Protocol
         };
 
-        if (getEnvironmentVariable(EndpointVarName) is { Length: > 1 } endpoint)
+        if (getConfigurationVariable(EndpointVarName) is { Length: > 1 } endpoint)
             options.Endpoint = endpoint;
 
-        FillHeadersIfPresent(getEnvironmentVariable(HeaderVarName), options.Headers);
+        FillHeadersIfPresent(getConfigurationVariable(HeaderVarName), options.Headers);
 
-        FillHeadersResourceAttributesIfPresent(getEnvironmentVariable(ResourceAttributesVarName), options.ResourceAttributes);
+        FillHeadersResourceAttributesIfPresent(getConfigurationVariable(ResourceAttributesVarName), options.ResourceAttributes);
 
-        if (getEnvironmentVariable(ServiceNameVarName) is { Length: > 1 } serviceName)
+        if (getConfigurationVariable(ServiceNameVarName) is { Length: > 1 } serviceName)
         {
             options.ResourceAttributes[SemanticConventions.AttributeServiceName] = serviceName;
         }

src/Serilog.Sinks.OpenTelemetry/Sinks/OpenTelemetry/Configuration/OpenTelemetryEnvironment.cs

@@ -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);
+    }
+}