You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It is a libary that lets you monitor certain activities on your machine, and sends a heartbeat at a periodic (configurable) time detailing all the activity changes during that time. The activities that you want to monitor are **pluggable** handlers for those activities and can be added or removed according to your needs.
5
+
It is a libary that lets you monitor certain activities on your machine, and then sends a heartbeat at a periodic (configurable) time detailing all the activity changes during that time. The activities that you want to track are monitored by **pluggable** handlers for those activities and can be added or removed according to your needs. An example of an activity is `MouseCursorActivity`, i.e. whether your mouse cursor was moved or not.
6
6
7
7
## Installation
8
8
@@ -11,16 +11,16 @@ It is a libary that lets you monitor certain activities on your machine, and sen
11
11
## Usage
12
12
13
13
14
-
heartbeatFrequency := 60 //value always in seconds
15
-
workerFrequency := 5 //seconds
14
+
heartbeatInterval := 60 //value always in seconds
15
+
workerInterval := 5 //seconds
16
16
17
17
activityTracker := &tracker.Instance{
18
-
HeartbeatFrequency: heartbeatFrequency,
19
-
WorkerFrequency: workerFrequency,
18
+
HeartbeatInterval: heartbeatInterval,
19
+
WorkerInterval: workerInterval,
20
20
LogLevel: logging.Debug,
21
21
}
22
22
23
-
//This starts the tracker for all handlers. It gives you a channel
23
+
//This starts the tracker for all handlers currently implemented. It gives you a channel on
24
24
//which you can listen to for heartbeat objects
25
25
heartbeatCh := activityTracker.Start()
26
26
@@ -33,11 +33,11 @@ It is a libary that lets you monitor certain activities on your machine, and sen
33
33
34
34
if !heartbeat.WasAnyActivity {
35
35
36
-
logger.Infof("no activity detected in the last %v seconds", int(heartbeatFrequency))
36
+
logger.Infof("no activity detected in the last %v seconds", int(heartbeatInterval))
37
37
38
38
} else {
39
39
40
-
logger.Infof("activity detected in the last %v seconds.", int(heartbeatFrequency))
40
+
logger.Infof("activity detected in the last %v seconds.", int(heartbeatInterval))
41
41
42
42
logger.Infof("Activity type:\n")
43
43
@@ -49,10 +49,10 @@ It is a libary that lets you monitor certain activities on your machine, and sen
49
49
50
50
## Output
51
51
52
-
The above code created a tracker with all (`Mouse-click`, `Mouse-movement` and `Screen-Change`) handlers activated. The `heartbeat frequency` is set to 60 seconds, i.e. every 60 seconds I received a `heartbeat` which mentioned all activities that were captured.
52
+
The above code created a tracker with all (`Mouse-click`, `Mouse-movement` and `Screen-Change`) handlers activated. The `heartbeat Interval` is set to 60 seconds, i.e. every 60 seconds I received a `heartbeat` which mentioned all activities that were captured.
53
53
54
54
```
55
-
INFO[2019-03-30T15:52:01-07:00] starting activity tracker with 60s heartbeat and 5s worker frequency...
55
+
INFO[2019-03-30T15:52:01-07:00] starting activity tracker with 60s heartbeat and 5s worker Interval...
56
56
57
57
INFO[2019-03-30T15:53:01-07:00] activity detected in the last 60 seconds.
There are 2 primary configs required for the tracker to work:
68
68
69
-
-`HeartbeatFrequency`
69
+
-`HeartbeatInterval`
70
70
71
-
> The frequency at which you want the heartbeat (in seconds, default 60s)
71
+
> The Interval at which you want the heartbeat (in seconds, default 60s)
72
72
73
73
74
-
-`WorkerFrequency`
74
+
-`WorkerInterval`
75
75
76
-
> The frequency at which you want the checks to happen within a heartbeat (default 60s).
76
+
> The Interval at which you want the checks to happen within a heartbeat (default 60s).
77
77
78
+
The activity tracker gives you a `heartbeat` object every 60 seconds, that is based on the `HeartbeatInterval`. But there is something else to understand here. In order for the tracker to know how many times an activity occured, like how many times you moved the cursor for example, it needs to query the mouse position every `x` seconds. That's where the `WorkerInterval` comes into play.
78
79
79
-
The activity tracker gives you a `heartbeat` object every 60 seconds, that is based on the `HeartbeatFrequency`. But there is something else to understand here. In order for the tracker to know how many times an activity occured, or how many times you moved the cursor for example, it needs to query the mouse movement library `n` number of times. That's where the `WorkerFrequency` comes into play.
80
+
The `WorkerInterval` tells the tracker how frequently to check for an activity within a heartbeat. It does that by querying the handler associated with that activity. Let's say you want to know how many times the mouse cursor was moved within 60 seconds. You need to constantly ask the `mouseCursorHandler` every `x` seconds to see if the cursor moved. What you want to do is to start the tracker with the usual 60s `HeartbeatInterval `, configured with a `Mouse-cursor` handler. In this case, you set the `WorkerInterval` to 5 seconds. The tracker will then keep asking the mouse cursor handler every 5 seconds to see if there was a movement, and keep track each time there was a change. At the end of `HeartbeatInterval`, it will construct the `heartbeat` with all the changes and send it.
80
81
81
-
The `WorkerFrequency` tells the tracker how many times to query each of the handlers in the tracker within a heartbeat. Let's say you want to know how many times the mouse cursor was moved. What you want to do is to start the tracker with the usual 60s `HeartbeatFrequency `, configured with a `Mouse-cursor` handler. In this case, you set the `WorkerFrequency`to 5 seconds. It will then keep checking the mouse coordinates every 5 seconds to see if there was a movement, and track each time there was a change. At the end of `HeartbeatFrequency`, it will track all the changes and send it in the `heatbeat` object.
82
+
> If you are just concerned whether any activity happened within a heartbeat or not, you can set `WorkerInterval` the same as `HeartbeatInterval`. That way, the workers need to check just once before each heartbeat to know if there was any activity registered.
82
83
83
-
>If you are just concerned whether any activity happened within a heartbeat or not, you can set `WorkerFrequency` the same as `HeartbeatFrequency`.
84
+
>If you want to know how many `times` an activity occured within a heartbeat, you might want to set the `WorkerInterval` to a low value, so that it keeps quering the handlers.
84
85
85
-
>If you want to know how many times an activity occured within a heartbeat, you might want to set the `WorkerFrequency` to a low value, so that it keeps quering the handlers.
86
86
87
-
88
-
##### Note: If the `WorkerFrequency` and the `HeartbeatFrequency` are set the same, then the `WorkerFrequency` always is started a fraction of a second before the `HeartbeatFrequency` kicks in. This is done so that when the `heartbeat` is going to be generated at the end of `HeartbeatFrequency`, the worker should have done its job of querying each of the handlers before that.
87
+
##### Note: If the `WorkerInterval` and the `HeartbeatInterval` are set the same, then the `WorkerInterval` always is started a fraction of a second before the `HeartbeatInterval` kicks in. This is done so that when the `heartbeat` is going to be generated at the end of `HeartbeatInterval`, the worker should have done its job of querying each of the handlers before that.
89
88
90
89
## Usecase
91
90
92
-
Suppose you want to track Activities A, B and C on your machine, and you want a heartbeat every 5 minutes. What you want is for the tracker to send you heartbeats every 5 minutes, and each heartbeat would contain whether any of A, B or C occured within those 5 minutes, and if so, at what times.
91
+
Suppose you want to track Activities A, B and C on your machine, and you want to know how many times they occured every minute.
92
+
93
+
You want a report at the end of every minute saying `Activity A` happened 5 times, `Activity B` happened 3 times and `Activity C` happened 2 times.
93
94
94
-
As another example, let's say you want to monitor whether there was any mouse click on your machine and you want to be monitor every 5 minutes. What you do is start the `Activity Tracker` with just the `mouse click` handler and `heartbeat` frequency set to 5 minutes. The `Start` function of the library gives you a channel which receives a `heartbeat` every 5 minutes, and it has details on whether there was a `click` in those 5 minutes, and if yes, the times the click happened.
95
+
First, you need to create a `Handler` for each of those activities. See sections below on how to create one. The main `tracker` object will simply ask each of the handlers every `WorkerInterval` amout of time whether that activity happened or not at that moment.
95
96
97
+
As another example, let's say you want to monitor whether there was any mouse click on your machine and you want to be notified every 5 minutes. What you do is start the `Activity Tracker` with just the `mouse click` handler and `heartbeat` Interval set to 5 minutes. The `Start` function of the library gives you a channel which receives a `heartbeat` every 5 minutes, and it has details on whether there was a `click` in those 5 minutes, and if yes, the times the click happened.
96
98
97
99
98
100
# Components
@@ -111,51 +113,61 @@ It is the data packet sent from the tracker library to the user.
111
113
If there was, then the `ActivityMap` will tell you what type of activity it was and what all times it occured.
112
114
113
115
The `Time` field is the time of the Heartbeat sent (not to be confused with
114
-
the activity time, which is the time the activity occured within the time frame)
116
+
the activity time, which is the time the activity occured within the time frame).
115
117
116
118
### Tracker
117
119
118
120
The tracker is the main struct for the library.
119
121
120
-
//Instance is an instance of the tracker
121
-
HeartbeatFrequency int //the frequency at which you want the heartbeat (in seconds, default 60s)
122
-
WorkerFrequency int //therequency at which you want the checks to happen within a heartbeat (in seconds, default 5s)
122
+
HeartbeatInterval int //the Interval at which you want the heartbeat (in seconds, default 60s)
123
+
WorkerInterval int //the Interval at which you want the checks to happen within a heartbeat (in seconds, default 60s)
123
124
LogLevel string
124
125
LogFormat string
125
126
126
127
127
-
#### - `HeartbeatFrequency`
128
+
#### - `HeartbeatInterval`
128
129
129
-
The frequency at which you want the heartbeat (in seconds, default 60s)
130
+
The Interval at which you want the heartbeat (in seconds, default 60s)
130
131
131
-
##### Note: The `HeartbeatFrequency` value can be set anywhere between 60 seconds - 300 seconds. Not setting it or setting it to anything other than the allowed range will revert it to default of 60s.
132
+
##### Note: The `HeartbeatInterval` value can be set anywhere between 60 seconds - 300 seconds. Not setting it or setting it to anything other than the allowed range will revert it to default of 60s.
132
133
133
-
#### - `WorkerFrequency`
134
+
#### - `WorkerInterval`
134
135
135
-
The frequency at which you want the checks to happen within a heartbeat (default 60s).
136
+
The Interval at which you want the checks to happen within a heartbeat (default 60s).
136
137
137
-
##### Note: The `WorkerFrequency` value can be set anywhere between 4 seconds - 60 seconds. It CANNOT be more than `HeartbeatFrequency` for obvious reasons. Not setting it or setting it to anything other than the allowed range will revert it to default of 60s.
138
+
##### Note: The `WorkerInterval` value can be set anywhere between 4 seconds - 60 seconds. It CANNOT be more than `HeartbeatInterval` for obvious reasons. Not setting it or setting it to anything other than the allowed range will revert it to default of 60s.
138
139
139
140
140
141
## Relationship between Activity and Handler
141
142
142
-
Activity and Handler have a 1-1 mapping, i.e. each handler can only handle one type of activity, and vice-versa, each activity should be handled by one handler only.
143
+
Activity and Handler have a 1-1 mapping, i.e. each handler can only handle one type of activity, and vice-versa.
144
+
145
+
## Types of handlers
146
+
147
+
There are 2 types of handlers:
148
+
149
+
- Push based
150
+
- Pull based
151
+
143
152
144
-
The `Type` in the `Handler` interface determines the type of activity the particular handler handles.
153
+
The `push` based ones are those that push to the `tracker` object when an activity happened. An example is the `mouseClickHander`. Whenever a mouse click happens, it sends the `activity` to the `tracker` object.
154
+
155
+
The `pull` based ones are those that the `tracker` has to ask the handler to know if there was any activity happening at that moment.
156
+
Examples are `mouseCursorHandler` and `screenChangeHandler`. The `asking` is done through the `Trigger` function implemented by handlers.
157
+
158
+
It is up to you to define how to implement the handler. Some make sense to be pull based, since it is going to be memory intensive to make the mouse cursor movement handler push-based. It made sense to make it `pull` based.
145
159
146
160
## New pluggable handlers for activities
147
161
148
162
149
-
//Instance is the main interface for a Handler for the tracker
150
-
type Instance interface {
151
-
Start(*log.Logger, chan *activity.Instance)
152
-
Type() activity.Type
153
-
Trigger()
154
-
Close()
155
-
}
156
-
157
-
Any new type of handler for an activity can be easily added, it just needs to implement the above `Handler` interface and define what type of activity it is going to track, that's it! It can be plugged in with the tracker and then the tracker will include those activity checks in its heartbeat.
163
+
//Handler interface
164
+
Start(*log.Logger, chan *activity.Instance)
165
+
Type() activity.Type
166
+
Trigger() //used for pull-based handlers
167
+
Close()
158
168
169
+
170
+
Any new type of handler for an activity can be easily added, it just needs to implement the above `Handler` interface and define what `type` of activity it is going to track (also add the new `activity` as well), that's it! It can be plugged in with the tracker and then the tracker will include those activity checks in its heartbeat.
159
171
160
172
## Currently supported list of activities/handlers
0 commit comments