Class: SnowplowTracker::Timestamp

Inherits:
Object
  • Object
show all
Defined in:
lib/snowplow-tracker/timestamp.rb

Overview

Creates timestamps for events. Timestamps are counted in milliseconds since the Unix epoch (‘(Time.now.to_f * 1000).to_i`).

Snowplow events accrue timestamps as they are processed. When an event is first generated by a Tracker, it has the raw event property ‘dtm` (“device timestamp”; `dvce_created_tstamp` in the processed event) or `ttm` (“true timestamp”;`true_tstamp` in the processed event). These two timestamps are set using the Timestamp subclasses DeviceTimestamp and TrueTimestamp. The Emitter adds a `stm` (“sent timestamp”; `dvce_sent_tstamp`) property to the event just before sending it to the collector. These timestamps are all processed into UTC time.

Events can have either a device timestamp or a true timestamp, not both. By default, the ‘#track_x_event` methods create a DeviceTimestamp. In some circumstances, the device timestamp may be inaccurate. There are three methods to override the default device timestamp value when the event is created.

  1. Provide your own calculated timestamp, as a Num (e.g. ‘1633596554978`), to the `#track_x_event` method. This will be converted into a DeviceTimestamp by the Tracker, and will still be recorded as `dtm` in the event.

  2. Manually create a DeviceTimestamp (e.g. ‘SnowplowTracker::DeviceTimestamp.new(1633596554978)`), and provide this to the `#track_x_event` method. This will still be recorded as `dtm` in the event.

  3. Provide a TrueTimestamp object to the ‘track_x_event` method (e.g. `SnowplowTracker::TrueTimestamp.new(1633596554978)`). This will result in a `ttm` field in the event.

The timestamps that are added to the event once it has been emitted are not the responsibility of this class. The collector receives the event and adds a ‘collector_tstamp`. A later part of the pipeline adds the `etl_tstamp` when the event enrichment has finished.

When DeviceTimestamp is used, a ‘derived_tstamp` is also calculated and added to the event. This timestamp attempts to take latency and possible inaccuracy of the device clock into account. It is calculated by `collector_tstamp - (dvce_sent_tstamp - dvce_created_tstamp)`. When TrueTimestamp is used, the `derived_stamp` will be the same as `true_tstamp`.

See Also:

Direct Known Subclasses

DeviceTimestamp, TrueTimestamp

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type, value) ⇒ Timestamp

Returns a new instance of Timestamp.



75
76
77
78
 
# File 'lib/snowplow-tracker/timestamp.rb', line 75

def initialize(type, value)
  @type = type
  @value = value
end

Instance Attribute Details

#type ⇒ Object (readonly) 



69
70
71
 
# File 'lib/snowplow-tracker/timestamp.rb', line 69

def type
  @type
end

#value ⇒ Object (readonly) 



72
73
74
 
# File 'lib/snowplow-tracker/timestamp.rb', line 72

def value
  @value
end

Class Method Details

.create ⇒ Object

Calculates time since the Unix epoch.



82
83
84
 
# File 'lib/snowplow-tracker/timestamp.rb', line 82

def self.create
  (Time.now.to_f * 1000).to_i
end