jahro-logging

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

If the project has a `LogTag` constants class, use its values. Otherwise, use the system/class name as the tag.

### Criticality tiers

Auto-classify the system being written/edited and adjust logging depth accordingly:

**Tier 1 — Critical (maximum verbosity)**
Systems: saves, IAP, auth, network, analytics.
Log every state transition, decision branch, error with full context. Include timing, retry counts, correlation IDs.

**Tier 2 — Gameplay (moderate verbosity)**
Systems: player state, inventory, economy, quests, AI, scene management.
Log state transitions, significant events, errors, warnings. Skip per-frame updates.

**Tier 3 — Infrastructure (minimal verbosity)**
Systems: physics, input, animation, audio, rendering, camera, UI navigation.
Log initialization, errors, anomalies only. Never log per-frame operations.

Classification heuristics by class/namespace name:

| Pattern | Tier |
|:--------|:-----|
| `SaveManager`, `PurchaseController`, `AuthService`, `NetworkManager`, `AnalyticsDispatcher` | 1 |
| `PlayerController`, `InventorySystem`, `QuestManager`, `AIController`, `EconomyManager` | 2 |
| `CameraController`, `InputHandler`, `AudioManager`, `ParticleSpawner`, `AnimationDriver` | 3 |

### Boundary logging

Log at boundaries — the joints where things break. Skip internal computations.

- **System boundaries**: when control passes between systems (log the handoff)
- **State boundaries**: state machine transitions (log from/to/cause)
- **Error boundaries**: `catch` blocks, null checks, validation failures (log diagnostics)
- **External boundaries**: file I/O, HTTP, platform APIs (log request + response/error)

Do NOT log: internal algorithm steps, per-frame position/velocity, routine success that happens 1000x/session, framework plumbing (`Awake` called, coroutine started).

### Hot-path guards

Never place unconditional `Debug.Log` in `Update()`, `FixedUpdate()`, `LateUpdate()`, or any per-frame method. These produce 60+ messages/second/instance, flood the console, and tank performance. If temporary frame-level logging is needed, guard it:

```csharp
[SerializeField] private bool debugMovement;

void Update()
{
    if (debugMovement)
        Debug.Log($"[Player] Position — pos={transform.position}, vel={rb.velocity}", this);
}
```

### Context object

In MonoBehaviours, always pass `this` (or `gameObject`) as the second parameter to `Debug.Log`. This makes the log message clickable in the Unity Console — clicking it pings the source GameObject in the Hierarchy.

```csharp
Debug.Log($"[Player] State changed — from={oldState}, to={newState}", this);
Debug.LogError($"[Save] Write failed — path={filePath}, error={ex.Message}", this);
```

### Sensitive data

Never log credentials, tokens, passwords, emails, payment details, or PII. Mask or omit them:

```csharp
Debug.Log($"[Auth] Login attempt — user={userId}, token=***", this);
```

### Data formatting

- **Numbers**: include units — `elapsed=340ms`, `size=1.2MB`, not bare numbers
- **Vectors**: readable format — `pos=(12.3, 0.0, -4.5)`, not `pos=UnityEngine.Vector3`

From jahro-console/unity-agent-skills, MIT.

More from jahro-console/unity-agent-skills