ci-server-engineer/.claude/skills/audit-trail/tasks/configure-audit.md

task	version	source	status
Choose what AUDIT Service stores (classifier STORAGE, AUDIT_INFO), define selection groups, run an event logger (ADTLOG)	R1.03	IM 36K10L25-01EN §2.4, §3, §4.2, App. 1; practiced on CI-Eng-Sample 2026-10-01	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.