Trace review

Trace System

Inspect repeated callsites with Trace when you need to understand frequency, frame range, and occurrence history.

Trace history
Grouping methods
Stack capture
When to use ordinary logs

Trace System

Trace logs are designed for repeated diagnostic histories. A normal log says something happened. A trace helps you inspect how often a specific point was hit and how it behaved over time.

AzCon.Trace("AI tick");

var options = new LogOptions(
    alias: AzCon.Alias.Dynamic("Enemy 12"),
    category: AzCon.Category.AI);

AzCon.Trace("Decision changed", in options);

The common AzCon.Trace(...) call uses a stable call-site key based on file, line, and member name. Open a Trace row to inspect occurrence count, timing span, frame range, and occurrence history. Analysis reads the complete retained group rather than only rows visible through current filters, and large timelines load rows on demand. The first request in a large retained session can take longer while retained Trace groups are indexed. Clear, retention trimming, database replacement, or unmount requires that index to be rebuilt on a later request, so bounded in-memory retention is recommended for consistently responsive sessions.

With Workbench presentation enabled, View Occurrences opens the Workbench's Occurrences role. Selecting a Trace row also prepares that role in the background without changing the visible Workbench role or taking focus. In separate-window mode, the same command opens the occurrence utility. See Dockable Workbench for follow, pin, and history behavior.

Grouping Methods

Method	Grouping
`TraceCallsite(message, ...)`	Groups all calls from the same source location.
`TraceContext(message, UnityEngine.Object context, ...)`	Groups by source location plus live Unity object identity. Requires a valid, non-destroyed context.
`TraceContext(message, LogContextId contextId, ...)`	Uses a cached, version-neutral Unity context ID. This overload is safe to call from background threads.
`TraceContext(message, int contextInstanceId, ...)`	Legacy cached instance-ID overload retained for compatibility.
`TraceAlias(message, LogAlias alias, ...)`	Groups by source location plus logical alias.
`TraceAlias(message, uint aliasId, ...)`	Faster variant using a cached alias `Id`.

AzCon.TraceCallsite("Damage calculation ran");

AzCon.TraceContext("Enemy state changed", this, AzCon.Category.AI);

var playerAlias = AzCon.Alias.Dynamic("Player 1");
AzCon.TraceAlias("Input packet received", playerAlias, AzCon.Category.Network);

Cache a version-neutral context ID from a live object on Unity's main thread before sending work to a background thread. Editors exposing the public entity-identity API use it; other supported editors use the public instance-ID fallback.

private LogContextId _contextId;

void Awake()
{
    _contextId = AzCon.GetContextId(this);
}

void LogFromWorkerThread()
{
    AzCon.TraceContext("Enemy state changed", _contextId);
}

Stack Capture

LogConfig.TraceStackMode controls whether trace logs use a cheap call-site frame or full stack capture.

When to Use Trace

A method is called too often or not often enough.
You need to compare repeated updates across frames.
You want callsite history without creating many different log messages.
Aliases or contexts help separate repeated calls by object or role.

Use ordinary Debug or Log rows when you only need a single event marker.