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
`AzCon.Trace(...)`	Trace	Very frequent diagnostic breadcrumbs, repeated flow tracking, and trace history grouping.
`AzCon.Debug(...)`	Debug	Development-only state inspection and diagnostic details.
`AzCon.Log(...)`	Info	Normal informational events, lifecycle notes, and successful operations.
`AzCon.LogWarning(...)`	Warning	Recoverable problems, unusual state, and degraded behavior.
`AzCon.LogError(...)`	Error	Failed operations, invalid state, and exceptions you handled but still need visible.
`AzCon.LogException(...)`	Fatal	Exception-first logging that stores the exception object.

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, tags, headers, aliases, Unity contexts, exceptions, context IDs, and stack-capture overrides.

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,
    stackCaptureOverride: LogStackCaptureOverride.ForceCallsite);

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.
`contextId`	Non-object or precomputed identity, such as an entity ID.
`exception`	Attached exception object.
`stackCaptureOverride`	Per-log stack behavior: Default, Suppress, ForceCallsite, or ForceFullStack.
`sourceId`	Advanced source override for remote or multi-process logging.

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. LogOption.NoStacktrace suppresses stack capture for that entry.

Assertions

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

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

LogAssertion(...) always emits an assertion entry. 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);