[sdk-logs] Introduce OpenTelemetryLoggingBuilder (proposal 4)

[CodeBlanch]

Relates to #4433
Relates to #4502

Changes

• Introduce OpenTelemetryLoggingBuilder as the thing returned by the ILoggingBuilder.AddOpenTelemetry extension
• Introduce LoggerProviderBuilder.ConfigureLoggerOptions extension for configuring OpenTelemetryLoggerOptions

Details

Today we configure logging like this:

appBuilder.Logging.AddOpenTelemetry(options =>
{
   options.IncludeFormattedMessage = true;
   options.AddConsoleExporter();
});

"options" is OpenTelemetryLoggerOptions class.

Now the OpenTelemetry Specification has LoggerProvider and we have a LoggerProviderBuilder API. The SDK LoggerProvider is fed into the ILogger integration (OpenTelemetryLoggerProvider).

There are different ways we could approach this. Today we have extensions for logging that target OpenTelemetryLoggerOptions. We will need to target LoggerProviderBuilder now. We could forever have two versions of every extension, but that seems lame.

This PR is adding a new class OpenTelemetryLoggingBuilder to try and bridge the two worlds. Previously the ILoggingBuilder.AddOpenTelemetry extension returned the ILoggingBuilder passed into the call. Now it returns OpenTelemetryLoggingBuilder which implements ILoggingBuilder. This shouldn't be a source breaking change. It may be a binary breaking change, need to investigate that. OpenTelemetryLoggerOptions.AddProcessor and OpenTelemetryLoggerOptions.SetResourceBuilder methods would be obsoleted as would our existing extensions on OpenTelemetryLoggerOptions.

All of these styles can be interchanged.

// Configure OTel via ILoggingBuilder
appBuilder.Logging
   .AddOpenTelemetry(options=> options.IncludeFormattedMessage = true)
   .AddConsoleExporter();

// Configure OTel via OpenTelemetryBuilder
appBuilder.Services
   .AddOpenTelemetry()
   .WithLogging(builder => builder
      .ConfigureLoggerOptions(options => options.IncludeFormattedMessage = true)
      .AddConsoleExporter());

// Configure OTel via OpenTelemetryBuilder
appBuilder.Services
   .AddOpenTelemetry()
   .WithLogging(builder => builder.AddConsoleExporter());

// Configure ILogger options via Options API
appBuilder.Services.Configure<OpenTelemetryLoggerOptions>(options => options.IncludeFormattedMessage = true);

// Configure OTel via ILoggingBuilder
appBuilder.Logging
   .AddOpenTelemetry().AddConsoleExporter());

// Configure ILogger options via Options API
appBuilder.Services.Configure<OpenTelemetryLoggerOptions>(options => options.IncludeFormattedMessage = true);

Considerations

Today you can do this:

appBuilder.Logging.AddOpenTelemetry().AddEventSource();

Which is to chain calls on the ILoggerBuilder.

The signature of OpenTelemetryLoggingBuilder has OpenTelemetryLoggingBuilder : LoggerProviderBuilder, ILoggingBuilder. The reason for implementing ILoggingBuilder is so that the above code does not break on upgrade.

If users update their code like this...

appBuilder.Logging
   .AddOpenTelemetry().AddConsoleExporter()
   .AddEventSource(); // This won't compile because AddConsoleExporter breaks the chain

Basically they will have to reorder things.

appBuilder.Logging
   .AddEventSource()
   .AddOpenTelemetry().AddConsoleExporter();

Or

appBuilder.Logging.AddOpenTelemetry().AddConsoleExporter();
appBuilder.Logging.AddEventSource()   

Merge requirement checklist

• CONTRIBUTING guidelines followed (nullable enabled, static analysis, etc.)
• Unit tests added/updated

[noahfalk]

It may be a binary breaking change, need to investigate that

It is : ) https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md#signatures

✗ Disallowed

Changing the type of a property, field, parameter or return value

[github-actions]

This PR was marked stale due to lack of activity and will be closed in 7 days. Commenting or Pushing will instruct the bot to automatically remove the label. This bot runs once per day.

[github-actions]

Closed as inactive. Feel free to reopen if this PR is still being worked on.