Diagnostics and Debugging

Diagnostics and Debugging

TestTrackingDiagrams includes several diagnostic tools to help you understand what's being tracked, identify configuration issues, and debug missing or unexpected diagram content.

---

Diagnostic Mode

Enable DiagnosticMode on ReportConfigurationOptions to generate a comprehensive DiagnosticReport.html alongside your normal reports:

var options = new ReportConfigurationOptions
{
    DiagnosticMode = true // generates DiagnosticReport.html
};

The diagnostic report includes:

Section	Contents
Configuration Dump	All ReportConfigurationOptions values, including InternalFlow settings
Log Counts by Service	Number of request/response logs per ServiceName
Log Counts by Test	Number of logs per test, sorted descending — highlights tests with zero logs
Unpaired Requests	Request logs without matching responses (same TraceId + RequestResponseId)
Orphaned Test IDs	Test IDs in logs that don't match any Feature/Scenario
Scenarios with No Logs	Scenarios that ran but produced zero logged interactions
Activity Source Discovery	All detected ActivitySource names from captured OTel spans, with span counts and tracked/well-known status

Tip: Enable DiagnosticMode temporarily during development to identify why diagrams are missing content — unpaired logs, orphaned IDs, or missing activity sources are the most common root causes.

---

Report Diagnostics

ReportDiagnostics.Analyse() runs automatically at report generation time and produces warning strings that appear in the report footer. Common warnings include:

• "No request/response logs recorded" — No interactions were tracked. Check that TestTrackingMessageHandler is wired up.
• "N test(s) have no request/response logs" — Some scenarios didn't produce any HTTP interactions.
• "InternalFlowSpanStore contains 0 spans" — No OTel spans were captured. Check that the activity listener is running.

When ActivitySourceDiscovery is enabled on ReportConfigurationOptions, the diagnostics additionally list all discovered activity sources with their span counts:

var options = new ReportConfigurationOptions
{
    ActivitySourceDiscovery = true // includes source discovery in diagnostics
};

---

Activity Source Discovery

ActivitySourceDiscovery.GetDiscoveredSources() returns a dictionary of all ActivitySource names that produced spans during the test run, with their span counts:

var sources = ActivitySourceDiscovery.GetDiscoveredSources();
// e.g. { "Microsoft.AspNetCore": 42, "System.Net.Http": 38, "MyApi.Services": 15 }

This is useful for:

• Identifying which sources are producing spans — Helps you decide which to include/exclude via InternalFlowSpanGranularity and InternalFlowActivitySources.
• Verifying custom sources are being captured — If your custom ActivitySource doesn't appear, check that InternalFlowActivitySources includes its name.
• Understanding span volume — High span counts from a single source may indicate noisy instrumentation that could be filtered.

---

InternalFlowSpanStore.Complete()

When creating manual spans (e.g. inside a TrackingProxy or custom tracking code), use InternalFlowSpanStore.Complete(activity) as a one-liner to stop and store the span:

var activity = new ActivitySource("MySource").StartActivity("MyOperation");
try
{
    // ... do work ...
}
finally
{
    InternalFlowSpanStore.Complete(activity);
}

Complete() is null-safe — it does nothing if the activity is null. If the activity hasn't been stopped, it calls Stop() before adding it to the store.

---

Empty Diagram Diagnostics

When InternalFlowNoDataBehavior is set to ShowMessage (the default), segments with no captured spans show an enriched diagnostic message instead of a generic "No data" notice. The message includes:

• The current InternalFlowSpanGranularity setting
• The configured InternalFlowActivitySources (if Manual granularity)
• A count of total spans in the InternalFlowSpanStore
• Actionable suggestions (e.g. "Try switching to Full granularity", "Check that your activity sources are listed")

This makes it much easier to diagnose why a particular popup has no internal flow content.

---

RequestResponseLogger.LogPair()

LogPair() is a convenience method that logs a matched request/response pair in a single call, automatically generating TraceId and RequestResponseId values:

RequestResponseLogger.LogPair(
    testName: "My test",
    testId: "test-123",
    method: "Cache Get",                    // OneOf<HttpMethod, string>
    uri: new Uri("redis://cache/my-key"),
    serviceName: "Redis Cache",
    callerName: "My Service",
    requestContent: "GET my-key",
    responseContent: "{\"value\": 42}",
    statusCode: HttpStatusCode.OK
);

This is equivalent to calling RequestResponseLogger.Log() twice (once for Request, once for Response) with matching identifiers and timestamps. It's the recommended approach for custom dependency tracking when you already have both the request and response data available.

See Tracking Custom Dependencies for the full manual approach when you need more control (e.g. different timestamps for request vs response, custom headers, or TrackingIgnore support).

---

Flame Chart Zoom

Flame charts in internal flow popups and whole-test flow sections now support interactive zoom:

Action	Effect
Click a bar	Zooms into that span's time range (with 5% padding)
Double-click anywhere	Resets to the full view

When zoomed, a hint banner appears: "🔍 Zoomed — double-click to reset"

Tooltips on each bar now include:

• Activity source name (e.g. [Microsoft.AspNetCore])
• Span display name
• Duration in milliseconds
• Percentage of total duration

---

TrackingComponentRegistry

All tracking components (TestTrackingMessageHandler, SqlTrackingInterceptor, CosmosTrackingMessageHandler, BlobTrackingMessageHandler, BigQueryTrackingMessageHandler, RedisTracker) auto-register with TrackingComponentRegistry when constructed. This enables automated detection of misconfigured components that were wired up but never processed any traffic.

Automatic Warnings

When ReportDiagnostics.Analyse() runs at report generation time, it automatically checks for unused tracking components and produces console warnings:

Warning: 1 tracking component(s) were registered but never invoked: SqlTrackingInterceptor (Identity Database).
This usually means the component was added to the wrong pipeline or options. Enable DiagnosticMode for details.

This happens automatically — no extra code needed. The warning is informational only and never throws or fails tests.

Diagnostic Report Details

When DiagnosticMode=true, the HTML diagnostic report includes a dedicated Tracking Components section with:

• A table of all registered components with invocation counts and active/unused status
• Troubleshooting hints for common causes (EF Core DbContextOptions<T> mismatch, incorrect HttpClient registration, untracked Redis IDatabase)

Inspect Programmatically

// All registered components
var all = TrackingComponentRegistry.GetRegisteredComponents();

// Only unused components
var unused = TrackingComponentRegistry.GetUnusedComponents();

// Individual component properties (via ITrackingComponent interface)
foreach (var c in all)
{
    Console.WriteLine($"{c.ComponentName}: invoked={c.WasInvoked}, count={c.InvocationCount}");
}

Reset Between Runs

Call Clear() alongside RequestResponseLogger.Clear():

RequestResponseLogger.Clear();
TrackingComponentRegistry.Clear();

ITrackingComponent Interface

All tracking components implement this interface:

public interface ITrackingComponent
{
    string ComponentName { get; }     // e.g. "SqlTrackingInterceptor (Identity Database)"
    bool WasInvoked { get; }          // true after first request/command
    int InvocationCount { get; }      // total requests/commands processed
}

---

Common Issues: Missing Dependencies in Diagrams

gRPC dependency not appearing in per-test reports

Symptom: GrpcTrackingInterceptor is registered and WasInvoked is true, but gRPC calls don't appear in per-test diagrams. The diagnostic report may show logs with "Unknown" test identity.

Cause: The gRPC client runs inside the SUT's request pipeline (on a worker thread), and CurrentTestInfoFetcher cannot resolve the test framework's execution context from that thread. Without HttpContextAccessor, the interceptor falls back to the delegate, which throws → caught internally → logged as "Unknown" → filtered out of per-test reports.

Fix (v2.26.1+): Use AddTrackedGrpcClient<TClient>() which auto-resolves IHttpContextAccessor from DI:

services.RemoveAll<MyGrpcClient>();
services.AddTrackedGrpcClient<MyGrpcClient>(
    handler,
    new Uri("http://localhost"),
    opts =>
    {
        opts.ServiceName = "My gRPC Service";
        opts.CallingServiceName = "My API";
        opts.CurrentTestInfoFetcher = () => GetCurrentTestInfo();
        // HttpContextAccessor auto-resolved from DI — no manual wiring needed
    });

Fix (v2.25.2): Set HttpContextAccessor manually on GrpcTrackingOptions:

services.AddSingleton(sp =>
{
    var options = new GrpcTrackingOptions
    {
        ServiceName = "My gRPC Service",
        CallingServiceName = "My API",
        CurrentTestInfoFetcher = () => GetCurrentTestInfo(),
        HttpContextAccessor = sp.GetRequiredService<IHttpContextAccessor>()
    };
    // ...
});

See Integration Grpc Extension#Dual-Resolution Test Identity (HttpContextAccessor) for the full explanation.

Other dependencies not appearing in per-test reports

Symptom: An extension tracker is registered and WasInvoked is true, but calls don't appear in per-test diagrams. The diagnostic report may show logs with "Unknown" test identity.

Cause: Same as gRPC above — the tracker runs inside the SUT's request pipeline (on a worker thread), and CurrentTestInfoFetcher cannot resolve the test framework's execution context from that thread.

Fix (v2.26.3+): All extension options classes now have an HttpContextAccessor property, and DI extensions / convenience methods auto-resolve it from DI. If you use AddServiceBusTestTracking(), AddTrackedGrpcClient<T>(), CreateTestTrackingClient(), or similar DI conveniences, this is handled automatically.

If you construct trackers manually, set HttpContextAccessor on the options object:

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

See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+) for details.