Skip to main content

File-based audit logging

info

On-premises only — this feature is available only for on-premises installations of the iGrafx platform.

Overview​

The iGrafx platform can capture audit events to a local log file on the application server. The file-based audit feature writes one audit event per line in JSON Lines (JSONL) format to a file on the local file system — a self-contained, easy-to-ship record of platform activityActivity A named step in a process (e.g. "Approve Invoice"). Each event in an event log records one activity occurrence for one case..

Audit Settings controls what the platform records. At Audit successful logins only, it stores successful logins in the application database. At Audit on, it also records the full set of audit events — object changes, role and permission edits, server-setting changes, feature-flag toggles, and more — and, on an on-premises installation, writes them to the local log file.

A new on-premises installation starts at Audit off. To turn the feature on, select Audit on under Audit Settings; the platform starts writing with the next event, without a restart. To confirm it's active, check that the status chip beside Audit Settings reads Active.

For the structure of each individual audit event, see Enhanced auditing capabilities.

Where to find the files​

The platform writes audit events under the iGrafx base directory:

<igrafx.basedirectory>/auditlogs/
   auditevents.jsonl                              ← active file (currently being written)
   auditevents-<UTC-timestamp>.jsonl              ← rolled-over historical files
   …

The platform creates the auditlogs/ directory and an empty auditevents.jsonl when it starts on an on-premises installation, whatever the Audit Settings level; the file stays empty until Audit on is selected. The base directory is controlled by the igrafx.basedirectory JVM system property on your application server.

You can also export the recorded events as a JSONL file from the administration UI, without reading the log files — see Export audit events.

Rollover behavior​

When the active log file reaches 10 MB in size, the platform closes it, renames it with a UTC timestamp suffix (for example, auditevents-2026-05-01T23-45-00Z.jsonl), and starts a new empty auditevents.jsonl file. This is a rename-only operation — the platform doesn't delete, compress, or move rolled-over files off the server. The rollover threshold keeps individual files bounded in size and easy to process with downstream tooling, but the total number of files in auditlogs/ grows over time. Configure the threshold with the igrafx.auditing.localfile.maxsize.mb setting, as outlined in Advanced configuration.

If the platform is restarted while an active file is still under the rollover size, the new process appends to the existing auditevents.jsonl rather than starting a fresh file — restarts do not trigger rollover on their own.

Use cases​

  • Security information and event management (SIEM) and log-aggregator ingestion — point your existing log shipper (for example Fluent Bit, Logstash, or Splunk Universal Forwarder) at the auditlogs/ directory to flow audit events into a central security or observability platform without writing a custom integration.
  • Compliance retention — keep an append-only audit trail that lives outside the application database. Once a file rolls over, the platform never modifies it again, which makes the rolled-over files easy to copy into immutable retention storage.
  • Support and forensics — attach an audit file to a support ticket, or search the JSONL output directly to investigate a specific event window, without needing database access.

Operational considerations​

The total disk footprint of auditlogs/ grows with platform activityActivity A named step in a process (e.g. "Approve Invoice"). Each event in an event log records one activity occurrence for one case.. Instances with many users, frequent logins, or heavy content workflowsWorkflow An automated or semi-automated sequence of tasks that moves work from initiation to completion, often with routing rules and human-task assignments. will produce more rolled-over files. Because the platform doesn't delete, compress, or archive rolled-over files on its own, you're responsible for monitoring disk usage of the auditlogs/ directory and setting up an archival or pruning routine that matches your retention policy. Include free space on the volume hosting the iGrafx base directory in your server-health monitoring.

Related tasks & references​