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/:

Log File

Contents

vx-logs.log

Key logs required by VVSG 2.0 or otherwise critical for understanding the behavior of the application or device, including:

all application log events
USB device connection events
machine boot and shutdown events
all sudo actions
password events
dm-verity events

auth.log

All operating system authentication-related events. Note that this will not include voting system authentication events such as logging in with a smart card - these events are in vx-logs.log

syslog

All other events emitted from the application or the operating system that do not fall into the other log files.

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 theApplication 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:

CDF Attribute

ElectionEventLog.GeneratedTime

ISO formatted timestamp of when logs were exported

ElectionEventLog.Device

List containing only the current device

Device.Type

The CDF DeviceType matching the type of machine:

VxAdmin -> "ems"
VxScan -> "scan-single"
VxCentralScan -> "scan-batch"
VxMark -> "bmd"

Device.Id

The serial number of the device

Device.Version

The software version e.g. "v3.1.2"

Device.Event

List of all events

Event.Id

A VotingWorks defined identifier for the type of event, such as "save-election-package-complete"

Event.Disposition

"success", "failure", "na", or "other"

Event.OtherDisposition

If the disposition is "other", the details appear here

Event.Sequence

The index of the log in the list of logs, zero-indexed

Event.TimeStamp

ISO formatted timestamp of when the event was logged

Event.Type

Log event type

Event.Description

Log message

Event.Details

JSON including the log source and any additional logging metadata

Event.UserId

The user at the time of the log

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

System Event

Detail

Logging Details

Device generated error and exception messages

Errors can be logged with any LogEventId but are indicated by a Disposition of failure. All logs contain a Source. Every error is logged when it occurs and each log can be assumed to correspond to one instance of that error occurring unless otherwise stated in the log. VxScan violations of physical security include scanner cover open logs: scanner-state-machine-event

scanner-state-machine-transition VxScan violations of physical security include scanner cover open logs: mark-scan-state-machine-event

paper-handler-state-machine-transition