HTTP Tracking Setup

HTTP tracking is the core mechanism that captures all HTTP traffic for diagram generation. There are two sides to track:

1. Outgoing calls from the SUT — Calls your API makes to its downstream dependencies
2. Incoming calls to the SUT — Calls your test makes to the API under test

Deprecation (v2.28.1): CallingServiceName has been renamed to CallerName across all options classes. The old property still works but produces a compile warning. Update your code to use CallerName — the old name will be removed in a future major version.

This page covers the basic setup using TrackDependenciesForDiagrams() and the options reference. If your project uses named clients, typed clients, existing DelegatingHandler chains, or other advanced HttpClient patterns, see Tracking Dependencies for a step-by-step guide covering every common pattern.

Inside your WebApplicationFactory configuration, register tracking for outgoing calls from the SUT:

Simplified imports (v2.0.131+): TrackDependenciesForDiagrams() and CreateTestTrackingClient() are now available directly from the core Kronikol namespace. You can use using Kronikol; instead of a framework-specific namespace — the core extensions accept the base TestTrackingMessageHandlerOptions type, so any framework-specific options class works.

builder.ConfigureServices(services =>
{
    services.TrackDependenciesForDiagrams(
        new XUnitTestTrackingMessageHandlerOptions
        {
            CallerName = "My API",
            PortsToServiceNames =
            {
                { 80, "My API" },
                { 5001, "Auth Service" },
                { 5002, "Payment Service" }
            }
        });
});

This registers:

• TestTrackingMessageHandlerOptions as a singleton
• IHttpContextAccessor for extracting tracking headers from incoming requests
• IHttpMessageHandlerBuilderFilter as TrackingHttpMessageHandlerBuilderFilter (automatically injects the tracking DelegatingHandler into every HttpClient built by IHttpClientFactory)

ClientNamesToServiceNames uses a tiered resolution strategy (v3.0.23+):

1. Exact match — The full client name is looked up as a dictionary key
2. EndsWith with boundary — If the client name (stripped of assembly qualification) ends with a key, and the preceding character is non-alphanumeric (e.g. +, ., -), the match succeeds
3. Contains (assembly-qualified names only) — For Refit v9 and other source generators that produce assembly-qualified client names (containing , ), a case-sensitive Contains check is used as a final fallback

The Contains fallback is restricted to assembly-qualified names to prevent false positives on simple names (e.g. key "Client" should not match "MyBetterClient").

For typed HttpClients registered via services.AddHttpClient<TClient>(), IHttpClientFactory uses the full type name as the client name. For example:

// Registration:
services.AddHttpClient<TenantHierarchyHttpClient>(o => o.BaseAddress = ...);

// In IHttpMessageHandlerBuilderFilter.Configure(), builder.Name = "TenantHierarchyHttpClient"
// So the dictionary key must be exactly "TenantHierarchyHttpClient":
ClientNamesToServiceNames =
{
    { "TenantHierarchyHttpClient", "Tenant Hierarchy Service" }  // ✅ exact match
    // { "TenantHierarchyService", "Tenant Hierarchy Service" }  // ❌ won't match
}

For named HttpClients registered via services.AddHttpClient("my-client"), the key is the string you passed.

Refit / source-generated clients (v3.0.21+): Refit and other source generators produce complex client names. For Refit v8-style names like Refit.Implementation.Generated+SomeModule+IIntelligenceAiApiClient, ends-with matching works (the + is a valid boundary). For Refit v9 assembly-qualified names like ...IntelligenceAiIIntelligenceAiApiClient, Data.Insights.Api, Version=1.0.0.0, ..., the contains fallback matches:

ClientNamesToServiceNames =
{
    { "IIntelligenceAiApiClient", "Intelligence AI" }  // ✅ matches both Refit v8 (EndsWith) and v9 (Contains)
}

Diagnostic tip (v2.28.12+): When DiagnosticMode=true, the diagnostic report includes an Unmatched HTTP Client Names section that lists all clientName values that didn't match any ClientNamesToServiceNames key (neither exact nor ends-with), along with request counts. This makes misconfigured mappings immediately visible.

Framework-specific options classes (XUnitTestTrackingMessageHandlerOptions, NUnitTestTrackingMessageHandlerOptions, BDDfyTestTrackingMessageHandlerOptions, LightBddTestTrackingMessageHandlerOptions, ReqNRollTestTrackingMessageHandlerOptions) extend TestTrackingMessageHandlerOptions and auto-populate CurrentTestInfoFetcher from the framework's test context. Each framework package also provides a CurrentTestInfo static class with a Fetcher property — use CurrentTestInfo.Fetcher when you need to set CurrentTestInfoFetcher on extension options.

⚠️ Startup HTTP calls: XUnitTestTrackingMessageHandlerOptions (and XUnit2TestTrackingMessageHandlerOptions) set CurrentTestInfoFetcher to read from the test context. If your SUT makes HTTP calls during startup — e.g. hosted services fetching configuration, health checks, warm-up requests — the fetcher will execute when no test is active. CurrentTestInfo.Fetcher throws InvalidOperationException when no test is running (since v2.28.22; xUnit v2's and NUnit's since 4.13.1). The tracking handler catches it and sends the startup call untracked, without test headers, unless a TestIdentityScope or TestIdentityScope.GlobalFallback names a test (it goes to that test) or RequestResponseLogger.CaptureBackground is on (it is kept as a background call, under the unknown identity). Tests still pass and diagrams for actual tests are unaffected.

If you want explicit control, use the base TestTrackingMessageHandlerOptions with CurrentTestInfo.Fetcher:

services.TrackDependenciesForDiagrams(new TestTrackingMessageHandlerOptions
{
    CallerName = "My API",
    PortsToServiceNames = { { 80, "My API" }, { 5001, "Auth Service" } },
    CurrentTestInfoFetcher = CurrentTestInfo.Fetcher,
});

See also: Tracking Dependencies — Gotcha: HTTP Calls During HttpClient Construction for a related pitfall when HTTP calls are made during HttpClient construction (not just app startup).

A send that throws (a refused connection, a broken response body, HttpClient's timeout surfacing as a TaskCanceledException) is logged as a response whose status is the exception's type behind a bang, !HttpRequestException, with the message chain in error (3.18.0); the exception is rethrown untouched. The fingerprint the history reads names it (GET /asyncapi/v1.json !HttpRequestException), the diagram draws the return with the message in the note on it (5.35.0), kronikol query http <report> s3/i1 prints the message under the status (the address of the response half, which holds it: s3/i0 is the request), and from 4.3.0 Failures.md prints it under the calls table and kronikol export sends the call as an ERROR span with it as the message. Before 3.18.0 the request stood alone with no reason, which hid every first attempt a retry loop swallowed. FailedSend.Status and FailedSend.Describe are public for any other capturer.

From 5.34.3 every Kronikol tracker answers a call that throws this way (#232): the AWS handlers, the Atlas Data API, Redis, the Google and Azure storage handlers when a response body breaks off as it is read, the brokers, the SQL family and EF Core (a cancelled command among them), Spanner, gRPC, MongoDB, Elasticsearch and TrackingProxy. A tracker whose service gives a status of its own keeps it, with the reason in error: the SQL family and Spanner answer Error, MassTransit draws a Fault call, and Kafka answers its error code (!Local_MsgTimedOut). Before, many of them left the request alone.

Not all dependencies use IHttpClientFactory. For dependencies with their own HTTP internals:

• Azure Cosmos DB SDK — Uses its own HttpClient internally. Use Kronikol.Extensions.CosmosDB which provides CosmosTrackingMessageHandler. See Integration CosmosDB Extension.
• EF Core / Relational databases — EF Core uses ADO.NET DbCommand internally, not HttpClient. Use Kronikol.Extensions.EfCore.Relational which provides SqlTrackingInterceptor — a DbCommandInterceptor that classifies SQL operations and shows them as Select: /ordersdb/Users, Insert: /ordersdb/Orders, etc. Works with SQL Server, PostgreSQL, MySQL, SQLite, Oracle, and Spanner. See Integration EF Core Relational Extension.
• gRPC services — gRPC clients use GrpcChannel, not IHttpClientFactory. Use Kronikol.Extensions.Grpc which provides GrpcTrackingInterceptor for outgoing calls, GrpcTrackingChannel.Create() for incoming (test → SUT) calls, and AddTrackedGrpcClient<TClient>() for DI-based registration (v2.26.0+). Produces protobuf-aware labels like SayHello: grpc:///greet.Greeter/SayHello instead of raw HTTP/2 binary traffic. AddTrackedGrpcClient<T>() and CreateTestTrackingGrpcClient auto-resolve IHttpContextAccessor from DI so test identity flows through for SUT → downstream calls. See Integration Grpc Extension for the full setup guide.
• Non-HTTP interactions (Kafka, Service Bus, etc.) — Use MessageTracker. See Event & Message Tracking.

To track incoming calls from the test to the SUT, create the test's HttpClient via the CreateTestTrackingClient() extension method:

HttpClient client = factory.CreateTestTrackingClient(
    new XUnitTestTrackingMessageHandlerOptions
    {
        FixedNameForReceivingService = "My API"
    });

This is a convenience method equivalent to:

var client = factory.CreateDefaultClient(new TestTrackingMessageHandler(options));

It wraps the WebApplicationFactory's HttpClient in a TestTrackingMessageHandler so that all calls from the test to the SUT appear in the diagrams.

Parallel tests sharing one factory (5.6.1+). CreateTestTrackingClient() makes its client under a lock of the factory's own, as every framework package's CreateTestTrackingClient() and the gRPC extension's CreateTestTrackingGrpcClient() do, so tests running in parallel can share one factory and make their clients from it at the same moment, as a Reqnroll suite's features do in their [BeforeScenario] hooks. WebApplicationFactory has no lock of its own there: before 5.6.1, the first clients made at once each started a copy of the application, and a client made at the same moment as another could be lost from the factory's list of clients or leave a null in it, so the factory's Dispose threw NullReferenceException. A client you make with the factory's own CreateClient() while tests run is outside that lock: start the factory before the tests run (factory.StartServer() in a run-start hook) and make such clients one at a time.

If your test suite already has custom DelegatingHandlers on the test-to-SUT client (e.g. a handler that waits for background processing to complete after each request), use the overload that accepts additional handlers:

HttpClient client = factory.CreateTestTrackingClient(
    new XUnitTestTrackingMessageHandlerOptions
    {
        FixedNameForReceivingService = "My API"
    },
    new MyBackgroundWorkHandler(),
    new MyRetryHandler());

This is equivalent to manually calling CreateDefaultClient with the tracking handler first:

var trackingHandler = new TestTrackingMessageHandler(
    new XUnit2TestTrackingMessageHandlerOptions
    {
        FixedNameForReceivingService = "My API"
    });

HttpClient client = factory.CreateDefaultClient(trackingHandler, new MyBackgroundWorkHandler());

Ordering: The tracking handler is always placed first (outermost) so it captures the full request/response including any modifications made by subsequent handlers.

For more complex handler chaining scenarios (named clients, typed clients, existing DelegatingHandler chains, IHttpMessageHandlerBuilderFilter, etc.), see Tracking Dependencies which covers 8 common patterns in detail.

When your SUT processes a request inside WebApplicationFactory, the code runs on the server's thread pool — not on the test thread. This means AsyncLocal<T>-based test context (used by xUnit, NUnit, LightBDD, ReqNRoll, etc.) is not available inside the SUT's request pipeline.

This affects all tracking extensions that run inside the pipeline. For example, if your API produces a Kafka message, writes to Cosmos DB, or logs to Redis as part of handling a request, the extension's CurrentTestInfoFetcher delegate will throw an exception (caught internally by TestInfoResolver, so tests still pass — but unless a TestIdentityScope or the global fallback names the test, the operation is not logged at all, or with RequestResponseLogger.CaptureBackground on is kept as a background call under the unknown identity, and won't appear in diagrams).

The standard HTTP tracking (TestTrackingMessageHandler) never had this problem because it propagates test identity via HTTP headers (test-tracking-current-test-name, test-tracking-current-test-id) on the incoming request. But non-HTTP extensions (Kafka, Cosmos DB, Redis, EF Core, Service Bus, etc.) had no way to read those headers — until now.

Starting in v2.23.0, all 22 tracking extensions accept an optional IHttpContextAccessor? httpContextAccessor parameter in their constructors. When provided, the extension uses dual-resolution to determine the current test identity:

1. Try HTTP headers first — If an HttpContext is available (meaning the code is running inside a request pipeline), read test-tracking-current-test-name and test-tracking-current-test-id from the request headers
2. Fall back to the delegate — If no HttpContext is available, or its request carries no tracking headers (e.g. the code is running directly on the test thread), use CurrentTestInfoFetcher as before

This is fully backward-compatible. The httpContextAccessor parameter defaults to null, and all existing code continues to work unchanged.

Every extension options class with a CurrentTestInfoFetcher has an HttpContextAccessor property (the TcpTap, ProxyTap and OTLP taps take neither): most since v2.26.3, MongoDB's since 4.10.0, and Kafka's, Bigtable's, Spanner's, MediatR's and EF Core's (SqlTrackingInterceptorOptions) since 4.11.0. Convenience methods, DI extensions, and CreateTestTrackingClient() auto-resolve IHttpContextAccessor from DI when available — no manual wiring needed for the standard setup paths:

builder.ConfigureTestServices(services =>
{
    // TrackDependenciesForDiagrams() registers IHttpContextAccessor automatically
    services.TrackDependenciesForDiagrams(new XUnitTestTrackingMessageHandlerOptions { ... });

    // ServiceBus — AddServiceBusTestTracking auto-resolves IHttpContextAccessor from DI
    services.AddServiceBusTestTracking(new ServiceBusTrackingOptions
    {
        ServiceName = "ServiceBus",
        CallerName = "My API",
        CurrentTestInfoFetcher = CurrentTestInfo.Fetcher
    });

    // gRPC — AddTrackedGrpcClient auto-resolves IHttpContextAccessor from DI
    services.AddTrackedGrpcClient<MyGrpcClient>(handler, uri, opts => { ... });
});

If you construct trackers manually (not via DI extensions), you can set HttpContextAccessor on the options:

builder.ConfigureTestServices(services =>
{
    services.AddHttpContextAccessor();

    services.AddSingleton(sp =>
    {
        var options = new KafkaTrackingOptions
        {
            ServiceName = "Kafka",
            CallerName = "My API",
            CurrentTestInfoFetcher = CurrentTestInfo.Fetcher,
            HttpContextAccessor = sp.GetRequiredService<IHttpContextAccessor>()
        };
        return new KafkaTracker(options);
    });
});

The constructor httpContextAccessor parameter still works and takes precedence over the options property. KafkaTrackingOptions.HttpContextAccessor is 4.11.0+; before it, pass the accessor to the constructor: new KafkaTracker(options, accessor).

All DI extensions and convenience methods auto-resolve IHttpContextAccessor from the service provider when it's available in DI. This covers:

• Core: CreateTestTrackingClient() (both overloads)
• ServiceBus: AddServiceBusTestTracking()
• gRPC: AddTrackedGrpcClient<TClient>(), CreateTestTrackingGrpcClient()
• MediatR: TrackMediatorForDiagrams() (auto-resolved since v2.23.0)
• All other extensions: Set HttpContextAccessor on the options class — the tracker reads it via ?? options.HttpContextAccessor (BigQuery's and Pub/Sub's trackers since 4.18.2)

You need dual-resolution (via auto-resolve or manual HttpContextAccessor) if all of these are true:

1. Your extension tracker runs inside the SUT's request pipeline (not on the test thread)
2. The SUT is hosted via WebApplicationFactory (in-process)
3. You're using CreateTestTrackingClient() or manually adding TestTrackingMessageHandler on the test-to-SUT client, or (4.13.0+) a gRPC test client from CreateTestTrackingGrpcClient or GrpcTrackingChannel (each propagates the headers)

If your extension only runs on the test thread (e.g. in [BeforeScenario] / [AfterScenario] hooks, or in step definitions that call the SDK directly without going through the SUT), the delegate alone is sufficient.

A host that registers AddTestTrackingContextPropagation() resolves the scenario without an accessor: its middleware begins a TestIdentityScope from the headers of each request it serves, so a tracker in the pipeline whose fetcher cannot see the test resolves through that scope (attribution Scope, where the accessor gives RequestHeader), and a TestTrackingMessageHandler without an accessor passes that identity on. The accessor adds what the scope cannot: the request's Kronikol trace id, which the HTTP handler, the gRPC interceptor and MessageTracker reuse so kronikol query flow can nest their calls under the request by trace id, and the headers HeadersToForward copies.

Note: If you register trackers manually via services.AddSingleton(sp => new XxxTracker(options, sp.GetService<IHttpContextAccessor>())), the explicit constructor parameter takes precedence over the options property.

All extensions delegate to TestInfoResolver.Resolve(httpContextAccessor, currentTestInfoFetcher) (or ResolveWithSource, which also says which step answered), which tries, in order:

1. The request the host is serving: when httpContextAccessor?.HttpContext?.Request carries both test-tracking-current-test-name and test-tracking-current-test-id, their values, decoded (HTTP Tracking Setup › Header values).
2. In a flow detached from the test (TestIdentityScope.Detach(); AddTestTrackingContextPropagation() detaches a host's hosted services), only an explicit TestIdentityScope or the scenario whose document the flow is working on; otherwise the call is background.
3. The CurrentTestInfoFetcher delegate, with its exceptions caught, unless it answers the unknown id.
4. TestIdentityScope.Current: the scope the middleware AddTestTrackingContextPropagation() installs begins for each request that carries the headers, or one the test began.
5. TestIdentityScope.GlobalFallback.
6. Nothing: null, so the operation is not logged, unless RequestResponseLogger.CaptureBackground is on, when it is logged as background (Unknown).

All 22 tracking extensions support the optional IHttpContextAccessor parameter as of v2.23.0. v2.26.3+: options classes expose an HttpContextAccessor property (MongoDB's from 4.10.0; Kafka's, Bigtable's, Spanner's, MediatR's and EF Core's (SqlTrackingInterceptorOptions) from 4.11.0), and convenience methods / DI extensions auto-resolve it from DI:

When using JustEat.HttpClientInterception for HTTP mocking, you need a custom IHttpMessageHandlerBuilderFilter to insert TestTrackingMessageHandler before the interception handler:

public class HttpClientInterceptionFilter(
    HttpClientInterceptorOptions options,
    IServiceProvider serviceProvider,
    TestTrackingMessageHandlerOptions? trackingOptions = null) : IHttpMessageHandlerBuilderFilter
{
    public Action<HttpMessageHandlerBuilder> Configure(Action<HttpMessageHandlerBuilder> next) =>
        builder =>
        {
            next(builder);

            string? serviceName = null;
            if (trackingOptions is not null && !string.IsNullOrEmpty(builder.Name))
            {
                var match = trackingOptions.ClientNamesToServiceNames
                    .FirstOrDefault(kvp => builder.Name.Contains(kvp.Key, StringComparison.OrdinalIgnoreCase));
                serviceName = match.Value;
            }

            if (serviceName is not null)
            {
                var httpContextAccessor = serviceProvider.GetRequiredService<IHttpContextAccessor>();
                builder.PrimaryHandler = new TestTrackingMessageHandler(
                    new TestTrackingMessageHandlerOptions
                    {
                        CallerName = trackingOptions!.CallerName,
                        FixedNameForReceivingService = serviceName,
                        CurrentTestInfoFetcher = trackingOptions.CurrentTestInfoFetcher,
                    },
                    httpContextAccessor)
                {
                    InnerHandler = new MockHttpMessageHandler(options)
                    {
                        InnerHandler = builder.PrimaryHandler
                    }
                };
            }
            else
            {
                builder.AdditionalHandlers.Add(options.CreateHttpMessageHandler());
            }
        };
}

The MockHttpMessageHandler wrapper handles GetResponseAsync properly as a DelegatingHandler:

public class MockHttpMessageHandler(HttpClientInterceptorOptions options) : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var response = await options.GetResponseAsync(request, cancellationToken);
        if (response is not null) return response;
        if (options.ThrowOnMissingRegistration)
            throw new HttpRequestNotInterceptedException(
                $"No HTTP response configured for {request.Method} {request.RequestUri}.", request);
        return await base.SendAsync(request, cancellationToken);
    }
}

Register in ConfigureTestServices:

services.AddSingleton<IHttpMessageHandlerBuilderFilter>(sp =>
    new HttpClientInterceptionFilter(interceptorOptions, sp, trackingOptions));

Common mistake — _ => vs sp =>: Using _ => discards the service provider, leaving IHttpContextAccessor null. Always use sp => and resolve IHttpContextAccessor from it. See Dual-Resolution Test Identity (v2.23.0+).

When combining TestTrackingMessageHandler with test faking (JustEat.HttpClientInterception, WireMock, or custom handlers), the handler chain ordering is critical:

┌─────────────────────────────────────┐
│ HttpClient                          │
├─────────────────────────────────────┤
│ TestTrackingMessageHandler          │  ← Records request + response
│   InnerHandler ─┐                   │
│                 ▼                    │
│ InterceptionHandler                 │  ← Returns fake response
│   InnerHandler ─┐                   │
│                 ▼                    │
│ PrimaryHandler (HttpClientHandler)  │  ← Never reached (intercepted)
└─────────────────────────────────────┘

The tracking handler must be outermost — it wraps the interception handler, not the reverse. This way:

1. Request flows through TestTrackingMessageHandler (recorded)
2. Then through the interception handler (fake response returned)
3. Response flows back through TestTrackingMessageHandler (recorded)

When implementing IHttpMessageHandlerBuilderFilter, replace PrimaryHandler with the tracking handler chained to the interceptor:

// ❌ Wrong: AdditionalHandlers runs after PrimaryHandler interception
builder.AdditionalHandlers.Add(trackingHandler);

// ✅ Correct: tracking wraps interception as the primary handler
var interceptionHandler = _interceptor.CreateHttpMessageHandler();
interceptionHandler.InnerHandler = builder.PrimaryHandler;

builder.PrimaryHandler = new TestTrackingMessageHandler(options, httpContextAccessor)
{
    InnerHandler = interceptionHandler
};

TestTrackingMessageHandler needs IHttpContextAccessor for dual-resolution of test identity. This must be resolved from DI at handler creation time, not at registration time:

// ❌ Wrong: HttpContextAccessor resolved at registration — HttpContext will be null
services.AddSingleton<IHttpMessageHandlerBuilderFilter>(_ =>
    new MyFilter(new HttpContextAccessor()));

// ✅ Correct: resolved from service provider at filter creation time
services.AddSingleton<IHttpMessageHandlerBuilderFilter>(sp =>
    new MyFilter(sp));

CreateTestTrackingClient() is the primary entry point for tracking inbound HTTP requests (test → SUT). It:

1. Creates an HttpClient targeting the in-memory test server
2. Inserts a TestTrackingMessageHandler as the outermost handler
3. Auto-injects test-tracking-current-test-name, test-tracking-current-test-id, test-tracking-trace-id and test-tracking-caller-name headers into every request it tracks, each only when the request lacks it. The call is logged with the test-tracking-trace-id the request carries, such as one you set or a first attempt's when a retry sends the message again (4.16.1; before, it was logged with another)
4. (v2.26.3+) Auto-resolves IHttpContextAccessor from DI
5. (5.6.1+) Makes the client under a lock of the factory's own, so tests running in parallel can share the factory (Parallel tests sharing one factory)

These headers are how the SUT's internal tracking (CosmosDB, Redis, Service Bus, etc.) correlates operations back to the originating test.

A test name, test id or caller name that is plain printable ASCII, neither begins nor ends with a space and does not begin with UTF-8'' is sent as it is. Any other value is sent in the RFC 8187 form that Content-Disposition: filename*= uses: UTF-8'' followed by the value's UTF-8 bytes, percent-encoded, so Café order travels as UTF-8''Caf%C3%A9%20order. That covers a name with an accent, an emoji or a line feed, an xUnit v3 theory whose long string argument xUnit shortened with ···, and an MSTest id naming a method with a non-ASCII letter.

Every Kronikol reader decodes the form: the middleware AddTestTrackingContextPropagation() installs, the dual resolution described above, MessageTracker, ProxyTap, and TestTrackingServerBridge.GetCurrentTestInfo(accessor), which is the way to read the identity in your own code. The handler, the gRPC interceptor (4.13.0+), ProxyTap and Playwright's ToHeaders() write it. Until 4.12.1 such a value failed the request over a real socket ("Request headers must contain only ASCII characters"), a line feed failed it in memory too, and ProxyTap and Playwright sent ? for each such character.

When you write the headers yourself, encode the same way:

static string HeaderValue(string value) =>
    value.All(c => c is >= ' ' and <= '~') && !value.StartsWith("UTF-8''") && value.Trim(' ') == value
        ? value
        : "UTF-8''" + Uri.EscapeDataString(value);

FixedNameForReceivingService sets the target service name in diagrams. It should match the CallerName used in outbound tracking options:

// Inbound: "Caller" → "My Service"
var client = factory.CreateTestTrackingClient(new XUnitTestTrackingMessageHandlerOptions
{
    FixedNameForReceivingService = "My Service"
});

// Outbound: "My Service" → "Downstream A"
services.TrackDependenciesForDiagrams(new XUnitTestTrackingMessageHandlerOptions
{
    CallerName = "My Service",  // Must match FixedNameForReceivingService above
    ClientNamesToServiceNames = { { "DownstreamAClient", "Downstream A" } }
});

One client per collection: Create one tracked client per test collection (not per test). The client is thread-safe and Kronikol headers are injected per-request based on the current test context.