# Logging & Diagnostics

- Human-readable logs are written to stderr by default
- `--verbose` shows expanded diagnostic details
- `--debug-log <path>` writes sanitized JSON lines for troubleshooting (no secrets)
- Verbose/debug logs include a correlation ID per command invocation
- PII (e.g., UPNs) is masked or truncated in logs; full identifiers appear only in primary output

### Debug Log Format (`--debug-log`)

When `--debug-log <path>` is specified, the CLI writes newline-delimited JSON (JSON Lines) to the specified file. Each line is a self-contained JSON object:

```json
{"ts":"2026-01-24T10:30:00.123Z","correlation_id":"a1b2c3d4","level":"INFO","event":"command_start","command":"users list","tenant":"contoso"}
{"ts":"2026-01-24T10:30:00.456Z","correlation_id":"a1b2c3d4","level":"DEBUG","event":"cache_miss","cache_key":"contoso:users:list"}
{"ts":"2026-01-24T10:30:00.789Z","correlation_id":"a1b2c3d4","level":"DEBUG","event":"graph_request","method":"GET","endpoint":"/users","duration_ms":234}
{"ts":"2026-01-24T10:30:01.012Z","correlation_id":"a1b2c3d4","level":"DEBUG","event":"graph_response","status":200,"items_count":50}
{"ts":"2026-01-24T10:30:01.345Z","correlation_id":"a1b2c3d4","level":"INFO","event":"command_complete","exit_code":0,"duration_ms":1222}
```

**Log Fields:**
| Field | Description |
|-------|-------------|
| `ts` | ISO 8601 timestamp with milliseconds |
| `correlation_id` | UUID linking all log entries for a single command invocation |
| `level` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `event` | Event type: `command_start`, `command_complete`, `graph_request`, `graph_response`, `cache_hit`, `cache_miss`, `retry`, `error` |
| `...` | Additional context fields vary by event type |

**Security:** Debug logs never contain tokens, secrets, or full UPNs. User identifiers are truncated (e.g., `j***@contoso.com`).

---

