Everything Else
Helix Logs and How to Locate Them

Helix 6.2 and later have many logging options that capture a record of activities. These semi-permanent log files are useful for troubleshooting, security audits, and other purposes.

Helix stores all logs in a common location, based on macOS standard guidelines. The exception to this is the crash logs, which are created by macOS itself. For more information on locating crash logs, see this page.

Viewing Helix Log Files

All Helix generated log files are stored in the user’s ~/Library/Logs/ folder, in a folder named ‘Helix’ (naturally). Helix log files are stored in plain text, so you can open them with any text editor, or (typically) double-click them to read then in the macOS Console application.

Using the Console application is the easiest way to access these files. The image on the right shows the Helix logs in the console viewer, with the Helix Utility (HU) log selected and displayed. In the sidebar on the left you can also see the Structure Check (SC) log and the User Access log.

Selecting a file in the sidebar displays its contents. Right-clicking (or choosing the File menu) shows options to reveal the file in the Finder, move the file to the trash, and even to create an email message with the file pre-attached.

Because these log files can accumulate data over time, they can potentially grow quite larger. It may be beneficial to periodically delete these files, but with today’s capacious hard drives, there is no harm in allowing them to grow indefinitely.

Although there are cosmetic differences between versions, Console’s functionality is essentially the same across all versions of macOS.

Helix Log Files
Structure Check Log

When a collection is opened, saved, or closed, an automatic structure check is performed, to ensure the structural integrity of the collection. The results of this check are written to the Structure Check Log, which is named using the prefix SC_ followed by the name of the collection itself.

This log is reset after each check. To switch it to maintain a record of previous checks, set the HxSCAppendLog preference to true. (See Editing Preferences for details on changing preferences.)

In addition, the HxSCMaintenanceDetails preference enables the SC log to include additional information about the icons that require maintenance. (The HxSCShowResourceCounts preference enables the SC log to include a count of every object type in the collection, which is mostly just a curiosity.)

Beginning in Helix 6.2.4, the structure check log has been extended to include information on how the save was invoked, which Helix application (and version) was being used, and whether maintenance was actually done.

Helix Utility Log

When Helix Utility is used to perform any function on a collection, the activity is written to the Helix Utility Log. This file is named using the prefix HU_ followed by the name of the collection itself.

All activities that appear in the Activity Log panel are logged, and the detail of the log matches the detail shown in the main window. Therefore, to capture the full scope of information available, be sure to turn the ‘Detailed Logging’ option on in the main window.

This is a cumulative log, maintaining a record of previous checks. There is no preference setting to change this.

User Access Log

The User Access Log is replaces and enhances the “Client Information” window, writing the access details to a file, so they are not lost when the application quits. This log records the following events:

  • Application launch & quit
  • Collection open & close
  • Data access actions (optional; see below)
  • Helix Client connections, disconnections & refusals
  • AppleScript Design Mode login & logout
  • Data access via Apple event

The User Access Log is turned off by default, and is enabled via the HxUserAccessLogging preference. (See Editing Preferences for instructions.)

Unlike the Structure Check and Helix Utility logs, which log data per collection, the User Access log data is captured per application. Each application creates a folder within the ~/Library/Logs/Helix/ folder into which a single useraccess.log file is written. (This preference has no effect on Helix Client.)

The User Access Log can optionally log specific data actions which provide the ability to create a general audit trail as well as provide useful debugging aids. The specific actions that can be logged are:

  • HxAccessLogAdd: Log the relation name and record ID of newly created records.
  • HxAccessLogDelete: Log the relation name and record ID of deleted records.
  • HxAccessLogReplace: Log the relation name and record ID of updated (replaced) records.
  • HxAccessLogPost: Log the beginning and ending of post actions by type (add, delete, replace, export, print), along with the relation name and record ID of affected records.
  • HxAccessLogLock: Log the relation name and record ID of records locked, along with an internal locking key. Also log the unlocking of those records.

Each entry also logs the ‘Seat#’ of the Client that generated the action, making it possible to identify exactly which user was involved. (Apple event accesses are logged as ‘-1’.)

In addition to the events noted above, Helix RADE and Engine can also log the following:

  • HxAccessLogSequence: Log the beginning and ending of a sequence.
  • HxAccessLogSequenceStep: Log each step of a sequence.

The Helix Preference Editor has been updated to provide an easy method for turning these on and off.

Debugging Logs

When working with QSA ToolWorks to isolate a bug in Helix, you may be requested to activate the debugging logs…

The HxWriteDebugData preference causes Helix to log data to the macOS system log. Special debug versions of Helix can be created to capture data this way, on an as needed basis. There is no reason to activate this preference unless you are working directly with QSA ToolWorks to isolate an issue.

The HxWriteDebugFile preference causes Helix to create a file (on the user’s desktop) containing specific debugging information. Currently the information captured by this log is primarily related to Client/Server interaction, but additional data may be captured on an as needed basis. Note: activating this preference causes Helix Server to run much slower than normal, and the file created can become huge in a very short amount of time. Do not activate this preference unless you are working directly with QSA ToolWorks to isolate an issue.