snowplow-tracker 0.6.1 → 0.8.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/README.md +58 -36
- data/lib/snowplow-tracker/emitters.rb +339 -154
- data/lib/snowplow-tracker/page.rb +55 -0
- data/lib/snowplow-tracker/payload.rb +28 -39
- data/lib/snowplow-tracker/self_describing_json.rb +92 -9
- data/lib/snowplow-tracker/subject.rb +289 -68
- data/lib/snowplow-tracker/timestamp.rb +93 -25
- data/lib/snowplow-tracker/tracker.rb +521 -257
- data/lib/snowplow-tracker/version.rb +26 -4
- data/lib/snowplow-tracker.rb +5 -5
- metadata +11 -33
- data/lib/snowplow-tracker/contracts.rb +0 -29
@@ -1,4 +1,4 @@
|
|
1
|
-
# Copyright (c)
|
1
|
+
# Copyright (c) 2013-2021 Snowplow Analytics Ltd. All rights reserved.
|
2
2
|
#
|
3
3
|
# This program is licensed to you under the Apache License Version 2.0,
|
4
4
|
# and you may not use this file except in compliance with the Apache License Version 2.0.
|
@@ -9,38 +9,106 @@
|
|
9
9
|
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
10
10
|
# See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
|
11
11
|
|
12
|
-
# Author::
|
13
|
-
# Copyright:: Copyright (c)
|
12
|
+
# Author:: Snowplow Analytics Ltd
|
13
|
+
# Copyright:: Copyright (c) 2013-2021 Snowplow Analytics Ltd
|
14
14
|
# License:: Apache License Version 2.0
|
15
15
|
|
16
|
-
module SnowplowTracker
|
17
|
-
|
18
|
-
class Timestamp
|
19
16
|
|
20
|
-
|
21
|
-
|
17
|
+
module SnowplowTracker
|
18
|
+
# Creates timestamps for events. Timestamps are counted in milliseconds since
|
19
|
+
# the Unix epoch (`(Time.now.to_f * 1000).to_i`).
|
20
|
+
#
|
21
|
+
# Snowplow events accrue timestamps as they are processed. When an event is
|
22
|
+
# first generated by a {Tracker}, it has the raw event property `dtm`
|
23
|
+
# ("device timestamp"; `dvce_created_tstamp` in the processed event)
|
24
|
+
# or `ttm` ("true timestamp";`true_tstamp` in the processed event). These two
|
25
|
+
# timestamps are set using the Timestamp subclasses {DeviceTimestamp} and
|
26
|
+
# {TrueTimestamp}. The {Emitter} adds a `stm` ("sent timestamp";
|
27
|
+
# `dvce_sent_tstamp`) property to the event just before sending it to the
|
28
|
+
# collector. These timestamps are all processed into UTC time.
|
29
|
+
#
|
30
|
+
# Events can have either a device timestamp or a true timestamp, not both. By
|
31
|
+
# default, the `#track_x_event` methods create a DeviceTimestamp. In some
|
32
|
+
# circumstances, the device timestamp may be inaccurate. There are three
|
33
|
+
# methods to override the default device timestamp value when the event is
|
34
|
+
# created.
|
35
|
+
#
|
36
|
+
# 1. Provide your own calculated timestamp, as a Num (e.g. `1633596554978`),
|
37
|
+
# to the `#track_x_event` method. This will be converted into a
|
38
|
+
# DeviceTimestamp by the Tracker, and will still be recorded as `dtm` in
|
39
|
+
# the event.
|
40
|
+
# 2. Manually create a DeviceTimestamp (e.g.
|
41
|
+
# `SnowplowTracker::DeviceTimestamp.new(1633596554978)`), and provide this to the
|
42
|
+
# `#track_x_event` method. This will still be recorded as `dtm` in the
|
43
|
+
# event.
|
44
|
+
# 3. Provide a TrueTimestamp object to the `track_x_event` method (e.g.
|
45
|
+
# `SnowplowTracker::TrueTimestamp.new(1633596554978)`). This will result in a `ttm` field in
|
46
|
+
# the event.
|
47
|
+
#
|
48
|
+
# The timestamps that are added to the event once it has been emitted are not
|
49
|
+
# the responsibility of this class. The collector receives the event and adds a
|
50
|
+
# `collector_tstamp`. A later part of the pipeline adds the `etl_tstamp` when
|
51
|
+
# the event enrichment has finished.
|
52
|
+
#
|
53
|
+
# When DeviceTimestamp is used, a `derived_tstamp` is also calculated and
|
54
|
+
# added to the event. This timestamp attempts to take latency and possible
|
55
|
+
# inaccuracy of the device clock into account. It is calculated by
|
56
|
+
# `collector_tstamp - (dvce_sent_tstamp - dvce_created_tstamp)`. When
|
57
|
+
# TrueTimestamp is used, the `derived_stamp` will be the same as
|
58
|
+
# `true_tstamp`.
|
59
|
+
#
|
60
|
+
# @see
|
61
|
+
# https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
|
62
|
+
# the Snowplow Tracker Protocol
|
63
|
+
# @see
|
64
|
+
# https://discourse.snowplowanalytics.com/t/which-timestamp-is-the-best-to-see-when-an-event-occurred/538
|
65
|
+
# A Discourse forums post explaining timestamps
|
66
|
+
# @api public
|
67
|
+
class Timestamp
|
68
|
+
# @private
|
69
|
+
attr_reader :type
|
22
70
|
|
23
|
-
|
24
|
-
|
25
|
-
@value = value
|
26
|
-
end
|
71
|
+
# @private
|
72
|
+
attr_reader :value
|
27
73
|
|
74
|
+
# @private
|
75
|
+
def initialize(type, value)
|
76
|
+
@type = type
|
77
|
+
@value = value
|
28
78
|
end
|
29
79
|
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
end
|
35
|
-
|
80
|
+
# Calculates time since the Unix epoch.
|
81
|
+
# @private
|
82
|
+
def self.create
|
83
|
+
(Time.now.to_f * 1000).to_i
|
36
84
|
end
|
85
|
+
end
|
37
86
|
|
38
|
-
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
87
|
+
# @see Timestamp
|
88
|
+
# A very simple class that stores a timestamp, i.e. a numeric value
|
89
|
+
# representing milliseconds since the Unix epoch, and which type of timestamp
|
90
|
+
# it is, namely `ttm`. This raw event `ttm` field will be processed into
|
91
|
+
# `true_tstamp` in the completed event.
|
92
|
+
class TrueTimestamp < Timestamp
|
93
|
+
# @param [Num] value timestamp in milliseconds since the Unix epoch
|
94
|
+
# @example
|
95
|
+
# SnowplowTracker::TrueTimestamp.new(1633596346786)
|
96
|
+
def initialize(value)
|
97
|
+
super 'ttm', value
|
44
98
|
end
|
99
|
+
end
|
45
100
|
|
46
|
-
|
101
|
+
# @see Timestamp
|
102
|
+
# A very simple class that stores a timestamp, i.e. a numeric value
|
103
|
+
# representing milliseconds since the Unix epoch, and which type of timestamp
|
104
|
+
# it is, namely `dtm`. This raw event `dtm` field will be processed into
|
105
|
+
# `dvce_created_tstamp` in the completed event.
|
106
|
+
class DeviceTimestamp < Timestamp
|
107
|
+
# @param [Num] value timestamp in milliseconds since the Unix epoch
|
108
|
+
# @example
|
109
|
+
# SnowplowTracker::DeviceTimestamp.new(1633596346786)
|
110
|
+
def initialize(value)
|
111
|
+
super 'dtm', value
|
112
|
+
end
|
113
|
+
end
|
114
|
+
end
|