--- task: Choose what AUDIT Service stores (classifier STORAGE, AUDIT_INFO), define selection groups, run an event logger (ADTLOG) version: R1.03 source: IM 36K10L25-01EN §2.4, §3, §4.2, App. 1; practiced on CI-Eng-Sample 2026-10-01 status: verified (PROCESS-side ITEM.* events from docs) --- # Configure the audit trail ## 1. Event classifiers — what is stored Each event type is a classifier `...` in `AUDIT_EVENT_CLAS_DF` (`NAME`, `SUBJECT`, `ATTRIBUTE`, `AGITATION` = action, `SOURCE`, `BASIC_SET`, `STORAGE`). Only `STORAGE` can be changed. Configuration and DSS value changes use subject `DATASET` with attribute `NULL-ATTR`, e.g. `DATASET.NULL-ATTR.MODIFY.LOC-ENG-MOD` (Engineering Module) or `….ENT-ENG-MOD` (`dssqld`); logins use `CI-SERVER.NULL-ATTR.LOGIN.`. List the classifiers (and which are off): `dssqld -e ecl.qlo -d AUDIT_EVENT_CLAS_DF`. Change: ``` @FIELDS NAME,STORAGE @AUDIT_EVENT_CLAS_DF "...",0 ``` `dssqld -m`, or in the Engineering Module *Configuration › Audit trail › Event classifiers* (the change itself is audited: `AUDIT_EVENT_CLAS_DF` `STORAGE` `MODIFY`). **Not immediate:** the processes that report events (e.g. `DSSSDA`) cache the storage flags and re-read them every `ECL_REFRESH` seconds (default 1800). Verified: a classifier switched off was still recorded right after the change and no longer 31 minutes later; switching it back on is delayed the same way. Allow up to 30 minutes or restart CI Server (ISS-050). Confirm with the user before switching anything off. ### Item option *Audit trailing wanted* (`AUDIT_INFO`) `ITEM_DF` / `SUB_ITEM_DF` / `EXTERNAL_ALARM_DF` field `AUDIT_INFO` (default 0). It switches the `ITEM.*` / `SUB-ITEM.*` events raised by ITEM Service for **operator writes**. Verified on `CI-Eng-Sample.PUMP1.MODE` with the buttons on display `CIENG_Tank` (2026-10-01; re-checked 2026-10-06 with *Manual* / *Auto* on `CIENG_Control`: same events, user and old / new value): - `AUDIT_INFO` 1: a button write 0 → 1 stored `ITEM` `VALUE` `MODIFY` `OPER-INTERFACE`, user `ADMIN`, old 0 / new 1, plus `ITEM` `STATUS` `MODIFY` (13 → 9). - `AUDIT_INFO` 0: the write 1 → 0 left **no** audit record. It does not affect DSS writes (`dssqld`, Engineering Module: always audited as `ITEM_VAL` dataset events) or `itmval -p` (never audited). Sample: `19b_audit_item_df.qli` (`dssqld -m`, `NAME,AUDIT_INFO`). PROCESS writes (`COMPUTE`) also need `AUDIT = YES` in `tls\sup\opc.sup` (installed `NO`) and their classifiers are off by default; not tested. ## 2. Selection groups A selection group is a named, compiled filter for an AUDIT destination (`ADTLOG`, the chronological overview). Dataset `AUDIT_SELGRP_DF`: `NAME` (≤ 32), `DESCRIPTION`, `EXPRESSION` (memo), `COMPILE` (1 = compile now), `LISTING` (compiler output), `VALID_EXPRESSION`. Expression language (from the compiler's own listing): - Words compared with a **string**: `aai1 acnd acnm actm mai1 nond nonm reas sacs sact satr sbgp sbid term user` (same meaning as the `E_LAYOUT` units in §4: `sbgp` subject, `satr` attribute, `sact` action, `sacs` source, `sbid` subject id, `user` …). - Words compared with a constant: `nval oval` (new / old value). - Operators `= != > < >= <=`, `and`, `or`, parentheses. **No `LIKE`**: match a name prefix with a range, e.g. `sbid >= "
." and sbid < "
/"` (`/` sorts right after `.`). Example (`examples/CI-Eng-Sample/19_audit_df.qli`): ``` @FIELDS NAME,DESCRIPTION,EXPRESSION,COMPILE @AUDIT_SELGRP_DF "CIENG_ITEMS","Audit events on CI-Eng-Sample",@" sbid >= "CI-Eng-Sample." and sbid < "CI-Eng-Sample/" "@,1 ``` `dssqld -i`. Write the memo **over several lines** (`@"` newline … newline `"@`): on one line `@""@` is taken as a file name (`CRL-E-EINVAL` / `CRL-E-ENOENT`). Check: export the dataset — `LISTING` ends with `ADTT-I-CMP_SUCC, Expression successfully compiled` and `VALID_EXPRESSION` is 1. An error (e.g. `ADTT-E-UNKNOWN_TOK`) makes the `dssqld` line fail with `ADTT-E-CMP_NO_SUCC` and leaves `VALID_EXPRESSION` 0. Remove with `dssqld -r` (`NAME` only). ## 3. Event logger `ADTLOG` `adtlog -n ` connects to `ADTSTO` and prints each new event as text (stdout, or the printer in `PRT_DEV`). It is not started by default (`audit_start.cmd` has it commented out; `fmfprt.sup` assigns the printer function `AUDIT_TRAIL` to `ADTLOG`). A process reads `tls\sup\.sup`, so one setup file per logger instance. Without a setup file the default layout is three lines per event (time with milliseconds, subject, attribute, action, source / subject id, user / old and new value). Verified test: `adtlog -n adtlogt` in a console, then a value write — the logger printed the `LOGIN`, the `ITEM_VAL` change and the `LOGOUT`. A console logger runs until stopped: Ctrl+C, or `durstp -m -p ` (skill `system-management`, `bus-utilities.md`). Filtered logger: `examples/CI-Eng-Sample/audit/adtlogci.sup` (`SEL_GROUP = "CIENG_ITEMS"`, one-line `E_LAYOUT`, `TIMEFMT`, `HEADER`, `HEADER_AFTER`). The user copies it to `%TLS_ROOT_PATH%\tls\sup\` (admin); then `adtlog -n adtlogci` printed only the CI-Eng-Sample changes (no logins), one line each under the header. If the selection group does not exist or did not compile, the logger logs an error and exits. To run it permanently, add a `start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\adtlog -n ` line to `audit_start.cmd` (admin, restart). ## 4. Setup keywords (`adtsys.sup` is the template) `MAX_OPEN_UNITS` (20), `PRT_DEV`, `QUESIZE` (kB), `SEL_GROUP`; `COL_PROC`, `DST_PROC`, `HIS_PROC`, `STO_PROC` = `, `; `NODE_ECL_FILE`, `NODE_SGP_FILE`; `E_LAYOUT = ,,…` (`AAI1 ACND ACNM ACTM MAI1 NOND NONM NOTM NVAL NWLN OVAL REAS SACS SACT SATR SBGP SBID SPCE TERM USER`), `E_NOSPACE`, `TIMEFMT` (`DD/MM/YY hh:mm:ss.ppp` default — milliseconds shown, as the manual says); `ECL_REFRESH` (1800 s), `FLOWC` (30, 10), `HBEAT` (10), `TRYCON` (10); `FORM_FEED`, `HEADER` (repeat for more lines), `HEADER_AFTER` (re-print after n events; the header is also printed once at start). Which keyword applies to which process: L25 §4.2.2. ## 5. Retention Audit records live in history storage group `ADT` (rollover 1 day; lifetime 52 weeks on the test system). Longer/shorter retention = change `LIFE_TIME` of `ADT` (skill `history-management`); archive like any storage group. Ask before shortening it.