wwtools/aalogcli/docs/usage.md

aalog — usage

Command surface for the aalog CLI. The tool reads AVEVA / Wonderware System Platform binary logs (*.aaLGX) under C:\ProgramData\ArchestrA\LogFiles (override with --log-dir).

Common options

Inherited by last, tail, range, and unread:

Option	Default	Notes
--log-dir <path>	C:\ProgramData\ArchestrA\LogFiles	Read from a copied-out log directory.
--component <pattern>	(none)	Substring match against Component. With --regex, treated as a regex.
--level <pattern>	(none)	Substring/regex against LogFlag (Info, Warning, Error, Trace, …).
--message <pattern>	(none)	Substring/regex against the message body.
--regex	off	Switch all three pattern options to regex (case-insensitive).
--llm-json	off	Emit the stable JSON envelope instead of human-readable lines.

Commands

aalog last

Most recent N records ending at now (or --until).

Option	Default	Notes
-n, --count <int>	50	How many records to return.
--until <iso>	now	ISO-8601 local time anchor for the end of the window.

aalog last                        # last 50, human readable
aalog last -n 200 --llm-json      # last 200, JSON envelope
aalog last --component aaEngine --level Error -n 100

aalog tail

Records from the last N minutes.

Option	Default	Notes
-m, --minutes <int>	10	Window length in minutes. Must be positive.
--max <int>	1000	Hard cap on records returned (keeps LLM payloads bounded).

aalog tail                                     # last 10 minutes
aalog tail -m 60 --level Error --llm-json      # last hour, errors only, JSON
aalog tail -m 5 --message "checkpoint failed" --regex

aalog range

Explicit start/end timestamps.

Option	Default	Notes
--from <iso>	(required)	Start timestamp, ISO-8601 local time.
--to <iso>	now	End timestamp, ISO-8601 local time. Must be later than --from.
--max <int>	1000	Hard cap on records returned.

aalog range --from 2026-05-03T08:00 --to 2026-05-03T09:00 --llm-json
aalog range --from 2026-05-03T14:30:00 --component "Galaxy" --level Warning

aalog unread

Incremental polling. Uses the upstream library's cache file (under %LOCALAPPDATA%\aaLogReader\ by default) to remember the last record ID seen, so successive invocations only return what's new.

Option	Default	Notes
--max <ulong>	1000	Maximum unread records to return.
--ignore-cache	off	Re-read regardless; the next call resumes from the new high-water mark.
--client-id <name>	(none)	Distinct cache files for parallel consumers.

aalog unread --llm-json                        # everything new since last call
aalog unread --client-id watchdog --max 200    # independent cache for this consumer

aalog fields

Print the LogRecord JSON field reference and exit. Same content as fields.md.

aalog fields

LLM-JSON envelope

When --llm-json is set, every read command writes a single JSON document to stdout:

{
  "query": {
    "command": "tail",
    "minutes": 5,
    "start": "2026-05-03T08:55:00",
    "end":   "2026-05-03T09:00:00",
    "max": 1000,
    "component": null,
    "level": "Error",
    "message": null,
    "regex": false,
    "log_dir": "C:\\ProgramData\\ArchestrA\\LogFiles"
  },
  "count": 3,
  "records": [
    {
      "MessageNumber": 18234021,
      "TimestampUtc":   "2026-05-03T13:59:42.117Z",
      "TimestampLocal": "2026-05-03T08:59:42.117",
      "Level":          "Error",
      "Component":      "aaEngine",
      "ProcessName":    "aaEngine",
      "ProcessId":      4128,
      "ThreadId":       6884,
      "SessionId":      "",
      "Host":           "PROD-AS-01.example.local",
      "Message":        "Galaxy connection timeout after 30000ms"
    }
  ]
}

Envelope guarantees

• query echoes every parameter that affected the result, including the resolved log_dir after --log-dir is applied. Agents can confirm scope without re-running the command.
• count == records.length.
• records is sorted newest first for last, tail, range, and unread.
• Field names in records[*] match exactly what aalog fields prints. Adding new fields is non-breaking; renaming or removing them is.

Tips for LLM use

• Cap aggressively. --minutes 60 --max 200 --level Error is more useful than dumping a thousand lines of Trace.
• Filter on Component first when chasing a specific subsystem (e.g. aaEngine, Bootstrap, aaGR). Levels alone are noisy.
• For follow-along debugging, prefer unread --client-id <agent-name> so each agent has its own cache.
• Pair with graccesscli mutations: run a graccess command, then aalog tail -m 1 --llm-json to read the resulting log activity.