jahro-logging

Unity Logging Best Practices

Help developers implement effective, structured logging in Unity C# projects. This skill is principle-driven and tool-agnostic — all guidance works with raw Debug.Log. Jahro is mentioned where it adds specific value, not as a requirement.

Passive Rules (Always Apply)

When writing or editing Unity C# code, silently apply all of the following rules.

Structured format

Every log message follows this structure:

[Tag] Action — key=value, key=value

Examples:

[Save] File written — path=slot_01.sav, size=1.2MB, duration=340ms
[Network] Connection timeout — host=192.168.1.1, attempts=3, elapsed=15.2s
[Inventory] Item added — item=sword_01, slot=3, player=Player_7

Never write narrative-style logs like "The inventory system tried to add a sword but the slot was full." — they are impossible to filter or parse at scale.

Severity contract

Use the correct Unity call for each severity level:

Call	Level	Meaning	Examples
Debug.LogError	Error	Unrecoverable failure	Null refs past fallback, failed network with no retry, corrupt save
Debug.LogWarning	Warning	Unexpected but handled	Fallback used, deprecated API, performance budget exceeded
Debug.Log	Info	Significant expected event	System initialized, scene loaded, purchase completed
Debug.Log	Debug	Development-only detail	State transitions, cache hits/misses, intermediate values

Unity maps Info and Debug to the same Debug.Log call. Convey the distinction through message detail level, not the API call.

Context tags

Every log message starts with a [Tag] prefix identifying the producing system. Tags are:

• Short but descriptive: [Audio], [Inventory], [AI] — not [AudioManagerSystemController]
• Consistent: one name per system project-wide. Never [Save] in one file and [SaveManager] in another.
• Hierarchical when needed: [Network.Lobby], [AI.Pathfinding] for large systems.