analytics-ruby 2.0.13 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 71d4951f83fc43ae93e330b35c97062bd9c8df64
-  data.tar.gz: 11e299db5daf757cba620a539fd827dd25a8436d
+SHA256:
+  metadata.gz: 51f3f02afed05c9c8461b454e0a3067962a75b8efde0930db0098eebf4a62829
+  data.tar.gz: e7d486d6c6186535e9a005c4d950e6e29d2dd9937f9b6da625191d786f76846a
 SHA512:
-  metadata.gz: 8439045c35184236fe21998035a6aa56b799b0d51246f7a52afc676511991eedb71001059ed81fc5f72f05debb1471ea4acc49cc9c4395f7844d010c35c9a95c
-  data.tar.gz: 3e5e394d1a0c569d37b8eccb85edc086ff6d7a94fb0eb8894764bafb57eaa01700ab7b2b64834052a17421e23b86396f8d9beca3fbcc67b824d6f2b4d615ea05
+  metadata.gz: c2ce09d450de65620eb99f9fae86aa5ce57709d53aa4a93c73c2d3db0b173afad532383a50fe4dcb953df72171b731a263ff7308aed79b646a25bc202c555e4d
+  data.tar.gz: b3625484ebca6117ae79fc42f03a595dff861b8c5ca02a6ef12ea9e933229c1479dad40b4db1d85e61ddf585c7c5a072d68e9cd21ced6b2482db338f45073707

data/bin/analytics

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+
+require 'segment/analytics'
+require 'rubygems'
+require 'commander/import'
+require 'time'
+require 'json'
+
+program :name, 'simulator.rb'
+program :version, '0.0.1'
+program :description, 'scripting simulator'
+
+def json_hash(str)
+  if str
+    return JSON.parse(str)
+  end
+end
+
+# analytics -method=<method> -segment-write-key=<segmentWriteKey> [options]
+
+default_command :send
+
+command :send do |c|
+  c.description = 'send a segment message'
+
+  c.option '--writeKey=<writeKey>', String, 'the Segment writeKey'
+  c.option '--type=<type>', String, 'The Segment message type'
+
+  c.option '--userId=<userId>', String, 'the user id to send the event as'
+  c.option '--anonymousId=<anonymousId>', String, 'the anonymous user id to send the event as'
+  c.option '--context=<context>', 'additional context for the event (JSON-encoded)'
+  c.option '--integrations=<integrations>', 'additional integrations for the event (JSON-encoded)'
+
+  c.option '--event=<event>', String, 'the event name to send with the event'
+  c.option '--properties=<properties>', 'the event properties to send (JSON-encoded)'
+
+  c.option '--name=<name>', 'name of the screen or page to send with the message'
+
+  c.option '--traits=<traits>', 'the identify/group traits to send (JSON-encoded)'
+
+  c.option '--groupId=<groupId>', String, 'the group id'
+  c.option '--previousId=<previousId>', String, 'the previous id'
+
+  c.action do |args, options|
+    Analytics = Segment::Analytics.new({
+      write_key: options.writeKey,
+      on_error: Proc.new { |status, msg| print msg }
+    })
+
+    case options.type
+    when "track"
+      Analytics.track({
+        user_id: options.userId,
+        event: options.event,
+        anonymous_id: options.anonymousId,
+        properties: json_hash(options.properties),
+        context: json_hash(options.context),
+        integrations: json_hash(options.integrations)
+      })
+    when "page"
+      Analytics.page({
+        user_id: options.userId,
+        anonymous_id: options.anonymousId,
+        name: options.name,
+        properties: json_hash(options.properties),
+        context: json_hash(options.context),
+        integrations: json_hash(options.integrations)
+      })
+    when "screen"
+      Analytics.screen({
+        user_id: options.userId,
+        anonymous_id: options.anonymousId,
+        name: options.name,
+        properties: json_hash(options.properties),
+        context: json_hash(options.context),
+        integrations: json_hash(options.integrations)
+      })
+    when "identify"
+      Analytics.identify({
+        user_id: options.userId,
+        anonymous_id: options.anonymousId,
+        traits: json_hash(options.traits),
+        context: json_hash(options.context),
+        integrations: json_hash(options.integrations)
+      })
+    when "group"
+      Analytics.group({
+        user_id: options.userId,
+        anonymous_id: options.anonymousId,
+        group_id: options.groupId,
+        traits: json_hash(options.traits),
+        context: json_hash(options.context),
+        integrations: json_hash(options.integrations)
+      })
+    when "alias"
+      Analytics.alias({
+        previous_id: options.previousId,
+        user_id: options.userId,
+        anonymous_id: options.anonymousId,
+        context: json_hash(options.context),
+        integrations: json_hash(options.integrations)
+      })
+    else
+      raise "Invalid Message Type #{options.type}"
+    end
+    Analytics.flush
+  end
+end

data/lib/analytics-ruby.rb

@@ -0,0 +1 @@
+require 'segment'

data/lib/segment/analytics/backoff_policy.rb

@@ -0,0 +1,49 @@
+require 'segment/analytics/defaults'
+
+module Segment
+  class Analytics
+    class BackoffPolicy
+      include Segment::Analytics::Defaults::BackoffPolicy
+
+      # @param [Hash] opts
+      # @option opts [Numeric] :min_timeout_ms The minimum backoff timeout
+      # @option opts [Numeric] :max_timeout_ms The maximum backoff timeout
+      # @option opts [Numeric] :multiplier The value to multiply the current
+      #   interval with for each retry attempt
+      # @option opts [Numeric] :randomization_factor The randomization factor
+      #   to use to create a range around the retry interval
+      def initialize(opts = {})
+        @min_timeout_ms = opts[:min_timeout_ms] || MIN_TIMEOUT_MS
+        @max_timeout_ms = opts[:max_timeout_ms] || MAX_TIMEOUT_MS
+        @multiplier = opts[:multiplier] || MULTIPLIER
+        @randomization_factor = opts[:randomization_factor] || RANDOMIZATION_FACTOR
+
+        @attempts = 0
+      end
+
+      # @return [Numeric] the next backoff interval, in milliseconds.
+      def next_interval
+        interval = @min_timeout_ms * (@multiplier**@attempts)
+        interval = add_jitter(interval, @randomization_factor)
+
+        @attempts += 1
+
+        [interval, @max_timeout_ms].min
+      end
+
+      private
+
+      def add_jitter(base, randomization_factor)
+        random_number = rand
+        max_deviation = base * randomization_factor
+        deviation = random_number * max_deviation
+
+        if random_number < 0.5
+          base - deviation
+        else
+          base + deviation
+        end
+      end
+    end
+  end
+end

data/lib/segment/analytics/client.rb

@@ -1,39 +1,42 @@
 require 'thread'
 require 'time'
+
+require 'segment/analytics/defaults'
+require 'segment/analytics/logging'
 require 'segment/analytics/utils'
 require 'segment/analytics/worker'
-require 'segment/analytics/defaults'
 
 module Segment
   class Analytics
     class Client
       include Segment::Analytics::Utils
+      include Segment::Analytics::Logging
 
-      # public: Creates a new client
-      #
-      # attrs - Hash
-      #           :write_key         - String of your project's write_key
-      #           :max_queue_size - Fixnum of the max calls to remain queued (optional)
-      #           :on_error       - Proc which handles error calls from the API
-      def initialize attrs = {}
-        symbolize_keys! attrs
+      # @param [Hash] opts
+      # @option opts [String] :write_key Your project's write_key
+      # @option opts [FixNum] :max_queue_size Maximum number of calls to be
+      #   remain queued.
+      # @option opts [Proc] :on_error Handles error calls from the API.
+      def initialize(opts = {})
+        symbolize_keys!(opts)
 
         @queue = Queue.new
-        @write_key = attrs[:write_key]
-        @max_queue_size = attrs[:max_queue_size] || Defaults::Queue::MAX_SIZE
-        @options = attrs
+        @test = opts[:test]
+        @write_key = opts[:write_key]
+        @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
         @worker_mutex = Mutex.new
-        @worker = Worker.new @queue, @write_key, @options
+        @worker = Worker.new(@queue, @write_key, opts)
+        @worker_thread = nil
 
         check_write_key!
 
         at_exit { @worker_thread && @worker_thread[:should_exit] = true }
       end
 
-      # public: Synchronously waits until the worker has flushed the queue.
-      #         Use only for scripts which are not long-running, and will
-      #         specifically exit
+      # Synchronously waits until the worker has flushed the queue.
       #
+      # Use only for scripts which are not long-running, and will specifically
+      # exit
       def flush
         while !@queue.empty? || @worker.is_requesting?
           ensure_worker_running
@@ -41,246 +44,114 @@ module Segment
         end
       end
 
-      # public: Tracks an event
+      # @!macro common_attrs
+      #   @option attrs [String] :anonymous_id ID for a user when you don't know
+      #     who they are yet. (optional but you must provide either an
+      #     `anonymous_id` or `user_id`)
+      #   @option attrs [Hash] :context ({})
+      #   @option attrs [Hash] :integrations What integrations this event
+      #     goes to (optional)
+      #   @option attrs [String] :message_id ID that uniquely
+      #     identifies a message across the API. (optional)
+      #   @option attrs [Time] :timestamp When the event occurred (optional)
+      #   @option attrs [String] :user_id The ID for this user in your database
+      #     (optional but you must provide either an `anonymous_id` or `user_id`)
+      #   @option attrs [Hash] :options Options such as user traits (optional)
+
+      # Tracks an event
       #
-      # attrs - Hash
-      #           :anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
-      #           :context      - Hash of context. (optional)
-      #           :event        - String of event name.
-      #           :integrations - Hash specifying what integrations this event goes to. (optional)
-      #           :options      - Hash specifying options such as user traits. (optional)
-      #           :properties   - Hash of event properties. (optional)
-      #           :timestamp    - Time of when the event occurred. (optional)
-      #           :user_id      - String of the user id.
-      def track attrs
+      # @see https://segment.com/docs/sources/server/ruby/#track
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :event Event name
+      # @option attrs [Hash] :properties Event properties (optional)
+      # @macro common_attrs
+      def track(attrs)
         symbolize_keys! attrs
-        check_user_id! attrs
-
-        event = attrs[:event]
-        properties = attrs[:properties] || {}
-        timestamp = attrs[:timestamp] || Time.new
-        context = attrs[:context] || {}
-
-        check_timestamp! timestamp
-
-        if event.nil? || event.empty?
-          fail ArgumentError, 'Must supply event as a non-empty string'
-        end
-
-        fail ArgumentError, 'Properties must be a Hash' unless properties.is_a? Hash
-        isoify_dates! properties
-
-        add_context context
-
-        enqueue({
-          :event => event,
-          :userId => attrs[:user_id],
-          :anonymousId => attrs[:anonymous_id],
-          :context =>  context,
-          :options => attrs[:options],
-          :integrations => attrs[:integrations],
-          :properties => properties,
-          :timestamp => datetime_in_iso8601(timestamp),
-          :type => 'track'
-        })
+        enqueue(FieldParser.parse_for_track(attrs))
       end
 
-      # public: Identifies a user
+      # Identifies a user
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#identify
       #
-      # attrs - Hash
-      #           :anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
-      #           :context      - Hash of context. (optional)
-      #           :integrations - Hash specifying what integrations this event goes to. (optional)
-      #           :options      - Hash specifying options such as user traits. (optional)
-      #           :timestamp    - Time of when the event occurred. (optional)
-      #           :traits       - Hash of user traits. (optional)
-      #           :user_id      - String of the user id
-      def identify attrs
+      # @param [Hash] attrs
+      #
+      # @option attrs [Hash] :traits User traits (optional)
+      # @macro common_attrs
+      def identify(attrs)
         symbolize_keys! attrs
-        check_user_id! attrs
-
-        traits = attrs[:traits] || {}
-        timestamp = attrs[:timestamp] || Time.new
-        context = attrs[:context] || {}
-
-        check_timestamp! timestamp
-
-        fail ArgumentError, 'Must supply traits as a hash' unless traits.is_a? Hash
-        isoify_dates! traits
-
-        add_context context
-
-        enqueue({
-          :userId => attrs[:user_id],
-          :anonymousId => attrs[:anonymous_id],
-          :integrations => attrs[:integrations],
-          :context => context,
-          :traits => traits,
-          :options => attrs[:options],
-          :timestamp => datetime_in_iso8601(timestamp),
-          :type => 'identify'
-        })
+        enqueue(FieldParser.parse_for_identify(attrs))
       end
 
-      # public: Aliases a user from one id to another
+      # Aliases a user from one id to another
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#alias
       #
-      # attrs - Hash
-      #           :context     - Hash of context (optional)
-      #           :integrations - Hash specifying what integrations this event goes to. (optional)
-      #           :options      - Hash specifying options such as user traits. (optional)
-      #           :previous_id - String of the id to alias from
-      #           :timestamp   - Time of when the alias occured (optional)
-      #           :user_id     - String of the id to alias to
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :previous_id The ID to alias from
+      # @macro common_attrs
       def alias(attrs)
         symbolize_keys! attrs
-
-        from = attrs[:previous_id]
-        to = attrs[:user_id]
-        timestamp = attrs[:timestamp] || Time.new
-        context = attrs[:context] || {}
-
-        check_presence! from, 'previous_id'
-        check_presence! to, 'user_id'
-        check_timestamp! timestamp
-        add_context context
-
-        enqueue({
-          :previousId => from,
-          :userId => to,
-          :integrations => attrs[:integrations],
-          :context => context,
-          :options => attrs[:options],
-          :timestamp => datetime_in_iso8601(timestamp),
-          :type => 'alias'
-        })
+        enqueue(FieldParser.parse_for_alias(attrs))
       end
 
-      # public: Associates a user identity with a group.
+      # Associates a user identity with a group.
       #
-      # attrs - Hash
-      #           :context      - Hash of context (optional)
-      #           :integrations - Hash specifying what integrations this event goes to. (optional)
-      #           :options      - Hash specifying options such as user traits. (optional)
-      #           :previous_id  - String of the id to alias from
-      #           :timestamp    - Time of when the alias occured (optional)
-      #           :user_id      - String of the id to alias to
+      # @see https://segment.com/docs/sources/server/ruby/#group
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :group_id The ID of the group
+      # @option attrs [Hash] :traits User traits (optional)
+      # @macro common_attrs
       def group(attrs)
         symbolize_keys! attrs
-        check_user_id! attrs
-
-        group_id = attrs[:group_id]
-        user_id = attrs[:user_id]
-        traits = attrs[:traits] || {}
-        timestamp = attrs[:timestamp] || Time.new
-        context = attrs[:context] || {}
-
-        fail ArgumentError, '.traits must be a hash' unless traits.is_a? Hash
-        isoify_dates! traits
-
-        check_presence! group_id, 'group_id'
-        check_timestamp! timestamp
-        add_context context
-
-        enqueue({
-          :groupId => group_id,
-          :userId => user_id,
-          :traits => traits,
-          :integrations => attrs[:integrations],
-          :options => attrs[:options],
-          :context => context,
-          :timestamp => datetime_in_iso8601(timestamp),
-          :type => 'group'
-        })
+        enqueue(FieldParser.parse_for_group(attrs))
       end
 
-      # public: Records a page view
+      # Records a page view
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#page
+      #
+      # @param [Hash] attrs
       #
-      # attrs - Hash
-      #           :anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
-      #           :category     - String of the page category (optional)
-      #           :context      - Hash of context (optional)
-      #           :integrations - Hash specifying what integrations this event goes to. (optional)
-      #           :name         - String name of the page
-      #           :options      - Hash specifying options such as user traits. (optional)
-      #           :properties   - Hash of page properties (optional)
-      #           :timestamp    - Time of when the pageview occured (optional)
-      #           :user_id      - String of the id to alias from
+      # @option attrs [String] :name Name of the page
+      # @option attrs [Hash] :properties Page properties (optional)
+      # @macro common_attrs
       def page(attrs)
         symbolize_keys! attrs
-        check_user_id! attrs
-
-        name = attrs[:name].to_s
-        properties = attrs[:properties] || {}
-        timestamp = attrs[:timestamp] || Time.new
-        context = attrs[:context] || {}
-
-        fail ArgumentError, '.properties must be a hash' unless properties.is_a? Hash
-        isoify_dates! properties
-
-        check_timestamp! timestamp
-        add_context context
-
-        enqueue({
-          :userId => attrs[:user_id],
-          :anonymousId => attrs[:anonymous_id],
-          :name => name,
-          :category => attrs[:category],
-          :properties => properties,
-          :integrations => attrs[:integrations],
-          :options => attrs[:options],
-          :context => context,
-          :timestamp => datetime_in_iso8601(timestamp),
-          :type => 'page'
-        })
+        enqueue(FieldParser.parse_for_page(attrs))
       end
-      # public: Records a screen view (for a mobile app)
+
+      # Records a screen view (for a mobile app)
       #
-      # attrs - Hash
-      #           :anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
-      #           :category     - String screen category (optional)
-      #           :context      - Hash of context (optional)
-      #           :integrations - Hash specifying what integrations this event goes to. (optional)
-      #           :name         - String name of the screen
-      #           :options      - Hash specifying options such as user traits. (optional)
-      #           :properties   - Hash of screen properties (optional)
-      #           :timestamp    - Time of when the screen occured (optional)
-      #           :user_id      - String of the id to alias from
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :name Name of the screen
+      # @option attrs [Hash] :properties Screen properties (optional)
+      # @option attrs [String] :category The screen category (optional)
+      # @macro common_attrs
       def screen(attrs)
         symbolize_keys! attrs
-        check_user_id! attrs
-
-        name = attrs[:name].to_s
-        properties = attrs[:properties] || {}
-        timestamp = attrs[:timestamp] || Time.new
-        context = attrs[:context] || {}
-
-        fail ArgumentError, '.properties must be a hash' unless properties.is_a? Hash
-        isoify_dates! properties
-
-        check_timestamp! timestamp
-        add_context context
-
-        enqueue({
-          :userId => attrs[:user_id],
-          :anonymousId => attrs[:anonymous_id],
-          :name => name,
-          :properties => properties,
-          :category => attrs[:category],
-          :options => attrs[:options],
-          :integrations => attrs[:integrations],
-          :context => context,
-          :timestamp => timestamp.iso8601,
-          :type => 'screen'
-        })
+        enqueue(FieldParser.parse_for_screen(attrs))
       end
 
-      # public: Returns the number of queued messages
-      #
-      # returns Fixnum of messages in the queue
+      # @return [Fixnum] number of messages in the queue
       def queued_messages
         @queue.length
       end
 
+      def test_queue
+        unless @test
+          raise 'Test queue only available when setting :test to true.'
+        end
+
+        @test_queue ||= TestQueue.new
+      end
+
       private
 
       # private: Enqueues the action.
@@ -288,57 +159,28 @@ module Segment
       # returns Boolean of whether the item was added to the queue.
       def enqueue(action)
         # add our request id for tracing purposes
-        action[:messageId] = uid
-        unless queue_full = @queue.length >= @max_queue_size
-          ensure_worker_running
+        action[:messageId] ||= uid
+
+        test_queue << action if @test
+
+        if @queue.length < @max_queue_size
           @queue << action
-        end
-        !queue_full
-      end
+          ensure_worker_running
 
-      # private: Ensures that a string is non-empty
-      #
-      # obj    - String|Number that must be non-blank
-      # name   - Name of the validated value
-      #
-      def check_presence!(obj, name)
-        if obj.nil? || (obj.is_a?(String) && obj.empty?)
-          fail ArgumentError, "#{name} must be given"
+          true
+        else
+          logger.warn(
+            'Queue is full, dropping events. The :max_queue_size ' \
+            'configuration parameter can be increased to prevent this from ' \
+            'happening.'
+          )
+          false
         end
       end
 
-      # private: Adds contextual information to the call
-      #
-      # context - Hash of call context
-      def add_context(context)
-        context[:library] =  { :name => "analytics-ruby", :version => Segment::Analytics::VERSION.to_s }
-      end
-
       # private: Checks that the write_key is properly initialized
       def check_write_key!
-        fail ArgumentError, 'Write key must be initialized' if @write_key.nil?
-      end
-
-      # private: Checks the timstamp option to make sure it is a Time.
-      def check_timestamp!(timestamp)
-        fail ArgumentError, 'Timestamp must be a Time' unless timestamp.is_a? Time
-      end
-
-      def event attrs
-        symbolize_keys! attrs
-
-        {
-          :userId => user_id,
-          :name => name,
-          :properties => properties,
-          :context => context,
-          :timestamp => datetime_in_iso8601(timestamp),
-          :type => 'screen'
-        }
-      end
-
-      def check_user_id! attrs
-        fail ArgumentError, 'Must supply either user_id or anonymous_id' unless attrs[:user_id] || attrs[:anonymous_id]
+        raise ArgumentError, 'Write key must be initialized' if @write_key.nil?
       end
 
       def ensure_worker_running

data/lib/segment/analytics/defaults.rb

@@ -6,15 +6,31 @@ module Segment
         PORT = 443
         PATH = '/v1/import'
         SSL = true
-        HEADERS = { :accept => 'application/json' }
-        RETRIES = 4
-        BACKOFF = 30.0
+        HEADERS = { 'Accept' => 'application/json',
+                    'Content-Type' => 'application/json',
+                    'User-Agent' => "analytics-ruby/#{Analytics::VERSION}" }
+        RETRIES = 10
       end
 
       module Queue
-        BATCH_SIZE = 100
         MAX_SIZE = 10000
       end
+
+      module Message
+        MAX_BYTES = 32768 # 32Kb
+      end
+
+      module MessageBatch
+        MAX_BYTES = 512_000 # 500Kb
+        MAX_SIZE = 100
+      end
+
+      module BackoffPolicy
+        MIN_TIMEOUT_MS = 100
+        MAX_TIMEOUT_MS = 10000
+        MULTIPLIER = 1.5
+        RANDOMIZATION_FACTOR = 0.5
+      end
     end
   end
 end