[API Proposal]: Simpler, neater and more memorable contextual logging

[lonix1]

Background and motivation

One can use ILogger to enrich log events with extra data:

using (_logger.BeginScope(new Dictionary<string, object?>
  {
    { "Foo", "abc" },
    { "Bar", 123 },
    { "Baz", true }
})) {
  _logger.LogInformation("Process returned {Result}", 42);
  _logger.LogInformation("Process returned {Result}", 43);
}

That is horrible, and hard to remember. That syntax must be used even to enrich a single log event.

For a single log event, Serilog's syntax is a pleasure:

_logger
  .ForContext("Foo", "abc")
  .ForContext("Bar", 123)
  .ForContext("Baz", true)
  .LogInformation("Process returned {Result}", 42);

...And that makes it easy to remember and use.

API Proposal

Unsure.

Maybe:

public static ILogger Enrich(this ILogger logger, string key, object? value);

Or:

public static ILogger Enrich(this ILogger logger, params (string, object?)[] properties);

However those contextual properties should only apply to the next log event. So like I said, I'm unsure what the signatures should look like. Maybe something new is required.

API Usage

A compromise between MEL and Serilog syntax:

For a single log event:

_logger
  .Enrich("Foo", "abc")
  .Enrich("Bar", 123)
  .Enrich("Baz", true)
  .LogInformation("Process returned {Result}", 42);

For multiple log events: either the same as we have now, or:

using (_logger.Enrich(
    ("Foo", "abc"),
    ("Bar", 123),
    ("Baz", true)
  )) {
  _logger.LogInformation("Process returned {Result}", 42);
  _logger.LogInformation("Process returned {Result}", 43);
}

Alternative Designs

I posted some workarounds on StackOverflow, which are much nicer. But they're still not as good as what could be done within the runtime. Some syntactic sugar would be great.

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-logging
See info in area-owners.md if you want to be subscribed.

[julealgon]

I feel like leveraging the new enrichment extension point from Microsoft.Extensions.Telemetry solves most of the issues I personally had with this pattern, as a ton of that stuff is contextual data that can be added with one or many enricher implementations the same way that it can be done with Serilog.

For the few cases where I need to add inline data, it would be nice to have a simpler syntax though, so I'm not opposed to this proposal.

[tarekgh]

@geeknoid @evgenyfedorov2 @joperezr Could you look into this and determine if it can be implemented using the Enrichment feature in the extensions? Is there a way to achieve this with the current model? Or you consider adding this feature there?

[geeknoid]

The enrichment model we provide is considerably more powerful and general purpose in nature. There is a chain of enrichers which can supplement log records with either static information (like cluster id for example) or with dynamic per-request state. It's a different logical model than what is proposed here however.

[tarekgh]

Thanks @geeknoid, does it make sense to consider the proposal here for potential support?

[geeknoid]

I don't think the proposal provides enough bang-for-the-buck, given the existence of the bigger enrichment story.

[tarekgh]

Thanks, @lonix1, for your suggestions. After discussion, we have decided not to pursue this proposal at this time. However, we will monitor for increased demand for similar proposals and may reconsider our decision in the future.

[julealgon]

@geeknoid so for very localized, non-contextual additional data, you suggest log scopes with dictionaries to be the go-to way to do those still? Would that be correct?

I ask because not all types of data can be injected using a singleton or a scoped enricher. Sometimes, there is data that is very local to a deeply nested method in the call graph that you still want to instrument in a block of child logger calls.

I do use log scopes for that in a similar way than what was presented here but was wondering if you would recommend a different strategy.

[geeknoid]

@julealgon My perspective on scopes is that they are a somewhat orphaned feature, and if logging was to be reimplemented in >NET, this feature probably wouldn't exist.

Across Microsoft, I've seen very very little use of scopes in real production contexts. Lexical scoping is often not the right model, especially in the face of async work. Most scenarios simply don't need this, or you end up lugging around your own bag of state for those specialized cases.