Merge pull request #148 from serilog/dev

4.0.0 Release

Author: nblumhardt

.github/.DS_Store

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report a bug and help us to improve Serilog.Sinks.OpenTelemetry
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+The Serilog maintainers want you to have a great experience using Serilog.Sinks.OpenTelemetry, and will happily track down and resolve bugs. We all have limited time, though, so please think through all of the factors that might be involved and include as much useful information as possible 😊.
+
+ℹ If the problem is caused by a sink or other extension package, please track down the correct repository for that package and create the report there: this tracker is for the **Serilog.Sinks.OpenTelemetry** package only.
+
+**Description**
+What's going wrong?
+
+**Reproduction**
+Please provide code samples showing how you're configuring and calling Serilog to produce the behavior.
+
+**Expected behavior**
+A concise description of what you expected to happen.
+
+**Relevant package, tooling and runtime versions**
+Which package versions are you using, on what platform?
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,4 @@
+contact_links:
+  - name: Ask for help
+    url: https://github.com/serilog/serilog/wiki/Usage-help
+    about: Ask the community for help on how to use Serilog

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an improvement to Serilog.Sinks.OpenTelemetry
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. `When [...], it would be great if [...]`.
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -397,3 +397,5 @@ FodyWeavers.xsd
 # JetBrains Rider
 *.sln.iml
 /test/Serilog.Sinks.OpenTelemetry.Tests/PublicApiVisibilityTests.received.txt
+
+.DS_Store

.gitignore

@@ -38,8 +38,9 @@ examples below.
 
 ## Configuration
 
-This sink supports two configuration styles: inline and options. The
-inline configuration looks like:
+This sink supports two configuration styles: inline and options.
+Inline configuration is appropriate for simple, local logging
+setups, and looks like:
 
 ```csharp
 Log.Logger = new LoggerConfiguration()
@@ -49,10 +50,7 @@ Log.Logger = new LoggerConfiguration()
     .CreateLogger();
 ```
 
-This configuration is appropriate only for simple, local logging 
-setups.
-
-More complicated use cases will need to use the options
+More complicated use cases need to use options-style
 configuration, which looks like:
 
 ```csharp
@@ -63,35 +61,28 @@ Log.Logger = new LoggerConfiguration()
         options.Protocol = OtlpProtocol.HttpProtobuf;
     })
     .CreateLogger();
-
 ```
 
 This supports the sink's full set of configuration options. See the
 `OpenTelemetrySinkOptions.cs` file for the full set of options. 
-Some of the more imporant parameters are discussed in the following
+Some of the more important parameters are discussed in the following
 sections.
 
 ### Endpoint and protocol
 
-The default endpoint is `http://localhost:4317`, which will send
-logs to an OpenTelemetry collector running on the same machine over
-the gRPC protocol. This is appropriate for testing or for using a 
-local OpenTelemetry collector as a proxy for a downstream logging service.
+The default endpoint and protocol are `http://localhost:4317` and `OtlpProtocol.Grpc`.
 
-In most production scenarios, you will want to set an endpoint. To do so,
-add the `endpoint` argument to the `WriteTo.OpenTelemetry()` call.
+In most production scenarios, you'll need to set an endpoint and protocol to suit your
+deployment environment. To do so, add the `endpoint` argument to the `WriteTo.OpenTelemetry()` call.
 
-You may also want to set the protocol explicitly. The supported values
+You may also want to set the protocol. The supported values
 are:
 
 - `OtlpProtocol.Grpc`: Sends a protobuf representation of the 
    OpenTelemetry Logs over a gRPC connection (the default).
 - `OtlpProtocol.HttpProtobuf`: Sends a protobuf representation of the
    OpenTelemetry Logs over an HTTP connection.
 
-When the `OtlpProtocol.HttpProtobuf` option is specified, the endpoint
-URL **must** include the full path, for example `http://localhost:4318/v1/logs`.
-
 ### Resource attributes
 
 OpenTelemetry logs may contain a "resource" that provides metadata concerning
@@ -126,6 +117,15 @@ Log.Logger = new LoggerConfiguration()
     .CreateLogger();
 ```
 
+### Environment variable overrides
+
+The sink also recognizes a selection of the `OTEL_OTLP_EXPORTER_*` environment variables described in
+the [OpenTelemetry documentation](https://opentelemetry.io/docs/specs/otel/protocol/exporter/), and will
+override programmatic configuration with any environment variable values present at runtime.
+
+To switch off this behavior, pass `ignoreEnvironment: true` to the `WriteTo.OpenTelemetry()` configuration
+methods.
+
 ## Serilog `LogEvent` to OpenTelemetry log record mapping
 
 The following table provides the mapping between the Serilog log 
@@ -165,6 +165,24 @@ Log.Logger = new LoggerConfiguration()
 The example shows the default value; `IncludedData.MessageTemplateMD5HashAttribute` can
 also be used to add the MD5 hash of the message template.
 
+## Sending traces through the sink
+
+Serilog `LogEvents` that carry a `SpanStartTimestamp` property of type `DateTime` will be
+recognized as spans by this sink, and sent using the appropriate OpenTelemetry endpoint
+and schema. The properties recognized by the sink match the ones emitted by
+[SerilogTracing](https://github.com/serilog-tracing/serilog-tracing).
+
+In addition to the field mapping performed for log records, events that represent trace
+spans can carry the special properties listed below.
+
+Serilog `LogEvent`               | OpenTelemetry `Span` | Comments                               |
+---------------------------------|----------------------|----------------------------------------| 
+`MessageTemplate`                | `Name`               |                                        |
+`Properties["ParentSpanId"]` | `ParentSpanId`       | Value must be of type `ActivitySpanId` |
+`Properties["SpanKind"]` | `Kind`               | Value must be of type `ActivityKind`   |
+`Properties["SpanStartTimestamp"]` | `StartTimeUnixNano`  | Value must be of type `DateTime`; .NET provides 100-nanosecond precision     |
+`Timestamp`                | `EndTimeUnixNano`    | .NET provides 100-nanosecond precision |
+
 ## Example
 
 The `example/Example` subdirectory contains an example application that logs

README.md

@@ -12,13 +12,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// ReSharper disable once RedundantUsingDirective
 using System.Net.Http;
-using Serilog.Configuration;
-using Serilog.Sinks.OpenTelemetry;
-using Serilog.Sinks.OpenTelemetry.Exporters;
+
 using Serilog.Collections;
+using Serilog.Configuration;
 using Serilog.Core;
 using Serilog.Events;
+using Serilog.Sinks.OpenTelemetry;
+using Serilog.Sinks.OpenTelemetry.Configuration;
+using Serilog.Sinks.OpenTelemetry.Exporters;
+// ReSharper disable MemberCanBePrivate.Global
 
 namespace Serilog;
 
@@ -27,42 +31,72 @@ namespace Serilog;
 /// </summary>
 public static class OpenTelemetryLoggerConfigurationExtensions
 {
+    // ReSharper disable once ReturnTypeCanBeNotNullable
     static HttpMessageHandler? CreateDefaultHttpMessageHandler() =>
 #if FEATURE_SOCKETS_HTTP_HANDLER
         new SocketsHttpHandler { ActivityHeadersPropagator = null };
 #else
         null;
 #endif
-    
+
     /// <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="ignoreEnvironment">If false the configuration will be overridden with values
+    /// from the <see href="https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/">OTLP Exporter
+    /// Configuration environment variables</see>, if present.</param>
     public static LoggerConfiguration OpenTelemetry(
         this LoggerSinkConfiguration loggerSinkConfiguration,
-        Action<BatchedOpenTelemetrySinkOptions> configure)
+        Action<BatchedOpenTelemetrySinkOptions> configure,
+        bool ignoreEnvironment = false)
     {
         if (configure == null) throw new ArgumentNullException(nameof(configure));
 
         var options = new BatchedOpenTelemetrySinkOptions();
         configure(options);
 
+        if (!ignoreEnvironment)
+        {
+            OpenTelemetryEnvironment.Configure(options, Environment.GetEnvironmentVariable);
+        }
+
         var exporter = Exporter.Create(
-            endpoint: options.Endpoint,
+            logsEndpoint: options.LogsEndpoint,
+            tracesEndpoint: options.TracesEndpoint,
             protocol: options.Protocol,
             headers: new Dictionary<string, string>(options.Headers),
             httpMessageHandler: options.HttpMessageHandler ?? CreateDefaultHttpMessageHandler());
 
-        var openTelemetrySink = new OpenTelemetrySink(
-            exporter: exporter,
-            formatProvider: options.FormatProvider,
-            resourceAttributes: new Dictionary<string, object>(options.ResourceAttributes),
-            includedData: options.IncludedData);
+        ILogEventSink? logsSink = null, tracesSink = null;
+
+        if (options.LogsEndpoint != null)
+        {
+            var openTelemetryLogsSink = new OpenTelemetryLogsSink(
+                exporter: exporter,
+                formatProvider: options.FormatProvider,
+                resourceAttributes: new Dictionary<string, object>(options.ResourceAttributes),
+                includedData: options.IncludedData);
 
-        return loggerSinkConfiguration.Sink(openTelemetrySink, options.BatchingOptions, options.RestrictedToMinimumLevel, options.LevelSwitch);
+            logsSink = LoggerSinkConfiguration.CreateSink(wt => wt.Sink(openTelemetryLogsSink, options.BatchingOptions));
+        }
+
+        if (options.TracesEndpoint != null)
+        {
+            var openTelemetryTracesSink = new OpenTelemetryTracesSink(
+                exporter: exporter,
+                resourceAttributes: new Dictionary<string, object>(options.ResourceAttributes),
+                includedData: options.IncludedData);
+
+            tracesSink = LoggerSinkConfiguration.CreateSink(wt => wt.Sink(openTelemetryTracesSink, options.BatchingOptions));
+        }
+
+        var sink = new OpenTelemetrySink(exporter, logsSink, tracesSink);
+
+        return loggerSinkConfiguration.Sink(sink, options.RestrictedToMinimumLevel, options.LevelSwitch);
     }
 
     /// <summary>
@@ -117,7 +151,7 @@ public static LoggerConfiguration OpenTelemetry(
             resourceAttributes?.AddTo(options.ResourceAttributes);
         });
     }
-    
+
     /// <summary>
     /// Audit to an OTLP exporter, waiting for each event to be acknowledged, and propagating errors to the caller.
     /// </summary>
@@ -132,20 +166,35 @@ public static LoggerConfiguration OpenTelemetry(
         if (configure == null) throw new ArgumentNullException(nameof(configure));
 
         var options = new OpenTelemetrySinkOptions();
-        
         configure(options);
 
         var exporter = Exporter.Create(
-            endpoint: options.Endpoint,
+            logsEndpoint: options.LogsEndpoint,
+            tracesEndpoint: options.TracesEndpoint,
             protocol: options.Protocol,
             headers: new Dictionary<string, string>(options.Headers),
             httpMessageHandler: options.HttpMessageHandler ?? CreateDefaultHttpMessageHandler());
 
-        var sink = new OpenTelemetrySink(
-            exporter: exporter,
-            formatProvider: options.FormatProvider,
-            resourceAttributes: new Dictionary<string, object>(options.ResourceAttributes),
-            includedData: options.IncludedData);
+        ILogEventSink? logsSink = null, tracesSink = null;
+
+        if (options.LogsEndpoint != null)
+        {
+            logsSink = new OpenTelemetryLogsSink(
+                exporter: exporter,
+                formatProvider: options.FormatProvider,
+                resourceAttributes: new Dictionary<string, object>(options.ResourceAttributes),
+                includedData: options.IncludedData);
+        }
+
+        if (options.TracesEndpoint != null)
+        {
+            tracesSink = new OpenTelemetryTracesSink(
+                exporter: exporter,
+                resourceAttributes: new Dictionary<string, object>(options.ResourceAttributes),
+                includedData: options.IncludedData);
+        }
+
+        var sink = new OpenTelemetrySink(exporter, logsSink, tracesSink);
 
         return loggerAuditSinkConfiguration.Sink(sink, options.RestrictedToMinimumLevel, options.LevelSwitch);
     }