snowplow-tracker 0.7.0.pre.alpha.2 → 0.7.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -1,4 +1,4 @@
1
- # Copyright (c) 2016 Snowplow Analytics Ltd. All rights reserved.
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:: Alex Dean, Fred Blundun, Ed Lewis (mailto:support@snowplowanalytics.com)
13
- # Copyright:: Copyright (c) 2016 Snowplow Analytics Ltd
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
- class Timestamp
63
+ # @private
64
+ attr_reader :type
19
65
 
20
- attr_reader :type
21
- attr_reader :value
66
+ # @private
67
+ attr_reader :value
22
68
 
23
- def initialize(type, value)
24
- @type = type
25
- @value = value
26
- end
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
- class TrueTimestamp < Timestamp
31
-
32
- def initialize(value)
33
- super 'ttm', value
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
- class DeviceTimestamp < Timestamp
39
-
40
- def initialize(value)
41
- super 'dtm', value
42
- end
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
- end
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