Logging

All VxSuite applications use the same framework to log user actions, application processes, and errors. The logs are persisted to disk and can be exported by election managers or system administrators.

Application Log Events

VxSuite applications use a shared logging library to capture required or otherwise important application log events. The core metadata for each application log event maps roughly to VVSG 2.0 standards, with some additional fields:

• Log Event ID - Internal identifier for each event. The full list of log event IDs with descriptions is included in the automatically generated log documentation.

• Log Event Type - Describes whether the event is a status update or an action, and whether it originated with the user, application, or larger system. The full list of log event types with descriptions is included in the automatically generated log documentation.

• User - If there was an authenticated user role at the time of a user action, describes the role as system_administrator, election_manager, poll_worker or vendor. If no user was authenticated, then unknown. If event does not originate from the user but rather automatically from the application or operating system, it will be system.

• Disposition - For actions that can fail or succeed, success or failure. Otherwise na for not applicable.

• Source - Indicates where in the system's architecture the log came from, whether it be the frontend renderer, the frontend server, the backend server, a hardware daemon, or the operating system.

• Message - The log message itself, which may not be present if the log event ID sufficiently describes the event.

• Other Metadata - Other metadata can be freely included. For example, if a user adds manual tallies on VxAdmin, the metadata of those manual tallies will be included in the logging.

• Time Written - Timestamp of when the log was created.

Log Management

The shared logging library formats the log events as JSON and pushes them to application processes' stdout. All stdout output from the application processes - both the application log events and any process output - is sent to the system's logger utility and assigned the tag votingworksapp.

VxSuite uses rsyslog, an advanced implementation of the Syslog protocol, to centralize and manage logs from votingworksapp and other sources. rsyslog has advantages over the built-in Linux syslog implementation of the Syslog protocol, including JSON structured messages, advanced filtering, and increased performance. Using rsyslog, different types of logs are directed to different log files in /var/log/votingworks/:

vx-logs.log is the most important and informative file in most cases. The other files rarely need to be referenced. All logs required by VVSG certification will exist in vx-logs.log.

Because each log file can grow very large, the application will rotate logs if necessary with the logrotate utility on each startup. Previous log files will be compressed and suffixed with a timestamp.

Including the various log files and log rotation, below is an example of the list of log files that might appear on a device:

/var/log/votingworks/vx-logs.log
/var/log/votingworks/vx-logs.log-20241104.gz
/var/log/votingworks/vx-logs.log-20241105.gz
/var/log/votingworks/auth.log
/var/log/votingworks/syslog
/var/log/votingworks/syslog-20241105.gz

Default VotingWorks Log Format

{
    "timeLogWritten":"2024-11-05T15:51:51.246232-08:00",
    "host":"VotingWorks",
    "source":"vx-scan-backend",
    "eventId":"auth-login",
    "eventType":"user-action",
    "user":"poll_worker",
    "message":"User logged in.",
    "disposition":"success",
}

The default VotingWorks log format is how logs are formatted when emitted from the application and how they appear in vx-logs.log. It is a direct mapping of the#application-log-events fields.

CDF Log Format

Logs can be exported in CDF format, in which case the vx-logs.log file is replaced by a vx-logs.cdf.json file with the logging attributes mapped as follows:

Error Logs

The log export flow exposed in all VxSuite applications also allows for exporting an errors-only version of the logs. This will only export a log file for logs where the disposition is "failure" and covers all software and hardware errors that have occurred on the machine.

15.1-D Logging Event Types Table

A full list of all logs made in the system with a description of each one can be found here. For convenience a table is provided below mapping Table 15-1 from VVSG 2.0 Requirement 15.1-D to the appropriate logs in the VotingWorks system. The details and descriptions provided in Table 15-1 have been simplified for brevity in this table. Some items have been expanded into multiple rows to more precisely specify linked logs.

General System Functions

Authentication and Access Control

Networking

Software

Voting Functions