Runtime API

AzCon API

Emit logs through the public AzCon facade and attach metadata with LogOptions.

Severity methods
Simple metadata and LogOptions
Scoped metadata
Trace, Unity-style overloads, and assertions

Import the API

using Azkar.Console;

AzCon is the public logging facade for Azkar Console. Use it instead of calling the internal logging core directly.

Severity Methods

AzCon.Trace("AI tick");
AzCon.Debug("Selected spawn point");
AzCon.Log("Connected to relay");
AzCon.LogWarning("Relay RTT spike detected");
AzCon.LogError("Save failed");

Method	Level	Use For	Stack Details
`AzCon.Trace(...)`	Trace	Very frequent diagnostic breadcrumbs, repeated flow tracking, and trace history grouping.	Purpose-built trace/callsite behavior.
`AzCon.Debug(...)`	Debug	Development-only state inspection and diagnostic details.	Full stack trace by default.
`AzCon.Log(...)`	Info	Normal informational events, lifecycle notes, and successful operations.	File and line by default.
`AzCon.LogWarning(...)`	Warning	Recoverable problems, unusual state, and degraded behavior.	Full stack trace by default.
`AzCon.LogError(...)`	Error	Failed operations, invalid state, and exceptions you handled but still need visible.	Full stack trace by default.
`AzCon.LogException(...)`	Fatal	Exception-first logging that stores the exception object.	Exception-first diagnostic details.

Ordinary AzCon.Log entries are optimized for high-volume logging and capture file and line by default. Use AzCon.Debug when a non-warning, non-error log needs a full diagnostic stack.

There are intentionally no public AzCon.Info, AzCon.Warning, AzCon.Error, or AzCon.Fatal methods. Use Log, LogWarning, LogError, and LogException.

Simple Metadata

For simple metadata, pass one value directly. LogOptions has implicit conversions for categories, single tags, tag masks, headers, aliases, and Unity object contexts.

AzCon.Log("Player spawned", AzCon.Category.Gameplay);
AzCon.Debug("Boss state changed", AzCon.Tag.Create("Boss"));
AzCon.LogWarning("Packet retry", AzCon.Header.Network);
AzCon.LogError("Save failed", new System.InvalidOperationException("Disk full"));
AzCon.Log("Selected object", this);

LogOptions

Use LogOptions when one entry needs multiple metadata values.

var combatTag = AzCon.Tag.Create("Combat");
var bossAlias = AzCon.Alias.Dynamic("Boss 01");

var options = new LogOptions(
    category: AzCon.Category.Gameplay,
    tags: AzCon.Tags(combatTag),
    header: AzCon.Header.Quick("Boss"),
    alias: bossAlias,
    context: this);

AzCon.Log("Boss phase started", in options);

Option	Purpose
`category`	One coarse classification, such as Gameplay, Network, Save, or Performance.
`tags`	Multi-tag filtering via `TagMask`.
`header`	Visual prefix, such as `[Network]`.
`alias`	Logical identity, such as Player 1, Server, or Boss 01.
`context`	Unity object context for selection and object metadata.

Scoped Metadata

Use AzCon.Scope(in LogScopeOptions) when a block of logs should share metadata. Explicit per-call metadata takes precedence, while tags are combined.

var scope = new LogScopeOptions(
    category: AzCon.Category.Network,
    tags: AzCon.Tags(AzCon.Tag.Create("Relay")),
    header: AzCon.Header.Network,
    alias: AzCon.Alias.Dynamic("Client"),
    context: this);

using (AzCon.Scope(in scope))
{
    AzCon.Log("Connecting");
    AzCon.LogWarning("Retrying handshake");
}

Use HeaderScope when only a visual header should apply.

using (AzCon.HeaderScope("Inventory", Color.cyan))
{
    AzCon.Log("Equipped item");
    AzCon.Debug("Slot cache rebuilt");
}

Scopes are thread-local, so they do not automatically cross async or thread boundaries.

Trace Methods

Trace logs are designed for repeated diagnostic histories. They use a stable call-site key based on file, line, and member name.

AzCon.Trace("AI tick");

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

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

Method	Grouping
`TraceCallsite(message, ...)`	Groups all calls from the same source location.
`TraceContext(message, UnityEngine.Object context, ...)`	Groups by source location plus Unity object instance. Requires a valid, non-destroyed context.
`TraceContext(message, int contextInstanceId, ...)`	Uses a cached instance ID, which is useful from background threads.
`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);

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

Unity-Compatible Methods

AzCon.Log("Message");
AzCon.Log("Message", this);

AzCon.LogFormat("Loaded {0} assets", assetCount);
AzCon.LogFormat(this, "Health: {0}", health);

AzCon.LogWarningFormat("RTT: {0} ms", rtt);
AzCon.LogErrorFormat(this, "Save slot {0} failed", slot);

AzCon.LogException(exception, this);

LogFormat(LogType, LogOption, Object, string, params object[]) maps Unity log types into Azkar Console levels. Stack capture follows the mapped level: ordinary logs use the current Log Stack Trace Capture setting, while warnings and errors keep full diagnostic stacks.

Assertions

AzCon.LogAssertion("Inventory invariant failed", this);

AzCon.Assert(playerHealth >= 0, "Health went negative: {0}", playerHealth);

LogAssertion(...) emits an assertion entry when logging is enabled. Assert(...) only emits when the condition is false and is compiled for UNITY_EDITOR or DEVELOPMENT_BUILD. Assertion entries are Error-level logs, use the Assert category, and prefix the message with [ASSERT].

Categories, Tags, Headers, and Aliases

Categories are one-per-log, broad, and filter-friendly.

AzCon.Log("Packet sent", AzCon.Category.Network);
var inventory = AzCon.Category.GetOrCreate("Inventory", Color.cyan);

Tags are many-per-log and cross-cutting.

var combat = AzCon.Tag.Create("Combat");
var boss = AzCon.Tag.Create("Boss");

AzCon.Log("Boss hit", new LogOptions(
    category: AzCon.Category.Gameplay,
    tags: AzCon.Tags(combat, boss)));

Headers are visual prefixes.

AzCon.Log("Handshake complete", AzCon.Header.Network);
AzCon.Log("Temporary note", AzCon.Header.Quick("Temp", Color.yellow));

Aliases identify logical actors or systems.

var server = AzCon.Alias.Create("Server", Color.green);
var player = AzCon.Alias.Dynamic("Player 1");

AzCon.TraceAlias("Replicated transform", player);