---
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 (operator-side ITEM.* value events from docs, ISS-049)
---

# Configure the audit trail

## 1. Event classifiers — what is stored

Each event type is a classifier `<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>` 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.<source>`.

List the classifiers (and which are off): `dssqld -e ecl.qlo -d AUDIT_EVENT_CLAS_DF`. Change:

```
@FIELDS
NAME,STORAGE
@AUDIT_EVENT_CLAS_DF
"<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>",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). In the test a switched-off classifier was
still recorded right after the change (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 did **not**
change what the tested tools record: DSS and Engineering Module value writes are audited for all
items, `itmval -p` for none. It is meant for the `ITEM.*` / `SUB-ITEM.*` classifiers (value,
status, limits) raised by ITEM Service for operator and PROCESS writes; PROCESS (`COMPUTE`) also
needs `AUDIT = YES` in `tls\sup\opc.sup` (installed `NO`) and its classifiers are off by default.
Not verified (ISS-049).

## 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 >= "<Section>." and sbid < "<Section>/"` (`/` 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
`@"<text>"@` 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 <name>` 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\<name>.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 <name>` (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 <name>` 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>, <name>`; `NODE_ECL_FILE`, `NODE_SGP_FILE`; `E_LAYOUT = <unit>,<width>,…`
(`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.