Participant Audit Logs

Ethica Researcher Dashboard offers different aggregate reports on the data provided by each participant which you can use to monitor their adherence throughout the study. But when you find a case that you cannot explain using aggregated data, it's useful to dive deeper into the detailed interaction of the participant with their app and with your study. The data from Participant Audit Logs can be useful in such cases.

For example, if the compliance for a participant is low, or their reported data is not what you expected, or when you find any other discrepancy that cannot be explained by just looking at the aggregate data, you can identify one or more participants and investigate their participation in more depth using the Participant Audit Logs data.

In this section, we explain how you can access this data for your study and the type of information you can find in it.

Accessing the logs

We provide two ways for researchers to access Participant Audit Logs. These options mainly differ on the details and ease-of-use.

Using the Researcher Dashboard

The first option is the Participant Audit Logs page on Researcher Dashboard. Using this, you'll be able to list all logs related to the participants in a more familiar and user-friendly environment. Also, it only includes the most important attributes for each log.

To start, log in to your Researcher Dashboard. Then select Participant Audio Logs from the left panel. On this page, you can filter the logs based on Participants, Events, and the Date. You can list the logs even without filtering them. This way you'd see all the logs.

Participant Audit Logs page in Researcher
Dashboard

After you press the Go button, whether you applied any filter or not, the list will be displayed sorted by the Date in descending order, so you can see the latest events first. You can change this order by clicking on the arrow button beside the Date column title in the logs table.

If you have already selected a subset of participants or events and you decide to clear them all, you can easily mark the All Participants and All Events options as checked respectively. The same is true for Any Date if you wanted to clear the From and To date fields under Date filtering option.

Sometimes the content of a row in the logs table might be partially visible. For example, if your browser is not wide enough, you might find the Message content of some of the logs incomplete (ended with an ellipsis). To see the complete contents, you can simply click on its row. A dialog will be opened containing all the columns related to that log.

Participant Audit Log details dialog in Researcher
Dashboard

The logs table provides the following information for each log:

  • Date: the date/time this log was captured on the participant's device. The time is shown in your local timezone.
  • User ID: the ID of the participant who sent this log.
  • Message: the log message.
  • Device ID: the device ID from which this log was sent.
  • Event ID: the ID of the event related to this log. Below you can find the full description of the available event types.
  • App Version: the version of the Ethica app which sent this log.

Using Kibana

The second option is to use Kibana. This option is more complex than the previous one. Please refer to the article regarding Data Analysis with Kibana for more details on how to use Kibana. In this document, we only focus on Participant Audit Logs.

To start, select Kibana from the left panel in your Researcher Dashboard to open the Kibana's Discover page. On this page, you can directly connect to your study's database and query and explore the data. This page by default points to the participant_history data table, which stores the Participant Audit Logs:

Participant Audit Logs data table in
Kibana

Also, by default, this page only shows the data arrived within the past 15 minutes. Chances are your study has not received any data within this period and you will see an empty page, as shown in the image above. You can extend this time range through the time selection dialog on the top right corner of the screen. Here we extend the time range to access the data from the past 15 days:

Querying participant audit logs for the past 15
days

On the left side of the screen, you can see the data attributes that are stored for each audit log. Note that the fields starting with an underline (_) are for internal use. The audit log data fields include:

  • user_id: the ID of the participant who sent this log.
  • study_id: the ID of the study for which this log was sent. If you have multiple studies within Ethica, you may need to filter data based on study ID as well.
  • record_time: the time this log was captured on the participant's device. The time is shown in your local timezone.
  • event_type: the type of this log. Below you can find the full description of the available event types.
  • device_id: the device ID from which this log was sent.
  • app_version: the version of the Ethica app which sent this log.
  • message: the log message.
  • extra_params: any additional parameters sent as part of this log.

Clicking on any of the data fields will show the value from that on the main part of the page. For example, below you can see the logs for Participant ID #34,016 on Nov. 19th 2020:

Participant Audit
Logs

Type of Recorded Events

The following list shows all types of audit log events Ethica captures in the Participant Audit Logs. Each type of event has an associated numerical code as well which helps with querying and filtering the events. For example, if you are interested in survey-related interactions for participant #12192, you can search for the reports for User ID 12192 and event type between 300 to 399.

User Events

Event 1: User signed up.

Indicates the user joined the Ethica app.

Example report:

User signed up.

Event 2: User signed in.

Indicates the user signed into the Ethica app.

Example report:

User signed in.

Event 3: User signed out.

Indicates the user signed out of the Ethica app.

Example report:

User signed out.

App Events

Event 100: Application opened.

Indicates the participant opened the Ethica app on their device.

Example report:

Application opened.

Event 101: Application closed.

Indicates the participant closed the Ethica app on their device.

Example report:

Application closed.

Event 102: Study update started.

Indicates the app started to reload the study configuration to receive the most recent updates. Study update can be initiated for the following reasons, which will be included in the report:

  • The participant can explicitly start the process.
  • Ethica can automatically start it due to a previously failed try.
  • Ethica app has been updated and therefore the studies are also being updated.
  • Ethica server requested the app to update the studies. This is often because of the researcher implicitly or explicitly initiating this.
  • The permissions granted to the app have changed.
  • The timezone of the participant has changed.

Example report:

Study update started. Reason: app update.

Event 103: Study update succeeded.

This event indicates the study update finished successfully. It should come after an Event 102.

Example report:

Study update finished successfully, after 2 seconds.

Event 104: Study update failed.

This event indicates a failure in the study update process. It should come after an Event 102. The reason for the failure will be included in the report.

Example report:

Study update failed after 0 seconds.
Error: Could not download study registrations.

Event 105: Data sync started.

This event indicates Ethica started to upload collected data with Ethica servers. This event is reported when the participant explicitly requests a data upload. For automated data upload refer to Event 111.

Example report:

User started data sync.

Event 106: Data sync finished.

This event indicates Ethica finished uploading collected data to the servers. This should come after an Event 105.

Example report:

User-initiated data sync finished after 322 seconds and transferring
10938 KB data.

Event 109: Data sync failed.

This event indicates Ethica failed to upload collected data to the servers. This should come after an Event 105. The reason for the failure will be included in the report which can be one of the following:

  • An internal error happened.
  • User preferences prevented Ethica from uploading the data. For example, user preferences may require data upload on Wi-Fi only, while the user is currently on mobile Internet.
  • No Internet connection available.
  • Incomplete data upload. Not all data were uploaded successfully due to network issues.
  • Another upload process was in progress.
  • Network problems occurred.

Example report:

User-initiated data sync failed after 2.072 seconds and
transferring 0 KB data.
Error: No Internet connection available.

Event 111: Automatic data upload started.

This event indicates Ethica started to automatically upload the collected data.

Example report:

Automatic data upload started.

Event 107: Automatic data upload finished.

This event indicates Ethica completed automatically uploading all participant data to the servers. This event should be followed by an Event 111.

Example report:

Automatic data upload started at 2019-03-22 13:00:48 UTC and finished after
0 seconds, transferring 3 KB data.

Event 110: Automatic data upload failed.

This event indicates Ethica failed to automatically upload data. Note that Ethica periodically tries to upload all collected data to Ethica servers, and if a failure happens, the data will be held locally and Ethica will try again next time. The participant will not be aware of such failure.

The report will also include the reason for the failure. For details of the reason please refer to Event 109.

Example report:

Automatic data upload started at 2019-03-22 12:56:51 UTC and failed after
0 seconds, transferring 0 KB data.
Error: User preferences prevented data upload.

Event 112: Automatic survey resp upload started.

This event indicates Ethica started to upload survey responses. Note that this event is different from Event 111 as Ethica treats survey responses differently during the upload by giving them more priority. Therefore, if there is a network connection available, Ethica tries to upload the survey responses, regardless of the participant's preferences.

Example report:

Upload survey responses started.

Event 113: Automatic survey resp upload finished.

This event indicates Ethica completed uploading all survey responses to the servers. This event should be followed by an Event 112.

Example report:

Upload survey responses started at 2019-03-22 12:56:51 UTC and finished
after 2 seconds.

Event 114: Automatic survey resp upload failed.

This event indicates Ethica failed to automatically upload the survey responses. Note that Ethica periodically tries to upload all collected data and survey responses to Ethica servers, and if a failure happens, the data will be held locally and Ethica will try again next time. The participant will not be aware of such failure.

The report will also include the reason for the failure. For details of the reason please refer to Event 109.

Example report:

Upload survey responses started at 2019-03-22 12:56:51 UTC and failed
after 10 seconds.
Error: Network error.

Event 108: Timezone changed.

This event indicates the user changed their timezone. This will trigger a study update (reported by Event 102).

Example report:

Time zone changed from America/Toronto to America/Vancouver.

Survey Events

Event 200: Activity opened.

This event indicates the participant opened an activity to respond.

Example report:

Survey ID 982 opened.

Event 201: Activity closed.

This event indicates the participant closed an activity, without finishing it. Note that if a participant closes an activity, they can still come back and continue it later.

Example report:

Survey ID 982 closed.

Event 202: Activity finished.

This event indicates that an activity session is concluded, either because the participant completed responding to the activity, or it was expired, or the participant decided to cancel the activity.

Example report:

Survey ID 982 scheduled at 2019-03-22 01:00:00 UTC and prompted
at 2019-03-22 01:00:01 UTC was marked as expired.

Event 203: Beacon survey triggered.

This event indicates that a proximity-triggered triggering logic caused a survey to be triggered. The detail of the event leading to the survey trigger will be included in the event.

Example report:

Survey ID 982 issued because of beacon with Team 1027, Role 2,
Subject 10271, first seen at 2019-03-22 06:17:48 UTC,
departed at 2019-03-22 06:32:47 UTC.

Notification Events

Event 204: Notification prompted.

This event indicates that a notification is prompted for this study.

Example report:

    Notification #2 issued for session f7e5691a-b229-4bea-97d1-0a0ff315c037
    of activity #7001.

Event 300: Available notifications changed.

This event indicates the list of notifications for the current participant has changed. If a notification is added, it shows an issue was detected by the Ethica app and a notification was shown to the participant. If a notification is removed, it shows the previously reported issue was resolved and the associated notification is removed. The report also includes the list of the notifications currently on display for this participant.

The notifications reported here can be one of the following:

  • #1: Location permission not granted.
  • #2: GPS is disabled (Android).
  • #93: GPS is disabled (iOS).
  • #3: Wi-Fi is disabled.
  • #4: Bluetooth is disabled (Android).
  • #95: Bluetooth is disabled (iOS).
  • #5: Audio recording permission is not granted.
  • #7: App usage plug-in is not available.
  • #8: App usage access permission is not granted.
  • #9: SMS/Call logs data source is not set up properly.
  • #13: Phone number validation is required.
  • #14: Email address validation is required.
  • #91: Background GPS permission is not granted.
  • #92: Notification permission is not granted.
  • #94: Foreground GPS permission is not granted.
  • #96: Phone number validation is required, but not completed.
  • #96: Email validation is required, but not completed.

Example report:

Notification "GPS is disabled" is Added.

App Settings Events

Event 400: Study settings changed.

This event indicates that the participant modified the app settings. The report includes current app settings. The setting which is modified can be one of the following:

  • #1: Upload via Wifi Only.
  • #2: Upload when plugged.
  • #3: Rapid upload.
  • #4: Sticky notification (Android only).

Example report:

User checked "Upload via Wifi Only" setting.

Event 401: Data source status changed.

This event indicates that the user enabled or disabled a given data source in the app. This is only reported for optional data sources, where the user can enable or disable them.

Example report:

User enabled GPS data source.

Event 402: Data collection status changed.

This event indicates that the user paused or resumed the data collection.

Example report:

User paused data collection. Data collection will resume at 2019-03-22 06:17:48 UTC.

Bluetooth Beacon Events

Event 600: Beacon was observed

This event indicates that the user's smartphone observed a given Bluetooth beacon registered for this study.

Example report:

Beacon with Team ID 1, Role ID 1, and Subject ID 2 was observed
from 2019-03-22 06:17:48 UTC to 2019-03-22 06:27:48 UTC.