Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
138 lines
4.9 KiB
Markdown
138 lines
4.9 KiB
Markdown
# 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. |
|
|
|
|
```powershell
|
|
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). |
|
|
|
|
```powershell
|
|
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. |
|
|
|
|
```powershell
|
|
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. |
|
|
|
|
```powershell
|
|
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`](fields.md).
|
|
|
|
```powershell
|
|
aalog fields
|
|
```
|
|
|
|
## LLM-JSON envelope
|
|
|
|
When `--llm-json` is set, every read command writes a single JSON document to stdout:
|
|
|
|
```json
|
|
{
|
|
"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.
|