Need more information on when and how to use this interface

[mtaylorfsmb]

Type of issue

Missing information

Description

This interface appears to be useful for capturing additional information into a structured form usable by structured loggers. But there is no documentation on the actual usage of this interface nor any examples. The only reason I found this is because of the extension method, that is also not well documented, over here.

It would be nice to get some discussion on when this is useful and what to do with it. While I can see where it is possible to add a new enricher, the IEnrichmentTagCollector that enrichers write to doesn't seem to be accessible anywhere else. So if I wanted to use an enricher to add some data to logging then I could create my own enricher. But I don't see any way to later write a logger, or whatever, that then has access to this collection of enriched data.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.http.logging.ihttpclientlogenricher?view=net-9.0-pp

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/Microsoft.Extensions.Http.Logging/IHttpClientLogEnricher.xml

Document Version Independent Id

6a9aad43-d09a-0706-1a59-3c44856344a9

Platform Id

bddae806-f751-afd0-bc13-29d59da12b47

Article author

@dotnet-bot

[tarekgh]

CC @evgenyfedorov2 @geeknoid

[evgenyfedorov2]

It would be nice to get some discussion on when this is useful and what to do with it.

This is useful for creating custom log enricher, as you say below.

While I can see where it is possible to add a new enricher, the IEnrichmentTagCollector that enrichers write to doesn't seem to be accessible anywhere else. So if I wanted to use an enricher to add some data to logging then I could create my own enricher. But I don't see any way to later write a logger, or whatever, that then has access to this collection of enriched data.

If you create a custom enricher, you then register it with IServiceCollection using the extension method, and you don't have to do anything else. The logging infra will call the Enrich method at the right time, extract all information from IEnrichmentTagCollector, and add it to log record's state. As a result, your logs will have the key/value pairs your custom enricher enriched them with.

Does this answer your questions, @mtaylorfsmb ?

[mtaylorfsmb]

@evgenyfedorov2, thank you for the additional information. You have answered part of my question. From the producer side it makes sense that the infrastructure calls the enricher. But what about the consumer side? We have custom loggers that would like access to this data. Where is this collection, or wherever it is ultimately boiled up to, accessible from the logger implementation side?

My point of this report is that this is yet another interface that seems useful but there is literally no documentation about it at all. It seems like someone at MS, or perhaps a partner, had a need for this so it was added. But without any documentation then it seems that nobody other than the requestor and implementers would be able to use it. If this is not designed for us to use then it should probably be marked as infrastructure and can remain undocumented. Otherwise at least a basic set of documentation on how/when to implement the interface and how/when to consume the interface would be useful.

Thanks.

[evgenyfedorov2]

But what about the consumer side? We have custom loggers that would like access to this data. Where is this collection, or wherever it is ultimately boiled up to, accessible from the logger implementation side?

It depends on your use case.

• One example is here https://source.dot.net/#Microsoft.Extensions.Http.Diagnostics/Logging/Internal/HttpClientLogger.cs,42 - enrichers are injected via DI, and then enrichment data attached to log record state https://source.dot.net/#Microsoft.Extensions.Http.Diagnostics/Logging/Internal/HttpClientLogger.cs,238
• If you have a custom logger/logger provider, you normally have access to the TState state which contains all key/value pairs including those added by enrichers, so you can do type-checking for IReadOnlyList<> and enumerate over it

If this is not designed for us to use then it should probably be marked as infrastructure and can remain undocumented.

This is designed to be used mainly on the consumer side. But yes, I can't agree more - we need to do a better job at documenting it.

[mtaylorfsmb]

@evgenyfedorov2 Thank you for the additional information.

[evgenyfedorov2]

cc @mariamgerges