ZBRA.MessageTrace.Client.AspNetCore 1.6.3

ZBRA.MessageTrace.Client.AspNetCore

Instruments an ASP.NET Core service for ZBRA MessageTrace. Records inbound requests, outbound HttpClient and SOAP calls and profiled method calls, correlates them across services, and ships them in batches to a MessageTrace collector.

net6.0 serves .NET 6–7, net8.0 serves 8–9, net10.0 serves 10. net6.0 is best effort: tested on every build, but .NET 6 is out of Microsoft support and fixes specific to it are not guaranteed. Apache-2.0.

Full details, best practices and pitfalls: REFERENCE.md, inside this package.

Setup

builder.Services.AddMessageTrace(builder.Configuration.GetSection(MessageTraceOptions.SectionName));

var app = builder.Build();
app.UseExceptionHandler();
app.UseRouting();
app.UseMessageTrace();   // after UseRouting, inside the exception handler
app.MapControllers();

{
  "MessageTrace": {
    "ServiceName": "orders-api",
    "BaseUrl": "https://trace.example.com/",
    "ApiKey": "…"          // from a secret store
  }
}

• ServiceName, BaseUrl, ApiKey are required. Invalid settings stop the host from starting.
• Settings are read once at startup. Any change needs a restart.
• Enabled: false turns tracing off. Nothing is required, recorded or sent.

Only requests that matched an endpoint are recorded. Static files, SPA fallback and 404s are not.

Outbound HTTP

services.AddHttpClient<IPartnerClient, PartnerClient>()
        .AddMessageTraceHandler();

// Calling another service instrumented with MessageTrace: propagate correlation, let it record the call.
services.AddHttpClient<IMasterDataClient, MasterDataClient>()
        .AddMessageTraceHandler(logRequest: false, propagate: true);

Never propagate: true towards external systems (SAP, partners, public APIs).

SOAP

WCF clients send through their own HttpClient, which AddMessageTraceHandler cannot reach. Outbound SOAP calls need ZBRA.MessageTrace.Client.Soap, a separate package so the WCF dependency chain stays out of services that make no SOAP calls. No extra using: AddMessageTraceBehavior is in the ZBRA.MessageTrace.Client.AspNetCore namespace.

Add the behavior once per endpoint, before the first call:

services.AddSingleton(p =>
{
    var client = new DefaultClient(binding, endpoint);
    client.Endpoint.AddMessageTraceBehavior(p);
    return client;
});

Calls are correlated with the request in scope, like any outbound call. Two capture levels:

• Metadata (default): host, path, timing, HTTP status or transport exception, SOAP action. No message content is read. An HTTP 200 is not the outcome: a BAPI RETURN error arrives as 200.
• Full: also reads the envelopes. Records the operation, SOAP faults, SAP RETURN outcomes, message ids and well-known document numbers, and marks the call 500 on a fault or RETURN error. Opt-in. Holds each envelope in memory up to MaxExtractionSize; the extracted values are stored without redaction. Needs buffered transfer mode: streamed endpoints stay at Metadata.

services.Configure<MessageTraceSoapOptions>(o => o.CaptureLevel = SoapCaptureLevel.Full);

• Supported WCF: 6.2 (net6), 8.1 (net8), 10.0 (net10).
• A custom WCF HttpMessageHandler factory on the endpoint disables tracing for it, with a warning.
• Extra business keys at Full: register an ISoapCallDescriber (see REFERENCE.md).

Profiling

Shows where the time goes inside a request. Each profiled call records its duration and outcome. In the collector, the calls nest under the request that made them on its timeline. The Profiling page ranks methods by cost, grouped by key.

There are two ways in, and they nest in each other.

Proxy an interface. No change to method bodies. Every call through the interface is recorded.

services.AddScopedWithProfiling<IOrderService, OrderService>();   // or AddTransientWithProfiling

[Profiling("orders")]                   // grouping key, defaults to DefaultProfilingKey
public class OrderService : IOrderService
{
    [ProfilingBehavior(EnableSaveMethodArguments = true)]   // off by default
    public Task<Order> PlaceAsync(OrderRequest request) { /* … */ }
}

• Applied only when EnableProfilingProxy is true, so it can be switched on per environment without code changes.
• Recorded arguments are stored as given, without redaction.
• Dispatch is reflection-based. Keep it off hot paths.
• The resolved object is a proxy: is checks and casts to OrderService fail.

Time a block with IMessageTraceProfiler. For code the proxy cannot reach: loops, static methods, classes without an interface, steps inside a method. Inject it from DI; it records whenever tracing is enabled.

using (profiler.Start("OrderImport", "ParseRows")) { /* … */ }

var rows = profiler.Measure("OrderImport", "ParseRows", () => Parse(file));
await profiler.MeasureAsync("OrderImport", "Save", () => repository.SaveAsync(rows));

• The names are the grouping on the Profiling page: keep them fixed, never ids or user input.
• Measure records a thrown exception as a failure, except cancellation, and rethrows it.

Tagging requests

Attach business context to a request, such as a tenant or an order number, to find its trace later. The pair is copied onto the request's event and the events of its outbound calls. It is stored as given, without redaction.

HttpContext.AddMessageTraceCustomData("tenant", order.TenantId);

Endpoint overrides

[MessageTraceBehavior] adjusts capture for one endpoint. It can turn capture off where it is on globally, never the reverse.

[MessageTraceBehavior(IgnoreEndpoint = true)]       // health checks, probes: nothing recorded
[MessageTraceBehavior(IgnoreRequestBody = true)]    // bodies carrying secrets
[MessageTraceBehavior(IgnoreResponseBody = true)]   // downloads, streams
[MessageTraceBehavior(GetResponseInfo = true)]      // keep a GET's response body, skipped by default

Defaults worth knowing

• Bodies captured up to 1024 bytes, text-like content types only. GET response bodies are skipped.
• Sensitive headers, body keys and card numbers are masked with ***.
• Queues are bounded (10 000 per stream) and drop the oldest when full. Flushed every 15 s and on shutdown.
• The collector drops entries older than its retention or stamped more than a day ahead of its clock (clock skew, long backlog replays); the rest of the batch is stored.
• On net6.0 this package lifts the application's System.Text.Json from the in-box 6.0 to 8.0.6.

Support

The Developer Integration Guide delivered with MessageTrace covers setup end to end. Support: message-trace@zbra.dev (best effort, no SLA).