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>
96 lines
5.1 KiB
Markdown
96 lines
5.1 KiB
Markdown
# aalogcli
|
|
|
|
A `.NET Framework 4.8 / x86` CLI for reading the AVEVA / Wonderware **System Platform** binary log files (`*.aaLGX`) — built on the [aaOpenSource/aaLog](https://github.com/aaOpenSource/aaLog) reader library and tuned for LLM-driven debugging (last N records, last N minutes, explicit time ranges, incremental "unread" polling, JSON envelope output).
|
|
|
|
## Hard constraints
|
|
|
|
- **Default log directory is `C:\ProgramData\ArchestrA\LogFiles`**, which only exists on a host running System Platform / Application Server. Override with `--log-dir <path>` when reading copied logs.
|
|
- **`lib/aaLogReader.dll` must be provisioned before building** — `aaLog` is not on NuGet. See [Provisioning aaLogReader.dll](#provisioning-aalogreaderdll).
|
|
- **Target framework is `net48`, platform `x86`** to match the upstream library and stay aligned with `graccesscli`. Do not retarget to .NET 10 / x64.
|
|
- **Filtering is post-fetch**, so `--component` / `--level` / `--message` narrow the result set the library returns; they do not push down into the binary scan.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
aalogcli/
|
|
AaLog.Cli.slnx
|
|
README.md this file
|
|
AGENTS.md agent guidance for working in this folder
|
|
lib/
|
|
aaLogReader.dll (not committed — see provisioning section)
|
|
src/AaLog.Cli/
|
|
AaLog.Cli.csproj
|
|
Program.cs
|
|
LogReaderFactory.cs
|
|
Commands/ last, tail, range, unread, fields
|
|
Output/ LogRecordDto, OutputWriter (human + llm-json)
|
|
Filtering/ post-fetch substring/regex filter
|
|
docs/
|
|
usage.md command surface, options, examples
|
|
fields.md LogRecord JSON field reference
|
|
```
|
|
|
|
## Resource index — by task
|
|
|
|
| Task | Go to |
|
|
| --- | --- |
|
|
| Agent rules for editing this CLI | [`AGENTS.md`](AGENTS.md) |
|
|
| Run the CLI / option reference / example invocations | [`docs/usage.md`](docs/usage.md) |
|
|
| `LogRecord` JSON field shape and types | [`docs/fields.md`](docs/fields.md) |
|
|
| Upstream reader library (license, source, build) | [aaOpenSource/aaLog on GitHub](https://github.com/aaOpenSource/aaLog) |
|
|
| LLM JSON envelope contract | [`docs/usage.md`](docs/usage.md#llm-json-envelope) |
|
|
|
|
## Provisioning `aaLogReader.dll`
|
|
|
|
The upstream library is GitHub-only, targets .NET 4.0, and ships with a legacy MSBuild `.csproj` plus a `packages.config` — none of which the modern .NET SDK 10 build pipeline restores cleanly. The recipe below rebuilds it as an SDK-style net48 project; this is the path that's been verified end-to-end on this repo.
|
|
|
|
If you have Visual Studio with full MSBuild + NuGet on PATH and prefer the upstream csproj as-is, that works too — just produce `aaLogReader.dll` somehow and drop it in `lib/`.
|
|
|
|
### SDK-style rebuild recipe (verified)
|
|
|
|
```powershell
|
|
# 1. Clone upstream sources somewhere outside this repo:
|
|
git clone https://github.com/aaOpenSource/aaLog.git $env:TEMP\aaLog
|
|
|
|
# 2. Create a sibling build folder with the SDK csproj from this repo's
|
|
# aalogcli/lib/build/aaLogReader.csproj template (see below).
|
|
mkdir $env:TEMP\aaLogReader-build
|
|
copy <wwtools>\aalogcli\lib\build\aaLogReader.csproj $env:TEMP\aaLogReader-build\
|
|
|
|
# 3. Two source files need a one-line patch — they reference [CallerMemberName]
|
|
# behind an #if NET45_OR_GREATER guard but never `using System.Runtime.CompilerServices;`.
|
|
# Copy the templates from this repo's lib/build/patched/ into a sibling folder:
|
|
mkdir $env:TEMP\aaLogReader-build\patched
|
|
copy <wwtools>\aalogcli\lib\build\patched\*.cs $env:TEMP\aaLogReader-build\patched\
|
|
|
|
# 4. Build and copy out:
|
|
cd $env:TEMP\aaLogReader-build
|
|
dotnet build -c Release
|
|
copy bin\Release\net48\aaLogReader.dll <wwtools>\aalogcli\lib\aaLogReader.dll
|
|
```
|
|
|
|
The csproj template sets `<Deterministic>false</Deterministic>` (the upstream `AssemblyInfo.cs` uses `[assembly: AssemblyVersion("1.0.*")]`) and pins `Newtonsoft.Json 13.0.3` / `log4net 2.0.15` to match what `aalog` itself uses, so there are no transitive-version conflicts at runtime.
|
|
|
|
`aaLogReader.dll` only needs to land in `lib/`. `Newtonsoft.Json.dll` and `log4net.dll` are pulled in via NuGet by `aalog` itself and end up next to `aalog.exe` automatically.
|
|
|
|
## Build & run
|
|
|
|
```powershell
|
|
dotnet build src/AaLog.Cli/AaLog.Cli.csproj -p:Platform=x86 -c Release
|
|
|
|
# Last 50 records, human readable:
|
|
dotnet run --project src/AaLog.Cli/AaLog.Cli.csproj -- last
|
|
|
|
# Last 5 minutes, error-level only, JSON envelope for an LLM:
|
|
dotnet run --project src/AaLog.Cli/AaLog.Cli.csproj -- tail --minutes 5 --level Error --llm-json
|
|
|
|
# Explicit range with regex message filter:
|
|
dotnet run --project src/AaLog.Cli/AaLog.Cli.csproj -- range --from 2026-05-03T08:00 --to 2026-05-03T09:00 --message "Galaxy.*timeout" --regex --llm-json
|
|
```
|
|
|
|
The built executable is `bin\Release\net48\aalog.exe` — drop it on `PATH` and use `aalog last -n 100`.
|
|
|
|
## Maintenance
|
|
|
|
This README follows the project doctrine in [`../DOCS-GUIDE.md`](../DOCS-GUIDE.md). When you add a command, an option, or a new field to the DTO, update [`docs/usage.md`](docs/usage.md) and [`docs/fields.md`](docs/fields.md) in the same change. The root [`../CLAUDE.md`](../CLAUDE.md) holds one row pointing at this README — it should not need to change unless the tool's task surface changes.
|