.NET

Inspect your server’s logs and HTTP activity in Tracebeam. The adapter connects outbound to your Mac—you do not need to expose a debug API or open an inbound port on your server.

Quick start

Requires .NET 8 or later. Open Tracebeam on your Mac and leave Settings → Connections in Basic mode.

1. Add a reference to your local tracebeam-dotnet checkout. The packages are not published to NuGet yet:

   dotnet add path/to/YourServer.csproj reference path/to/tracebeam-dotnet/src/Tracebeam.AspNetCore/Tracebeam.AspNetCore.csproj

2. Register the adapter and middleware in Program.cs:

   using Tracebeam.AspNetCore;
   
   var builder = WebApplication.CreateBuilder(args);
   builder.Services.AddTracebeam();
   
   var app = builder.Build();
   app.UseTracebeam(); // Before exception handling, routing, and endpoints.
   
   app.MapGet("/hello", (ILogger<Program> log) =>
   {
       log.LogInformation("Hello from .NET");
       return new { message = "Hello" };
   });
   app.Run();

3. Run your server with ASPNETCORE_ENVIRONMENT=Development, call an endpoint, and select its connection in Tracebeam’s center toolbar. Open Network or Console.

That’s enough for local inspection. The default address is ws://127.0.0.1:49152. No access key, certificate, or discovery setup is needed. Connections are disabled outside the Development environment by default.

Already have a server? Keep your existing routes, logging, and HTTP client registrations; add only the using, AddTracebeam(), and UseTracebeam() calls. For apps using Startup.cs, register in ConfigureServices and add the middleware near the start of Configure, before exception handling and routing.

Everything below is optional configuration or a capture detail—not another setup requirement.

What you can inspect

• Logs: ILogger messages, levels, categories, structured properties, scopes, exceptions, and Activity trace/span IDs. Existing logging providers keep working.
• Incoming HTTP: ASP.NET Core requests and responses, including method, URL, headers, status, middleware duration, and body previews.
• Outgoing HTTP: asynchronous requests from clients registered with IHttpClientFactory, including bodies, errors, and time to response headers.

Plain Console.WriteLine output is not automatically captured; use ILogger. Synchronous HttpClient.Send and directly constructed new HttpClient() instances are not automatically instrumented. See manual HTTP clients.

The .NET adapter provides logs and network inspection, not state inspectors, database profiling, screen capture, or offline adapter recording. You can record its connected session on the Mac.

Request and response bodies

Body capture is on by default, for both incoming and outgoing HTTP. JSON, XML, URL-encoded forms, and text are captured as the application reads or writes them. Streams and ASP.NET Core BodyReader / BodyWriter are supported.

The adapter does not pre-read requests, buffer entire responses, or spool uploads to disk. Headers appear first; a body update follows on consumption, completion, or disposal, using the same network row. Unread bytes are not fetched just for inspection, including with ResponseHeadersRead.

Limits and redaction

The defaults are 64 KiB per body preview and 4 MiB shared across active and queued raw body buffers. Redaction and event encoding run on one background sender. Exhausting the buffer budget omits bodies rather than delaying application requests.

To change the defaults, replace the quick start’s registration with:

builder.Services.AddTracebeam(options =>
{
    options.CaptureRequestBodies = true;
    options.CaptureResponseBodies = true;
    options.MaximumBodyBytes = 64 * 1024;
    options.MaximumTotalBodyBytes = 4 * 1024 * 1024;
    options.RedactedBodyFields.Add("deviceSignature");
});

Set either capture flag to false to omit that side’s body. The desktop’s body limit can reduce the preview size; Unlimited does not bypass adapter limits. MaximumBodyBytes supports up to 1 MiB, but the encoded event must also fit Connection.MaximumEventBytes (256 KiB by default, up to 1 MiB). Oversized body events fall back to metadata only. The raw-buffer budget is not a total process-memory cap.

Common passwords, tokens, API keys, and configured field names are redacted from JSON, XML, and forms. Body field matching ignores case, underscores, and hyphens. Extend the defaults for your own fields. Plain text, custom names, and unstructured strings can still contain secrets; redaction is not a universal secret detector.

Why a body may be missing or incomplete

• Unread or partially read: only consumed bytes are observed. Always dispose HTTP responses and streams.
• Unsupported content: binary, multipart, server-sent events, still-compressed content, and SendFile bodies are omitted. Responses already decompressed by your application’s handler can be captured.
• Truncated or invalid JSON/XML: omitted when safe field redaction cannot be guaranteed. Text can show a valid-character prefix; forms omit an incomplete final field.
• Capture limits: previews can be truncated or omitted when body, buffer, or event limits are reached.

Truncated bodies are not complete API contract inputs, and redacted fields no longer contain their original values. For trusted test fixtures only, RedactBodyFields = false allows raw previews, including incomplete JSON; do not use it with real credentials.

Docker or another computer

For Docker Desktop for Mac, replace the registration with:

builder.Services.AddTracebeam(options =>
{
    options.Connection.Endpoint = new Uri("ws://host.docker.internal:49152");
    options.Connection.AppName = "My API";
    options.Connection.BundleIdentifier = "com.example.my-api";
});

Enable Settings → Connections → Connect devices over Wi-Fi or Ethernet in Tracebeam and allow its listener through the Mac firewall. Keep the container’s ASP.NET Core environment set to Development. Container 127.0.0.1 refers to the container, not your Mac. No Tracebeam debug port needs to be published from Docker.

The referenced adapter source must be included in your Docker build context. For a server on another computer, use the Mac’s reachable hostname or IP instead of host.docker.internal. .NET does not perform automatic discovery.

Basic is unencrypted and unauthenticated: use it only on trusted development networks. For a remote test environment, use a private tunnel or VPN and Secure mode. EnableOutsideDevelopment = true is an explicit opt-in for controlled testing, not a production monitoring setup.

Configure the address without changing code

Read your application’s configuration explicitly:

builder.Services.AddTracebeam(options =>
{
    options.Connection.Endpoint = new Uri(
        builder.Configuration["Tracebeam:Endpoint"] ?? "ws://127.0.0.1:49152");
});

With this code, set Tracebeam__Endpoint=ws://host.docker.internal:49152 in the container environment. The adapter does not automatically bind configuration or environment variables itself.

Secure mode (optional)

Choose Secure in Tracebeam’s Connections settings, copy the access key, and export the Device CA Certificate. Configure the adapter:

builder.Services.AddTracebeam(options =>
{
    options.Connection.Endpoint = new Uri("wss://YOUR-MAC.local:49152");
    options.Connection.AccessKey =
        Environment.GetEnvironmentVariable("TRACEBEAM_ACCESS_KEY");
    options.Connection.DeviceCertificateAuthorityPath =
        "/private/config/tracebeam-device-ca.cer";
});

Replace the hostname with one covered by the certificate and the path with your exported certificate’s location. Supply the key through private environment/configuration, never source control. For Docker, mount the certificate read-only at the configured container path.

PEM and DER CA files are supported. Omit the CA path if the runtime already trusts the Device CA. Custom trust applies only to the debugger socket; your application’s HTTP/TLS configuration is unchanged. Certificate chain and hostname checks remain enabled.

Secure requires both wss:// and an access key. It never falls back to Basic or sends a key over ws://. Do not use the separate Proxy CA. Connection troubleshooting.

Advanced configuration

Filtering sensitive data

Extend the default redaction sets without changing actual requests:

builder.Services.AddTracebeam(options =>
{
    options.RedactedHeaders.Add("X-Device-Signature");
    options.RedactedQueryParameters.Add("session_secret");
    options.RedactedLogFields.Add("PaymentSecret");
    options.RedactedBodyFields.Add("PaymentSecret");
    options.MinimumLogLevel = LogLevel.Warning;
});

Arbitrary log text, exception messages, and unstructured scopes can still contain secrets. HTTP metadata redaction does not sanitize URLs logged separately by other libraries. Normal .NET logging filters also apply.

Manual HTTP clients

For clients you construct directly, use the registered TracebeamClient:

using Tracebeam;
using Tracebeam.AspNetCore;

var tracebeamClient = app.Services.GetRequiredService<TracebeamClient>();
var handler = new TracebeamHttpMessageHandler(tracebeamClient)
{
    InnerHandler = new HttpClientHandler()
};
using var http = new HttpClient(handler);
using var response = await http.GetAsync("https://example.com");

You do not need this for IHttpClientFactory clients. To suppress capture for one outgoing request, set request.Options.Set(TracebeamHttpMessageHandler.SuppressCapture, true) before sending it.

Remembered identity and reconnects

The adapter persists a random installation ID scoped to Connection.BundleIdentifier (the app name by default). Reconnects and restarts can reuse that identity; clearing its storage creates a new one. Identity is not authentication and does not merge separate capture sessions.

For containers, point Connection.IdentityDirectory at a private writable persistent volume. Give each replica its own directory; do not share identities, bake them into images, or include them in backups. Set PersistInstallationId = false to disable persistence.

The background sender uses a bounded queue: 512 events, 4 MiB encoded/reserved bytes, and 256 KiB per event by default. Configure these with Connection.MaximumQueuedEvents, MaximumQueuedBytes, and MaximumEventBytes if needed.

Capture is best effort. Disconnected activity and events that exceed queue capacity are omitted; old queued events are discarded on disconnect. TracebeamClient.Statistics exposes queue, sent, and dropped counts; automatic instrumentation skipped while disconnected is not counted. A desktop recording cannot recover omitted events.

Troubleshooting

• No connection: check Development is the effective environment, the Mac listener is active, and mode/port match. Docker requires the host address and network access described above.
• No incoming HTTP: place UseTracebeam() before exception handling, routing, and endpoints, then send a new request after connecting.
• No outgoing HTTP: use an IHttpClientFactory client or the explicit handler, and asynchronous send methods.
• No logs: use ILogger; check your .NET logging filters and the adapter’s MinimumLogLevel (Information by default).
• Missing bodies: check consumption, content type, redaction, and capture limits. Unread bodies are not fetched for inspection.
• New identity after recreating a container: use a private persistent identity volume and a stable bundle identifier.
• TLS errors: use the exported Device CA, a certificate-matching hostname, and the current access key. Never disable certificate validation.