# aalog — LogRecord field reference

The `--llm-json` envelope emits records of shape `LogRecordDto`, an LLM-friendly subset of the upstream [`aaLogReader.LogRecord`](https://github.com/aaOpenSource/aaLog/blob/master/aaLogReader/Types/LogRecord.cs) (declared in the bare `aaLogReader` namespace despite the file path). File-format internals (`RecordLength`, `OffsetToPrevRecord`, `OffsetToNextRecord`) and the redundant `EventDate` / `EventTime` / `EventMillisec` triple are dropped.

## Fields

| Field | Type | Source | Meaning |
| --- | --- | --- | --- |
| `MessageNumber`   | `ulong`  | `LogRecord.MessageNumber`     | Monotonic record id assigned by the logger. Stable across reads of the same log directory; useful as a cursor. |
| `TimestampUtc`    | `string` | `LogRecord.EventDateTimeUtc`  | Event time in UTC, ISO-8601 with `Z` suffix and millisecond precision (`2026-05-03T13:59:42.117Z`). |
| `TimestampLocal`  | `string` | `LogRecord.EventDateTimeLocal`| Event time in the host's local zone, ISO-8601 without offset (`2026-05-03T08:59:42.117`). |
| `Level`           | `string` | `LogRecord.LogFlag`           | Severity / category. Common values: `Info`, `Warning`, `Error`, `Trace`, `Debug`. |
| `Component`       | `string` | `LogRecord.Component`         | Originating subsystem (e.g. `aaEngine`, `Bootstrap`, `aaGR`, `aaIDE`). Best filter axis for narrowing scope. |
| `ProcessName`     | `string` | `LogRecord.ProcessName`       | Name of the OS process that emitted the record. |
| `ProcessId`       | `uint`   | `LogRecord.ProcessID`         | OS process id. |
| `ThreadId`        | `uint`   | `LogRecord.ThreadID`          | OS thread id within the process. |
| `SessionId`       | `string` | `LogRecord.SessionID`         | Session identifier; often empty. |
| `Host`            | `string` | `LogRecord.HostFQDN`          | Fully-qualified host name at time of emission. |
| `Message`         | `string` | `LogRecord.Message`           | Free-form message body. |

## Backward / forward compatibility

- **Adding a new field** to `LogRecordDto` is non-breaking. Agents that pin the existing field set continue to work.
- **Renaming or removing a field** is breaking. If it ever happens, bump this doc and the `--llm-json` example in [`usage.md`](usage.md) in the same change.
- The upstream library's underlying `LogRecord` may change shape across `aaLogReader.dll` versions. The CLI shields callers from that — only fields mapped explicitly in `LogRecordDto.From` ([`src/AaLog.Cli/Output/LogRecordDto.cs`](../src/AaLog.Cli/Output/LogRecordDto.cs)) reach the JSON envelope.

## Quick reference at runtime

```powershell
aalog fields
```

prints the same field list to stdout in plain text — useful when the caller can't load this file.