update measures and tags text

Author: rainsxng

docs/core/extensions/httpclient-latency-extensions.md

@@ -14,7 +14,61 @@ The <xref:Microsoft.Extensions.DependencyInjection.HttpClientLatencyTelemetryExt
 extension enables collection of detailed timing information for outgoing HTTP calls with no changes to calling code.
 It plugs into the existing `HttpClientFactory` pipeline to capture stage timings across the request lifecycle, record
 HTTP protocol details, measure garbage collection impact where the runtime exposes that data, and emit a uniform
-telemetry shape suitable for performance analysis and tuning.
+telemetry shape suitable for performance analysis and tuning.Enable them by calling `AddHttpClientLatencyTelemetry()` extension method.
+The built‑in handler creates an `ILatencyContext` per outbound request and populates measures by the time the inner
+pipeline completes. Consume them after `await base.SendAsync(...)` in a later delegating handler (added after telemetry)
+and export to your metrics backend. Example:
+
+Register extension method:
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Http.Diagnostics;
+using Microsoft.Extensions.Hosting;
+
+var builder = Host.CreateApplicationBuilder(args);
+
+// An example of some accessor that is able to read latency context
+builder.Services.AddSingleton<ILatencyContextAccessor, LatencyContextAccessor>();
+
+// Register HTTP client latency telemetry first so its delegating handler runs earlier.
+builder.Services.AddHttpClientLatencyTelemetry();
+
+// Register export handler (runs after telemetry; sees finalized ILatencyContext).
+builder.Services.AddTransient<HttpLatencyExportHandler>();
+
+// Register an HttpClient that will emit and export latency measures.
+builder.Services
+    .AddHttpClient("observed")
+    .AddHttpMessageHandler<HttpLatencyExportHandler>();
+
+var host = builder.Build();
+await host.RunAsync();
+```
+Access the context:
+
+```csharp
+public sealed class HttpLatencyExportHandler : DelegatingHandler
+{
+    // ILatencyContextAccessor is just an example of some accessor that is able to read latency context
+    private readonly ILatencyContextAccessor _latency;
+
+    public HttpLatencyExportHandler(ILatencyContextAccessor latency) => _latency = latency;
+
+    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
+    {
+        var rsp = await base.SendAsync(request, ct).ConfigureAwait(false);
+
+        var ctx = _latency.Current;
+        if (ctx != null)
+        {
+            var data = ctx.LatencyData;
+            // Record/export gc and conn with version as a dimension here.
+        }
+        return rsp;
+    }
+}
+```
 
 ### [.NET CLI](#tab/dotnet-cli)
 
@@ -96,10 +150,16 @@ Timestamps are recorded for key stages of the HTTP request lifecycle:
 
 #### Measures (platform dependent)
 
-Measures are numeric values captured during a request that quantify things your timestamp checkpoints alone
-don't show - like how long GC pauses stalled the thread or how often a brand-new connection had to be opened instead of
-reusing a pooled one. Use them when total latency is higher than the sum of visible phases, when investigating memory
-pressure or connection churn, or when tuning pooling and allocation patterns.
+Measures quantify latency contributors that raw phase checkpoints cannot (GC pause overlap, connection churn, other
+accumulated counts or durations). They are collected in an in‑memory latency context created when you call
+`AddHttpClientLatencyTelemetry()`. Nothing is emitted automatically: the context simply accumulates checkpoints, measures,
+and tags until the request completes. If you also enable HTTP client logging enrichment with `AddExtendedHttpClientLogging()`,
+the completed context is flattened into a single structured log field named `LatencyInfo` (version marker, server name if available, then tag, checkpoint, and measure name/value sequences).
+
+That log field is the only built‑in output artifact; no metrics or traces are produced unless you add your own exporter.
+To surface them as metrics, read the context after the request pipeline returns and record (for example) GC pause overlap
+to a histogram and connection initiations to a counter, optionally dimensioned by protocol version.
+
 
 | Name                     | Description                                                             |
 |--------------------------|-------------------------------------------------------------------------|
@@ -108,17 +168,29 @@ pressure or connection churn, or when tuning pooling and allocation patterns.
 
 #### Tags
 
-Use tags to attach stable categorical dimensions to each request so you can segment, filter, and aggregate metrics and
-logs without reprocessing raw data. They carry classification (not duration) and remain low‑cardinality by design.
+Use tags to attach stable categorical dimensions to each request so you can segment, filter, and aggregate metrics
+and logs without reprocessing raw data. They are low‑cardinality classification labels (not timings) captured
+in the latency context and, if HTTP client log enrichment is enabled, serialized into a single LatencyInfo log field.
+Enable enrichment at application startup by adding the logging extension (for all clients or per client) along with
+latency telemetry, for example:
+
+```csharp
+var builder = Host.CreateApplicationBuilder(args);
+builder.Services.AddHttpClientLatencyTelemetry(); // enables latency context + measures/tags
+builder.Services.AddExtendedHttpClientLogging();
+var app = builder.Build();
+```
+
+After this, outbound requests logged through the structured logging pipeline will include the `LatencyInfo` property
+containing the flattened tags, checkpoints, and measures. No metrics or traces are emitted automatically for tags;
+export them yourself (e.g., turn tag values into metric dimensions or `Activity` tags) if you need them outside logs.
 
 | Tag          | Description                                                     |
 |--------------|-----------------------------------------------------------------|
 | Http.Version | HTTP protocol version negotiated/used (for example, 1.1, 2, 3). |
 
 ## Usage example
 
-### Track HTTP request client latency
-
 These components enable tracking and reporting the latency of HTTP client request processing.
 
 You can register the services using the following methods: