Collect Audit Records¶

Collect TestGen's audit records into your log management tools to review who signed in, who changed access, and who changed configuration, tests, and findings.

TestGen writes a record of each security-relevant action, such as a user signing in, a change to who can access a project, or a change to a connection, to a dedicated audit file.

Find the audit file¶

The audit file is audit.log, in the same directory as the application log. Each line is one record, as a JSON object. Records are written only to this file: they do not appear in the application log or on standard output.

DockerPipKubernetes

The file is at /var/lib/testgen/log/audit.log inside the engine container, on the testgen_data volume, so it survives a restart. To read it from the directory that contains the docker-compose.yml file:

docker compose exec engine tail -f /var/lib/testgen/log/audit.log

The file is at ~/.testgen/log/audit.log.

The file is at /var/lib/testgen/log/audit.log inside the TestGen pod. The chart mounts no volume there, so the file is lost whenever the pod is replaced. To keep it, mount a persistent volume at /var/lib/testgen/log with extraVolumes and extraVolumeMounts, and set podSecurityContext.fsGroup: 101 so that the container user can write to it. See the Values reference.

The file is rotated at midnight. Earlier days are kept as audit.log.YYYY-MM-DD for 90 days by default. Configure your log collector to follow audit.log, so it reads each record once.

Change audit settings¶

Audit records are written by default. To turn them off, or to keep more or fewer days of files, set these environment variables. See Set Environment Variables.

Variable	Default	Purpose
`TESTGEN_AUDIT_LOG_ENABLED`	`yes`	Set to `no` to stop writing audit records.
`TESTGEN_AUDIT_LOG_MAX_QTY`	`90`	Number of daily audit files to keep.
`TESTGEN_LOG_FILE_PATH`	`/var/lib/testgen/log`, or `~/.testgen/log` for a pip install	Directory of both the application log and the audit file.

Read audit records¶

Who acted¶

Identify users by actor_id, which never changes. actor_username and actor_display_name can change over time.

A run started by a schedule has no acting user: source is scheduler, and cause_type and cause_id name the schedule. A profiling run that starts after a new table group's setup steps is recorded as started by the user who created the table group.

What one record covers¶

An action on several objects at once, such as locking a selection of tests, writes one record for each project, with the number of objects in target_count.
Deleting an object writes one record, for that object. What is deleted with it, listed with its action in Actions, gets no record of its own, except project memberships.
Project access is recorded once for each user and project, with the user as the target and the project in project_code. When a user or a project is deleted, each project the access ended on gets its own project.member_removed record, with the deleted user or project in cause_type and cause_id.

What is not recorded¶

Changes that runs make: tests that test generation creates or updates, a test that a test run turns off because it can no longer run, and monitors that profiling or a monitor run adds or removes.
Monitor runs.
Runs started from the CLI.
Runs deleted with their table group, test suite, connection, or project, or by data retention.
Changes to a contract's tests and versions: importing a contract document, editing its metadata, freezing a version, discarding a draft, moving a test into or out of a contract, and copying a test into a contract. A copy out of a contract is recorded as test_definition.created in the test suite it is copied to. Creating and deleting a contract are recorded, as test_suite.created and test_suite.deleted.

Reference¶

Record fields¶

Every record carries the same fields; a field that does not apply to an action is null, or empty for targets and changes.

Field	Content
`schema_version`	Version of the field set: `1`.
`id`	Unique ID of the record.
`occurred_at`	When the action happened, as an ISO 8601 UTC timestamp.
`action`	What was done, as `<entity>.<verb>`. See Actions.
`outcome`	`succeeded` or `failed`.
`actor_id`	Permanent ID of the acting user. `null` when the system acted, or when a sign-in failed. See Who acted.
`actor_username`	Username of the acting user. For a failed sign-in, the username that was entered.
`actor_display_name`	Display name of the acting user.
`source`	Where the action came from: `ui`, `api`, `mcp`, `cli`, `scheduler`, or `system`.
`project_code`	The project the action belongs to, where one applies.
`target_type`	The kind of object affected.
`target_count`	How many objects were affected.
`targets`	IDs of the affected objects, at most 100.
`target_name`	Name of the affected object, when exactly one was affected. A schedule or notification is named for what it covers, such as `Profiling of Sales` or `Test run notification for Sales Tests`.
`cause_type`, `cause_id`	The object that caused the action, such as a schedule, or the user or project whose deletion removed a project member.
`changes`	Changed fields, each as `{"from": ..., "to": ...}`. Fields use their stored names, such as `lock_refresh`, which can differ from the labels in the UI.

A record is written only when the change it describes is saved. A failed action, such as a sign-in with a wrong password, is recorded at once with the outcome failed.

changes lists only the fields whose saved value changed, so saving a form without changing anything writes no record. A new object lists the values it was created with, without from. Secret values, such as passwords, are listed as changed, without the values.

Records with the same id are the same event, for example when a file is collected twice, so deduplicate on id. Fields can be added without a change to schema_version. Existing field names and meanings do not change.

Actions¶

Action	Recorded when
`user.signed_in`	A user signs in to TestGen, in the UI or to authorize an application. A failed attempt is recorded with the outcome `failed`.
`user.signed_out`	A user signs out of the TestGen UI or the TestGen sign-in page.
`oauth_client.authorized`	An application, such as an AI assistant, receives access to TestGen on a user's behalf after the user authorizes it. `changes` holds `expires_in`: the access lasts that many seconds from `occurred_at`, unless it is revoked earlier.
`oauth_client.access_revoked`	An application gives up access before it expires, for example when it disconnects. The actor is the user who had granted it. Access that expires, or that TestGen revokes because a refresh token was reused, ends without this record.
`project.updated`	A project's settings change. `target_type` names the section that changed: `project.info` for its name and score weighting, `project.observability` for its export to DataOps Observability, or `project.retention` for its data retention.
`connection.created`	A connection is created, on its own or together with its first table group. Credentials are listed as changed, without their values.
`connection.updated`	A connection's settings change, including its connection type and its credentials, which are listed as changed without their values.
`table_group.created`	A table group is created. The test suite, schedule, monitor suite, and scorecard created with it each get their own record.
`table_group.updated`	A table group's settings change, including PII or critical data element detection turned off when a Data Catalog edit or a metadata import sets those flags by hand.
`table_group.deleted`	A table group is deleted, with its test suites, monitors, schedules, notifications, runs, results, and data catalog.
`test_suite.created`	A test suite is created.
`test_suite.updated`	A test suite's settings change.
`test_suite.deleted`	A test suite is deleted, with its tests, runs, results, schedules, and notifications.
`monitor_suite.created`	Monitoring is turned on for a table group. `changes` holds the monitor settings and the schedule.
`monitor_suite.updated`	A table group's monitor settings, or the timing of its monitor schedule, change.
`monitor_suite.paused`	A table group's monitor schedule is paused, so its monitors stop running.
`monitor_suite.resumed`	A paused monitor schedule is resumed.
`monitor_suite.deleted`	A table group's monitors are deleted, with their history and their schedule.
`schedule.created`	A profiling or test run schedule is created. `changes` holds the job it runs and the table group or test suite it runs for.
`schedule.updated`	A schedule's timing changes.
`schedule.paused`	A schedule is paused.
`schedule.resumed`	A paused schedule is resumed.
`schedule.deleted`	A schedule is deleted.
`notification.created`	A notification is created.
`notification.updated`	A notification's settings or recipients change.
`notification.paused`	A notification is paused, so it stops sending.
`notification.resumed`	A paused notification is resumed.
`notification.deleted`	A notification is deleted.
`notification_destination.created`	A notification destination, an email list or a webhook, is created. A webhook's URL and authorization header value are listed together as `secrets`, changed without the values.
`notification_destination.updated`	A notification destination's settings change.
`notification_destination.deleted`	A notification destination is deleted, with the notifications that send to it.
`scorecard.created`	A scorecard is created, on its own or with a table group. `changes` holds its filters as `criteria`.
`scorecard.updated`	A scorecard's settings or filters change.
`scorecard.deleted`	A scorecard is deleted.
`profiling_run.launched`	A profiling run is started, by a user or by a schedule.
`profiling_run.paused`	A user pauses a profiling run.
`profiling_run.resumed`	A user resumes a paused profiling run.
`profiling_run.canceled`	A user cancels a profiling run.
`profiling_run.deleted`	A user deletes profiling runs, with their results. A run that has not finished is canceled first; only the deletion is recorded.
`test_run.launched`	A test run is started, by a user or by a schedule.
`test_run.canceled`	A user cancels a test run.
`test_run.deleted`	A user deletes test runs, with their results. A run that has not finished is canceled first; only the deletion is recorded.
`test_definition.created`	A test is added, copied, or imported from a test definition file.
`test_definition.updated`	A test changes. `target_type` names what changed: `test_definition` for its settings, `test_definition.state` for its lock and its flag, or `test_definition.placement` when it moves to another test suite.
`test_definition.enabled`	A test is turned back on, so test runs include it again, including when one of its test results is confirmed, dismissed, or cleared. Those also unlock the test, recorded as `test_definition.updated`.
`test_definition.disabled`	A test is turned off, so test runs skip it, including when one of its test results is muted. Muting also locks the test, recorded as `test_definition.updated`.
`test_definition.deleted`	A test is deleted: by a user, by an import that removes the tests its file leaves out, or by copying or moving tests over it.
`monitor.created`	A metric monitor is added to a table.
`monitor.updated`	A monitor's settings change, including its thresholds.
`monitor.deleted`	A metric monitor is deleted.
`test_result.updated`	A test result's disposition changes. `changes` holds `disposition`: `Confirmed`, `Dismissed`, `Inactive` (shown as Muted), or `null` when cleared.
`hygiene_issue.updated`	A hygiene issue's disposition changes. `changes` holds `disposition`, with the same values.
`catalog_table.updated`	A table's metadata in the data catalog changes, edited or imported: its description, critical data element flag, or tags.
`catalog_column.updated`	A column's metadata in the data catalog changes, edited or imported: its description, critical data element, excluded data element, or PII flag, or its tags.

Additional actions Enterprise¶

The enterprise version also records these actions.

Action	Recorded when
`user.created`	An administrator adds a user, or a user signs in with single sign-on for the first time.
`user.updated`	A user's name, email, or password changes, including a change that single sign-on brings at sign-in.
`user.deleted`	An administrator deletes a user, which also revokes their personal access tokens and their applications' access. `target_name` holds the user's username at the time.
`user.admin_granted`	A user is made a global administrator, by an administrator or by single sign-on, including a user created as one.
`user.admin_revoked`	A user stops being a global administrator.
`project.member_added`	A user is added to a project. `changes` holds the role.
`project.member_role_changed`	A user's role in a project changes. `changes` holds the previous role and the new one.
`project.member_removed`	A user is removed from a project, including when the user or the project is deleted.
`access_token.created`	A user creates a personal access token. The token itself is never recorded.
`access_token.revoked`	A user revokes a personal access token.
`setting.updated`	An administrator changes a system setting. `target_name` holds the setting's key.
`project.created`	An administrator creates a project. `changes` holds its name and its data retention settings.
`project.deleted`	An administrator deletes a project, with everything in it. `target_name` holds the project's name at the time.
`connection.deleted`	A connection is deleted, with its table groups and everything in them.

Examples¶

The examples are formatted for reading. In the file, each record is on a single line.

A successful sign-in:

{
    "schema_version": 1,
    "id": "3f0c2b9e-6a51-4c1e-9d3a-2e7b8f40a1c5",
    "occurred_at": "2026-10-16T16:58:02.412207+00:00",
    "action": "user.signed_in",
    "outcome": "succeeded",
    "actor_id": "8a1e4c7d-2b90-4f3e-a6d5-91c0e7b3f248",
    "actor_username": "jdoe",
    "actor_display_name": "Jane Doe",
    "source": "ui",
    "project_code": null,
    "target_type": null,
    "target_count": 0,
    "targets": [],
    "target_name": null,
    "cause_type": null,
    "cause_id": null,
    "changes": {}
}

An administrator changing another user's role in a project:

{
    "schema_version": 1,
    "id": "b71d0a4e-93c2-4f68-8e15-6c2a9d7f3e01",
    "occurred_at": "2026-10-16T17:04:41.903512+00:00",
    "action": "project.member_role_changed",
    "outcome": "succeeded",
    "actor_id": "8a1e4c7d-2b90-4f3e-a6d5-91c0e7b3f248",
    "actor_username": "jdoe",
    "actor_display_name": "Jane Doe",
    "source": "ui",
    "project_code": "SALES",
    "target_type": "user",
    "target_count": 1,
    "targets": ["5c9e2f17-0b4a-4d83-a2e6-71f8c3d90b42"],
    "target_name": "asmith",
    "cause_type": null,
    "cause_id": null,
    "changes": {"role": {"from": "business", "to": "data_quality"}}
}