The Kronikol.Extensions.BigQuery package adds Google BigQuery REST API operation tracking to your test diagrams. Instead of showing raw HTTP requests like POST /bigquery/v2/projects/my-project/queries, your sequence diagrams show classified operations like Query: /query or Insert: /mydataset/table/mytable.

Using a shared library or abstraction layer? If your code doesn't use the BigQuery SDK directly — e.g. it goes through a shared data-access library, wrapper, or custom abstraction — this extension won't be able to intercept the underlying calls. See Tracking Custom Dependencies for alternative approaches including RequestResponseLogger.LogPair(), TrackingProxy<T>, and MessageTracker.

The Google BigQuery .NET SDK (Google.Cloud.BigQuery.V2) translates all operations into REST HTTP requests. BigQueryTrackingMessageHandler is a DelegatingHandler that intercepts these HTTP requests, classifies each one into a BigQuery operation (Query, Insert, Read, List, Create, Delete, Update, Cancel) using the HTTP method and URL path, then logs it to RequestResponseLogger with a human-readable label.

Because it logs to the same RequestResponseLogger as the standard TestTrackingMessageHandler, BigQuery operations appear alongside your HTTP API calls in the same sequence diagram — showing the complete flow from test → API → BigQuery.

dotnet add package Kronikol.Extensions.BigQuery

The extension supports three verbosity levels that control how much detail appears in the diagrams:

The default is Detailed.

The classifier recognises these BigQuery operations from the SDK's HTTP traffic:

In Summarised mode, Other operations are silently skipped.

The classifier extracts and tracks these resource types:

The upload endpoint variant (/upload/bigquery/v2/projects/...) is also recognised for data loading jobs.

Use the WithTestTracking() extension method on BigQueryClientBuilder:

var trackingOptions = new BigQueryTrackingMessageHandlerOptions
{
    ServiceName = "BigQuery",
    CallerName = "My API",
    Verbosity = BigQueryTrackingVerbosity.Detailed,
    CurrentTestInfoFetcher = CurrentTestInfo.Fetcher,
    HttpContextAccessor = httpContextAccessor // optional: enables dual-resolution from HTTP headers
};

var client = new BigQueryClientBuilder
{
    ProjectId = "my-project",
    // Credential = ... (for real BigQuery)
}
.WithTestTracking(trackingOptions)
.Build();

WithTestTracking sets the builder's HttpClientFactory to a TrackingBigQueryHttpClientFactory that wraps the default HTTP handler with the tracking handler. The pipeline becomes:

BigQueryClient → ConfigurableMessageHandler (auth, retry) → BigQueryTrackingMessageHandler → HttpClientHandler

For WebApplicationFactory-based integration tests where BigQuery clients are registered in DI:

builder.ConfigureTestServices(services =>
{
    // Remove existing BigQueryClient registration
    var descriptor = services.SingleOrDefault(d => d.ServiceType == typeof(BigQueryClient));
    if (descriptor != null) services.Remove(descriptor);

    // Register tracked client
    services.AddSingleton(sp =>
    {
        var trackingOptions = new BigQueryTrackingMessageHandlerOptions
        {
            ServiceName = "BigQuery",
            CallerName = "My API",
            Verbosity = BigQueryTrackingVerbosity.Detailed,
            CurrentTestInfoFetcher = CurrentTestInfo.Fetcher
        };

        return new BigQueryClientBuilder
        {
            ProjectId = "test-project",
        }
        .WithTestTracking(trackingOptions)
        .Build();
    });
});

If you need full control over the HTTP pipeline, use BigQueryTrackingMessageHandler directly:

var trackingOptions = new BigQueryTrackingMessageHandlerOptions
{
    ServiceName = "BigQuery",
    CallerName = "My API",
    Verbosity = BigQueryTrackingVerbosity.Detailed,
    CurrentTestInfoFetcher = () => ("My Test", testId)
};

var handler = new BigQueryTrackingMessageHandler(trackingOptions, new HttpClientHandler());
// Use handler with your own HTTP pipeline setup

v2.23.0+ Dual-Resolution: BigQueryTrackingMessageHandler accepts an optional IHttpContextAccessor? httpContextAccessor constructor parameter for resolving test identity from HTTP request headers when running inside the SUT's request pipeline. See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+) for details.

The following Google API headers are excluded by default (they add noise without diagnostic value):

• Authorization
• User-Agent
• x-goog-api-client
• x-goog-request-params
• google-cloud-resource-prefix
• Cache-Control

Override ExcludedHeaders to customise:

new BigQueryTrackingMessageHandlerOptions
{
    ExcludedHeaders = ["Authorization"] // Only exclude Authorization
}

If you don't need HTTP-level interception — for example, you want to log BigQuery operations from a gRPC-based pipeline, a shared data layer, or a custom abstraction — use BigQueryTracker directly:

using Kronikol.Extensions.BigQuery;

var tracker = new BigQueryTracker(new BigQueryTrackingMessageHandlerOptions
{
    ServiceName = "BigQuery",
    CallerName = "OrdersApi",
    Verbosity = BigQueryTrackingVerbosity.Detailed,
    CurrentTestInfoFetcher = CurrentTestInfo.Fetcher
});

// Classify and log
var request = new HttpRequestMessage(HttpMethod.Post, "/bigquery/v2/projects/my-project/queries");
var op = BigQueryOperationClassifier.Classify(request);
var (reqId, traceId) = tracker.LogRequest(op, "SELECT * FROM dataset.table");

// ... execute BigQuery operation ...

tracker.LogResponse(op, reqId, traceId, "42 rows returned");

BigQueryTracker implements ITrackingComponent, supports phase-aware tracking, and uses the same BigQueryTrackingMessageHandlerOptions as the handler.

Register a BigQueryTracker instance in your DI container:

services.AddBigQueryTestTracking(options =>
{
    options.ServiceName = "BigQuery";
    options.CallerName = "OrdersApi";
    options.Verbosity = BigQueryTrackingVerbosity.Detailed;
    options.CurrentTestInfoFetcher = CurrentTestInfo.Fetcher;
});

Then inject BigQueryTracker where needed in your test setup or custom middleware.

Note: Options D and E are complementary to Options A–C. The HTTP handler (Options A–C) intercepts all BigQuery SDK traffic automatically. The direct tracker (Options D–E) is for scenarios where you intercept at a different layer or want to log custom BigQuery-related events.

If you already use TestTrackingMessageHandlerOptions for HTTP tracking and want to share the same test info fetchers with BigQuery tracking:

var httpOptions = new TestTrackingMessageHandlerOptions
{
    CurrentTestInfoFetcher = () => (testName, testId),
    CurrentStepTypeFetcher = () => currentStepType,
    CallerName = "My API"
};

var bqOptions = new BigQueryTrackingMessageHandlerOptions
{
    ServiceName = "BigQuery",
    CallerName = httpOptions.CallerName,
    CurrentTestInfoFetcher = httpOptions.CurrentTestInfoFetcher,
    CurrentStepTypeFetcher = httpOptions.CurrentStepTypeFetcher,
    Verbosity = BigQueryTrackingVerbosity.Detailed
};

The extension works with all Kronikol framework adapters:

BigQueryTrackingMessageHandler implements ITrackingComponent and auto-registers with TrackingComponentRegistry on construction. At report generation time, unused components are automatically detected and surfaced as console warnings and in the diagnostic report (when DiagnosticMode=true). This never throws or fails tests.

See Diagnostics and Debugging for full details on the TrackingComponentRegistry API.