snowplow-tracker 0.6.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/README.md +56 -37
- data/lib/snowplow-tracker/emitters.rb +355 -147
- data/lib/snowplow-tracker/page.rb +60 -0
- data/lib/snowplow-tracker/payload.rb +30 -34
- data/lib/snowplow-tracker/self_describing_json.rb +92 -9
- data/lib/snowplow-tracker/subject.rb +282 -59
- data/lib/snowplow-tracker/timestamp.rb +95 -23
- data/lib/snowplow-tracker/tracker.rb +547 -242
- data/lib/snowplow-tracker/version.rb +33 -4
- data/lib/snowplow-tracker.rb +5 -5
- metadata +15 -17
- 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,110 @@
|
|
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
|
+
|
16
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
|
+
# `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
|
+
# `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. A `derived_tstamp` is also calculated and
|
52
|
+
# added to the event, which represents how long it took the event to be
|
53
|
+
# processed. This is calculated by `collector_tstamp - (dvce_sent_tstamp -
|
54
|
+
# dvce_created_tstamp)`.
|
55
|
+
#
|
56
|
+
# @see
|
57
|
+
# https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
|
58
|
+
# the Snowplow Tracker Protocol
|
59
|
+
# @api public
|
60
|
+
class Timestamp
|
61
|
+
include Contracts
|
17
62
|
|
18
|
-
|
63
|
+
# @private
|
64
|
+
attr_reader :type
|
19
65
|
|
20
|
-
|
21
|
-
|
66
|
+
# @private
|
67
|
+
attr_reader :value
|
22
68
|
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
69
|
+
# @private
|
70
|
+
# Contract type
|
71
|
+
TIMESTAMP = ->(x) {
|
72
|
+
return false unless x.is_a? Integer
|
73
|
+
x.to_s.length == 13
|
74
|
+
}
|
27
75
|
|
76
|
+
# @private
|
77
|
+
def initialize(type, value)
|
78
|
+
@type = type
|
79
|
+
@value = value
|
28
80
|
end
|
29
81
|
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
end
|
35
|
-
|
82
|
+
# Calculates time since the Unix epoch.
|
83
|
+
# @private
|
84
|
+
def self.create
|
85
|
+
(Time.now.to_f * 1000).to_i
|
36
86
|
end
|
87
|
+
end
|
37
88
|
|
38
|
-
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
89
|
+
# @see Timestamp
|
90
|
+
# A very simple class that stores a timestamp, i.e. a numeric value
|
91
|
+
# representing milliseconds since the Unix epoch, and which type of timestamp
|
92
|
+
# it is, namely `ttm`. This raw event `ttm` field will be processed into
|
93
|
+
# `true_tstamp` in the completed event.
|
94
|
+
class TrueTimestamp < Timestamp
|
95
|
+
Contract TIMESTAMP => Any
|
96
|
+
# @param [Num] value timestamp in milliseconds since the Unix epoch
|
97
|
+
# @example
|
98
|
+
# TrueTimestamp.new(1633596346786)
|
99
|
+
def initialize(value)
|
100
|
+
super 'ttm', value
|
44
101
|
end
|
102
|
+
end
|
45
103
|
|
46
|
-
|
104
|
+
# @see Timestamp
|
105
|
+
# A very simple class that stores a timestamp, i.e. a numeric value
|
106
|
+
# representing milliseconds since the Unix epoch, and which type of timestamp
|
107
|
+
# it is, namely `dtm`. This raw event `dtm` field will be processed into
|
108
|
+
# `dvce_created_tstamp` in the completed event.
|
109
|
+
class DeviceTimestamp < Timestamp
|
110
|
+
Contract TIMESTAMP => Any
|
111
|
+
# @param [Num] value timestamp in milliseconds since the Unix epoch
|
112
|
+
# @example
|
113
|
+
# DeviceTimestamp.new(1633596346786)
|
114
|
+
def initialize(value)
|
115
|
+
super 'dtm', value
|
116
|
+
end
|
117
|
+
end
|
118
|
+
end
|