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.
@@ -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