Lack of documenation on working_time metrics of Analytics

[PMazarovich]

Actions before raising this issue

• I searched the existing issues and did not find anything similar.
• I read/searched the docs

Is your feature request related to a problem? Please describe.

It is impossible to understand what working_time means without going to the code or without analyzing explicitly the log events.
It is necessary to document how it is calculated. What is the "duration" of some event types etc.

Describe the solution you'd like

Here is the small summary of how I understand the working_time:

UI collects the "events" when user interacts with buttons etc.
The structure of one single record in the event series described here
2.1 Each record has it's own timestamp
2.2 Some records has a duration
UI sends the message with the series of events by 3 triggers:
3.1. When user click "Save"
3.2 When user loads the job
3.3 Periodically by timer
When the "events" message (you can find it in Network page in your browser if needed) arrives, server calculates the working time and updates the payload with the calculated working_time.

Here is the example of how this working_time is calculated.

If you go from the bottom to the top you'll see the first event with working_time 0. Second one is the timestamp of the first - the timestamp of the current event. Third is the second timestamp - current timestamp (third one) etc.

working_time, timestamp, event
0.355 2024-04-28T18:06:46.099Z drag:object
0.392 2024-04-28T18:06:45.744Z drag:object
0.451 2024-04-28T18:06:45.352Z drag:object
0.497 2024-04-28T18:06:44.901Z drag:object
0.593 2024-04-28T18:06:44.404Z drag:object
0.565 2024-04-28T18:06:43.811Z drag:object
0 2024-04-28T18:06:43.246Z drag:object

There are some events that has a duration field. 2 of them are change:frame and save:job.

Working_time for these types is: duration of the event + time difference between the previous timestamp and a current timestamp.

Example:

working_time, timestamp, event
4.089 2024-04-28T18:07:01.346Z change:frame
0.662 2024-04-28T18:07:00.225Z drag:object
0.466 2024-04-28T18:06:59.563Z resize:object
0.582 2024-04-28T18:06:59.097Z drag:object
1.048 2024-04-28T18:06:58.515Z drag:object

Let's say we've pushed the "play" button and changed 30 frames from frame 10 to frame 40. This means that UI would generate 30 change:frame events. Instead, these 30 events are collapsed in 1 event with a duration of 4 seconds and a timestamp of the first change:event.

To summarize the above.

Each event has it's own timestamp
Some event types has a duration. One of these kind is change:frame. Others has a duration as 0.
If there is a duration > 0 for the event, the duration is added to the working_time

A note about the time limits. If the time difference between the current timestamp and previous timestamp is <= 100 s. then the working time is calculated just like it is described above. If the time difference is > 100s, the working_time is 0 for the current event and the working_time is calculated from the second timestamp as usual.

Describe alternatives you've considered

No response

Additional context

No response

[bsekachev]

UI sends the message with the series of events by 3 triggers:
3.1. When user click "Save"
3.2 When user loads the job
3.3 Periodically by timer

3.4 When user closes a job without saving (for example by clicking "Tasks" button).

Other statements are correct.

change:frame events are collapsed into series to avoid huge amount of such events in analytics.