Adding Microsoft.Extensions.Telemetry.Abstractions README

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/README.md

@@ -1,6 +1,11 @@
 # Microsoft.Extensions.Telemetry.Abstractions
 
-Common abstractions for high-level telemetry primitives.
+This package contains common abstractions for high-level telemetry primitives. Here are the main features it provides:
+
+- Enhanced Logging Capabilities
+- Log Enrichment
+- Latency Measurement
+- HTTP Request Metadata Handling
 
 ## Install the package
 
@@ -18,6 +23,100 @@ Or directly in the C# project file:
 </ItemGroup>
 ```
 
+## Usage
+
+### Enhanced Logging Capabilities
+
+The package includes a custom logging generator that enhances the default .NET logging capabilities by replacing the default generator. This generator automatically logs the contents of collections and offers advanced logging features, significantly improving the debugging and monitoring process.
+
+```csharp
+[LoggerMessage(1, LogLevel.Information, "These are the contents of my dictionary: {dictionary}")]
+internal static partial void LogMyDictionary(ILogger<Program> logger, Dictionary<int, string> temperature);
+```
+
+It also adds the `LogProperties` attribute which can be applied to a an object parameter of a `LoggerMessage` method. It introspects the passed-in object and automatically adds tags for all its properties. This leads to more informative logs without the need for manual tagging of each property.
+
+```csharp
+[LoggerMessage(1, LogLevel.Information, "Detected a new temperature: {temperature}")]
+internal static partial void LogNewTemperature(ILogger<Program> logger, [LogProperties] Temperature temperature);
+
+internal record Temperature(double value, TemperatureUnit unit);
+```
+
+### Log Enrichment
+
+To enrich your logging data, you can add custom log enrichers to your service collection. This can be done using specific implementations or generic types.
+
+```csharp
+// Using a specific implementation
+builder.services.AddLogEnricher(new CustomLogEnricher());
+
+// Using a generic type
+builder.services.AddLogEnricher<AnotherLogEnricher>();
+```
+
+Create custom log enrichers by implementing the `ILogEnricher` interface.
+
+```csharp
+public class CustomLogEnricher : ILogEnricher
+{
+    public void Enrich(IEnrichmentTagCollector collector)
+    {
+        // Add custom logic to enrich log data
+        collector.Add("CustomTag", "CustomValue");
+    }
+}
+```
+
+### Latency Measurement
+
+To track latency in your application, register checkpoint, measure, and tag names using the provided methods.
+
+```csharp
+builder.services.RegisterCheckpointNames("databaseQuery", "externalApiCall");
+builder.services.RegisterMeasureNames("responseTime", "processingTime");
+builder.services.RegisterTagNames("userId", "transactionId");
+```
+
+Implement the `ILatencyDataExporter` to export latency data. This can be integrated with external systems or logging frameworks.
+
+```csharp
+public class CustomLatencyDataExporter : ILatencyDataExporter
+{
+    public async Task ExportAsync(LatencyData data, CancellationToken cancellationToken)
+    {
+        // Export logic here
+    }
+}
+```
+
+Use the latency context to track performance metrics in your application.
+
+```csharp
+public void YourMethod(ILatencyContextProvider contextProvider)
+{
+    var context = contextProvider.CreateContext();
+    var checkpointToken = context.GetCheckpointToken("databaseQuery");
+
+    // Start measuring
+    context.AddCheckpoint(checkpointToken);
+
+    // Perform operations...
+
+    // End measuring
+    context.AddCheckpoint(checkpointToken);
+
+    // Optionally, record measures and tags
+    context.RecordMeasure(context.GetMeasureToken("responseTime"), measureValue);
+    context.SetTag(context.GetTagToken("userId"), "User123");
+}
+```
+
+### Http Request Metadata Handling
+
+The `IDownstreamDependencyMetadata` interface is designed to capture and store metadata about the downstream dependencies of an HTTP request. This is particularly useful for understanding external service dependencies and their impact on your application's performance and reliability.
+
+The `IOutgoingRequestContext` interface provides a mechanism for associating metadata with outgoing HTTP requests. This allows you to enrich outbound requests with additional information that can be used for logging, telemetry, and analysis.
 
 ## Feedback & Contributing