# Logging Attributes

When a user experiences a simulation, their data is recorded in our data logging pipeline. This document describes the structure of the data. 

## Definitions

The following terminology will be important for describing the structure of the logged data. 

* **Events** represent some logged occurrence at any point in time during a simulation. These events can be both user generated (e.g. "user grabs an object"), or system generated (e.g. "system loads a simulation"). Events are timestamped to the millisecond. 
* **User** is the one who experiences the simulation. Depending on how they access the simulation, their userID may be registered differently.
* **Session** begins when the user access the application and ends when the user leaves the application. A unique sessionID is generated per session.
* **Run** begins when the user loads a simulation and ends when the user leaves the simulation. 
* **Attributes** are key-values associated with specific events. For example, a "grab" event will have an attribute "targetObject" to indicate that a user "grabbed the targetObject'.

## List of Events and Associated Attributes

Below describe the list of events and the associated attributes that can appear in your Insights dashboard. 

<table data-full-width="false"><thead><tr><th width="226">Event Name</th><th width="237">Description</th><th>Important Attributes</th></tr></thead><tbody><tr><td>simulation_load</td><td>Simulation has completed loading</td><td><br></td></tr><tr><td>simulation_started</td><td>User has began the simulation </td><td><br></td></tr><tr><td>simulation_completed</td><td>User has completed the simulation</td><td><strong>timeToComplete</strong> (seconds)</td></tr><tr><td>trigger_event_Collide</td><td>Trigger has been activated involving two objects colliding with each other</td><td><p><strong>collided1</strong>: name of object that was collided</p><p><strong>collided2</strong>: name of object that was collided with</p></td></tr><tr><td>trigger_event_Grab</td><td>Trigger has been activated by grabbing an object</td><td><strong>grabName</strong>: name of object that was grabbed</td></tr><tr><td>trigger_event_Proximity</td><td>Trigger has been activated by moving onto a target position</td><td><p><strong>locationName</strong>: name of the target location</p><p><strong>radius</strong>: distance away from the center of target</p></td></tr><tr><td>trigger_event_Snap</td><td>Trigger has been activated by snapping an object into another</td><td><p><strong>snapHitboxName</strong>: name of the object that will hold the snapped object</p><p><strong>snapObject</strong>: name of the snapped object</p></td></tr><tr><td>trigger_event_SpeechReceived</td><td>Trigger has been activated by user speaking</td><td><br></td></tr><tr><td>trigger_event_Ungrab</td><td>Trigger has been activated by releasing a grabbed object</td><td>ungrabName: name of object that was released</td></tr><tr><td>trigger_event_Unsnap</td><td>Trigger has been activated by removing an object from a snapped position</td><td><p><strong>snapHitboxName</strong>: name of the object that held the snapped object</p><p><strong>snapObject</strong>: name of the removed snapped object</p></td></tr><tr><td>trigger_event_Use</td><td>Trigger has been activated by using an object</td><td><strong>useHitboxName</strong>: name of the object that was used</td></tr><tr><td>trigger_event_UseRelease</td><td>Trigger has been activated when no longer using the object</td><td><strong>useReleaseTargetName</strong>: name of the object that was used</td></tr><tr><td>state_machine_always_running_trigger_transition</td><td>Trigger (usually a user activated interaction/event) has been activated in the always running (global) state machine.</td><td><strong>triggerType</strong>: the trigger that caused the change in state machine</td></tr><tr><td>state_machine_always_running_condition_transition</td><td>Condition has been met causing an  activation in the always running (global) state machine.</td><td><p>The condition has been met in the format: </p><p><strong>[AttributeName] [Operator] [AttributeGoalValue]</strong></p><p></p><p>Example:</p><p>[ Count ] [ >= ] [ 10 ]</p></td></tr><tr><td>state_machine_transition_event</td><td>Transition between two states in the state machine</td><td><p><strong>fromState</strong>: name of state transitioned from</p><p><strong>toState</strong>: name of state transitioned to</p></td></tr><tr><td>state_machine_state_enter</td><td>Entered a state in the state machine</td><td><strong>state</strong>: name of state entered</td></tr><tr><td>state_machine_state_exit</td><td>Exited a state in the state machine</td><td><strong>state</strong>: name of state exited</td></tr><tr><td>general_user_utterance</td><td>User has produced an utterance by speaking or typing</td><td><strong>utterance</strong>: user’s transcript</td></tr><tr><td>gpt_chit_chat</td><td>User has activated GPT chit chat</td><td><p><strong>character.name</strong>: name of the character</p><p><strong>character.prompt</strong>: prompt supplied to GPT</p><p><strong>history.content</strong>: the conversation history</p><p><strong>response</strong>: gpt response</p><p>utterance: user’s transcript</p></td></tr><tr><td>quiz_multiple_question</td><td>Quiz question has been submitted</td><td><p><strong>question</strong>: the question that was asked</p><p><strong>questionChoices</strong>: list of choices</p><p><strong>selectedAnswers</strong>: answer selected by the user</p></td></tr></tbody></table>