Event logging

Event logging in Roundware is very useful for analysis of usage behaviors as well as debugging. Essentially, the goal is for all app interactions to be logged such that a full understanding of what happened during a particular session, or series of sessions, can be understood and analyzed at a later time.

Events are logged in one of two ways:

• directly by the python code
• via API call from the client

We try to get as much into the former category as possible, but some things require the latter, in particular things like client errors and the like.

Events are stored in the rw_event model with the following pieces of data (including optional* fields):

server_time
session_id
event_type
data*
latitude*
longitude*
tags*

Here is a list of the most frequently used event_types for api/1 (* indicates client-side reporting)

start_session
heartbeat
start_upload
stop_upload
start_record*
stop_record*
start_listen*
stop_listen*
move_listener
modify_stream
stop_session
cleanup_stream
client_error*

We will probably want to change some of these and add more for api/2:

modify_stream -> modify_tags
obtain_token
create_new_user
...

API call examples:

api/1

http://localhost:8888/api/1/?operation=log_event&session_id=1&event_type=modify_stream&latitude=1&longitude=1&tags=1,2,3

api/2

POST api/2/events/

Creates and logs a new event

Request Body Parameters:

• session_id - Required.
• event_type - Required
• client_time - Optional
• data - Optional
• latitude - Optional
• longitude - Optional
• tag_ids - Optional, comma delimited String of tag ids.

Listening History

We currently also log the listening history of each session allowing us to know what was heard and in what order. This is very handy for debugging as well as for eventual metrics on assets such as displaying "# of plays" for each asset. This data is in some ways simpler and different than the rw_event data, but is similar enough that it might be worth considering the possibility of combining the two.