application_insights 0.2.0 → 0.3.0

data/lib/application_insights/channel/queue_base.rb

@@ -2,24 +2,30 @@ require 'thread'
 
 module ApplicationInsights
   module Channel
-    # The base class for all queues.
+    # The base class for all types of queues for use in conjunction with an implementation of {SenderBase}. The queue
+    # will notify the sender that it needs to pick up items when it reaches {#max_queue_length}, or when the consumer
+    # calls {#flush}.
     class QueueBase
-      # Initializes a new instance of the queue class.
+      # Initializes a new instance of the class.
+      # @param [SenderBase] sender the sender object that will be used in conjunction with this queue.
       def initialize(sender)
-        raise ArgumentError, 'Sender was required but not provided' unless sender
         @queue = Queue.new
         @max_queue_length = 500
         @sender = sender
-        @sender.queue = self
+        @sender.queue = self if sender
       end
 
-      # Gets or sets the maximum number of items that will be held by the queue before we force a send.
+      # The maximum number of items that will be held by the queue before the queue will call the {#flush} method.
+      # @return [Fixnum] the maximum queue size. (defaults to: 500)
       attr_accessor :max_queue_length
 
-      # Gets the sender associated with this queue
+      # The sender that is associated with this queue that this queue will use to send data to the service.
+      # @return [SenderBase] the sender object.
       attr_reader :sender
 
-      # Adds a single item to the queue.
+      # Adds the passed in item object to the queue and calls {#flush} if the size of the queue is larger
+      # than {#max_queue_length}. This method does nothing if the passed in item is nil.
+      # @param [Contracts::Envelope] item the telemetry envelope object to send to the service.
       def push(item)
         unless item
           return
@@ -27,11 +33,12 @@ module ApplicationInsights
 
         @queue.push(item)
         if @queue.length >= @max_queue_length
-          flush()
+          flush
         end
       end
 
-      # Gets a single item from the queue. If no item is available, return nil.
+      # Pops a single item from the queue and returns it. If the queue is empty, this method will return nil.
+      # @return [Contracts::Envelope] a telemetry envelope object or nil if the queue is empty.
       def pop
         begin
           return @queue.pop(TRUE)
@@ -40,9 +47,16 @@ module ApplicationInsights
         end
       end
 
-      # Flushes the current queue to the passed in sender.
+      # Flushes the current queue by notifying the {#sender}. This method needs to be overridden by a concrete
+      # implementations of the queue class.
       def flush
       end
+
+      # Indicates whether the queue is empty.
+      # @return [true, false] true if the queue is empty
+      def empty?
+        @queue.empty?
+      end
     end
   end
 end

data/lib/application_insights/channel/sender_base.rb

@@ -1,32 +1,50 @@
 require 'json'
 require 'net/http'
+require 'stringio'
+require 'zlib'
 
 module ApplicationInsights
   module Channel
-    # The base class for all of our senders.
+    # The base class for all types of senders for use in conjunction with an implementation of {QueueBase}. The queue
+    # will notify the sender that it needs to pick up items. The concrete sender implementation will listen to these
+    # notifications and will pull items from the queue using {QueueBase#pop} getting at most {#send_buffer_size} items.
+    # It will then call {#send} using the list of items pulled from the queue.
     class SenderBase
-      # Initializes a new instance of the sender class.
+      # Initializes a new instance of the class.
+      # @param [String] service_endpoint_uri the address of the service to send telemetry data to.
       def initialize(service_endpoint_uri)
-        raise ArgumentError, 'Service endpoint URI was required but not provided' unless service_endpoint_uri
         @service_endpoint_uri = service_endpoint_uri
         @queue = nil
         @send_buffer_size = 100
       end
 
-      # Gets the service endpoint URI property. This is where we send data to.
+      # The service endpoint URI where this sender will send data to.
+      # @return [String] the service endpoint URI.
       attr_accessor :service_endpoint_uri
 
-      # The queue that we will be draining
+      # The queue that this sender is draining. While {SenderBase} doesn't implement any means of doing so, derivations
+      # of this class do.
+      # @return [QueueBase] the queue instance that this sender is draining.
       attr_accessor :queue
 
-      # Gets or sets the buffer size for a single batch of telemetry. This is the maximum number of items in a single service request we are going to send.
+      # The buffer size for a single batch of telemetry. This is the maximum number of items in a single service
+      # request that this sender is going to send.
+      # @return [Fixnum] the maximum number of items in a telemetry batch.
       attr_accessor :send_buffer_size
 
-      # Sends the data to send list to the service immediately.
+      # Immediately sends the data passed in to {#service_endpoint_uri}. If the service request fails, the passed in items
+      # are pushed back to the {#queue}.
+      # @param [Array<Contracts::Envelope>] data_to_send an array of {Contracts::Envelope} objects to send to the service.
       def send(data_to_send)
         uri = URI(@service_endpoint_uri)
-        request = Net::HTTP::Post.new(uri.path, { 'Accept' => 'application/json', 'Content-Type' => 'application/json; charset=utf-8' })
-        request.body = data_to_send.to_json
+        headers = {
+            'Accept' => 'application/json',
+            'Content-Type' => 'application/json; charset=utf-8',
+            'Content-Encoding' => 'gzip'
+        }
+        request = Net::HTTP::Post.new(uri.path, headers)
+        compressed_data = compress(data_to_send.to_json)
+        request.body = compressed_data
 
         http = Net::HTTP.new uri.hostname, uri.port
         if uri.scheme.downcase == 'https'
@@ -44,6 +62,17 @@ module ApplicationInsights
             end
         end
       end
+
+      private
+
+      def compress(string)
+        wio = StringIO.new("w")
+        w_gz = Zlib::GzipWriter.new wio, nil, nil
+        w_gz.write(string)
+        w_gz.close
+        wio.string
+      end
+
     end
   end
 end

data/lib/application_insights/channel/synchronous_queue.rb

@@ -2,25 +2,36 @@ require_relative 'queue_base'
 
 module ApplicationInsights
   module Channel
-    # A synchronous queue for use in conjunction with the SynchronousSender. The queue will flush either when it reaches max_queue_length or when someone calls flush().
+    # A synchronous queue for use in conjunction with the {SynchronousSender}. The queue
+    # will call {SenderBase#send} when it reaches {#max_queue_length}, or when the consumer
+    # calls {#flush}.
+    # @example
+    #   require 'application_insights'
+    #   require 'thread'
+    #   queue = ApplicationInsights::Channel::SynchronousQueue.new nil
+    #   queue.max_queue_length = 1
+    #   queue.push 1
     class SynchronousQueue < QueueBase
-      # Initializes a new instance of the synchronous queue class.
+      # Initializes a new instance of the class.
+      # @param [SenderBase] sender the sender object that will be used in conjunction with this queue.
       def initialize(sender)
         super sender
       end
 
-      # Flushes the current queue to the passed in sender.
+      # Flushes the current queue by by calling {#sender}'s {SenderBase#send} method.
       def flush
+        local_sender = @sender
+        return unless local_sender
         while TRUE
           # get at most send_buffer_size items and send them
           data = []
-          while data.length < @sender.send_buffer_size
+          while data.length < local_sender.send_buffer_size
             item = pop()
             break if not item
             data.push item
           end
           break if data.length == 0
-          @sender.send(data)
+          local_sender.send(data)
         end
       end
     end

data/lib/application_insights/channel/synchronous_sender.rb

@@ -2,9 +2,11 @@ require_relative 'sender_base'
 
 module ApplicationInsights
   module Channel
-    # A synchronous sender that works in conjunction with SynchronousQueue.
+    # A synchronous sender that works in conjunction with the {SynchronousQueue}. The queue will call {#send} on the
+    # current instance with the data to send.
     class SynchronousSender < SenderBase
-      # Initializes a new instance of the synchronous sender class.
+      # Initializes a new instance of the class.
+      # @param [String] service_endpoint_uri the address of the service to send telemetry data to.
       def initialize(service_endpoint_uri='https://dc.services.visualstudio.com/v2/track')
         super service_endpoint_uri
       end

data/lib/application_insights/channel/telemetry_channel.rb

@@ -1,3 +1,5 @@
+require_relative 'asynchronous_queue'
+require_relative 'asynchronous_sender'
 require_relative 'telemetry_context'
 require_relative 'synchronous_queue'
 require_relative 'synchronous_sender'
@@ -7,31 +9,48 @@ require_relative 'contracts/internal'
 
 module ApplicationInsights
   module Channel
-    # The telemetry channel is responsible for constructing an envelope an sending it.
+    # The telemetry channel is responsible for constructing a {Contracts::Envelope} object from the passed in
+    # data and specified telemetry context.
+    # @example
+    #   require 'application_insights'
+    #   channel = ApplicationInsights::Channel::TelemetryChannel.new
+    #   event = ApplicationInsights::Channel::Contracts::EventData.new :name => 'My event'
+    #   channel.write event
     class TelemetryChannel
-      # Initializes a new instance of the telemetry channel class.
+      # Initializes a new instance of the class.
+      # @param [TelemetryContext] context the telemetry context to use when sending telemetry data.
+      # @param [QueueBase] queue the queue to enqueue the resulting {Contracts::Envelope} to.
       def initialize(context=nil, queue=nil)
         @context = context || TelemetryContext.new
         @queue = queue || SynchronousQueue.new(SynchronousSender.new)
       end
 
-      # Gets the context associated with this channel.
+      # The context associated with this channel. All {Contracts::Envelope} objects created by this channel will use
+      # this value if it's present or if none is specified as part of the {#write} call.
+      # @return [TelemetryContext] the context instance (defaults to: TelemetryContext.new)
       attr_reader :context
 
-      # Gets the queue associated with this channel.
+      # The queue associated with this channel. All {Contracts::Envelope} objects created by this channel will be
+      # pushed to this queue.
+      # @return [QueueBase] the queue instance (defaults to: SynchronousQueue.new)
       attr_reader :queue
 
-      # Gets the sender associated with this channel.
+      # The sender associated with this channel. This instance will be used to transmit telemetry to the service.
+      # @return [SenderBase] the sender instance (defaults to: SynchronousSender.new)
       def sender
         @queue.sender
       end
 
-      # Flushes the current queue.
+      # Flushes the enqueued data by calling {QueueBase#flush}.
       def flush
         @queue.flush
       end
 
-      # Writes the passed in data to the sending queue.
+      # Enqueues the passed in data to the {#queue}. If the caller specifies a context as well, it will take precedence
+      # over the instance in {#context}.
+      # @param [Object] data the telemetry data to send. This will be wrapped in an {Contracts::Envelope} before being
+      #   enqueued to the {#queue}.
+      # @param [TelemetryContext] context the override context to use when constructing the {Contracts::Envelope}.
       def write(data, context=nil)
         local_context = context || @context
         raise ArgumentError, 'Context was required but not provided' unless local_context

data/lib/application_insights/channel/telemetry_context.rb

@@ -7,9 +7,20 @@ require_relative 'contracts/location'
 
 module ApplicationInsights
   module Channel
-    # Represents a context for sending telemetry to the Application Insights service.
+    # Represents the context for sending telemetry to the Application Insights service.
+    # @example
+    #   require 'application_insights'
+    #   context = ApplicationInsights::Channel::TelemetryContext.new
+    #   context.instrumentation_key = '<YOUR INSTRUMENTATION KEY GOES HERE>'
+    #   context.application.id = 'My application'
+    #   context.application.ver = '1.2.3'
+    #   context.device.id = 'My current device'
+    #   context.device.oem_name = 'Asus'
+    #   context.device.model = 'X31A'
+    #   context.device.type = "Other"
+    #   context.user.id = 'santa@northpole.net'
     class TelemetryContext
-      # Initializes a new instance of the TelemetryContext class.
+      # Initializes a new instance of the class.
       def initialize
         @instrumentation_key = nil
         @application = Contracts::Application.new
@@ -21,28 +32,36 @@ module ApplicationInsights
         @properties = {}
       end
 
-      # Gets or sets the instrumentation key.
+      # The instrumentation key that is used to identify which Application Insights application this data is for.
+      # @return [String] the instrumentation key.
       attr_accessor :instrumentation_key
 
-      # Gets or sets the application context.
+      # The application context. This contains properties of the application you are running.
+      # @return [Contracts::Application] the context object.
       attr_accessor :application
 
-      # Gets or sets the device context.
+      # The device context. This contains properties of the device you are running on.
+      # @return [Contracts::Device] the context object.
       attr_accessor :device
 
-      # Gets or sets the user context.
+      # The user context. This contains properties of the user you are generating telemetry for.
+      # @return [Contracts::User] the context object.
       attr_accessor :user
 
-      # Gets or sets the session context.
+      # The session context. This contains properties of the session you are generating telemetry for.
+      # @return [Contracts::Session] the context object.
       attr_accessor :session
 
-      # Gets or sets the operation context.
+      # The operation context. This contains properties of the operation you are generating telemetry for.
+      # @return [Contracts::Operation] the context object.
       attr_accessor :operation
 
-      # Gets or sets the location context.
+      # The location context. This contains properties of the location you are generating telemetry from.
+      # @return [Contracts::Location] the context object.
       attr_accessor :location
 
-      # Gets a dictionary of application-defined property values.
+      # The property context. This contains free-form properties that you can add to your telemetry.
+      # @return [Hash<String, String>] the context object.
       attr_reader :properties
     end
   end

data/lib/application_insights/telemetry_client.rb

@@ -8,23 +8,39 @@ require_relative 'channel/contracts/data_point'
 require_relative 'channel/contracts/data_point_type'
 require_relative 'channel/contracts/metric_data'
 require_relative 'channel/contracts/message_data'
+require_relative 'channel/contracts/stack_frame'
 
 module ApplicationInsights
-  # The telemetry client used for sending all types of telemetry.
+  # The telemetry client used for sending all types of telemetry. It serves as the main entry point for
+  # interacting with the Application Insights service.
   class TelemetryClient
-    # Initializes a new instance of the TelemetryClient class.
+    # Initializes a new instance of the class.
+    # @param [Channel::TelemetryChannel] telemetry_channel the optional telemetry channel to be used instead of
+    #   constructing a default one.
     def initialize(telemetry_channel = nil)
       @context = Channel::TelemetryContext.new
       @channel = telemetry_channel || Channel::TelemetryChannel.new
     end
 
-    # Gets the context associated with this telemetry client.
+    # The context associated with this client. All data objects created by this client will be accompanied by
+    # this value.
+    # @return [Channel::TelemetryContext] the context instance.
     attr_reader :context
 
-    # Gets the channel associated with this telemetry client.
+    # The channel associated with this telemetry client. All data created by this client will be passed along with
+    # the {#context} object to {Channel::TelemetryChannel#write}
+    # @return [Channel::TelemetryChannel] the channel instance.
     attr_reader :channel
 
-    # Send information about the page viewed in the application.
+    # Send information about the page viewed in the application (a web page for instance).
+    # @param [String] name the name of the page that was viewed.
+    # @param [String] url the URL of the page that was viewed.
+    # @param [Hash] options the options to create the {Channel::Contracts::PageViewData} object.
+    # @option options [Fixnum] :duration the duration of the page view in milliseconds. (defaults to: 0)
+    # @option options [Hash] :properties the set of custom properties the client wants attached to this
+    #   data item. (defaults to: {})
+    # @option options [Hash] :measurements the set of custom measurements the client wants to attach to
+    #   this data item (defaults to: {})
     def track_page_view(name, url, options={})
       data_attributes = {
         :name => name || 'Null',
@@ -37,21 +53,46 @@ module ApplicationInsights
       self.channel.write(data, self.context)
     end
 
-    # Send an ExceptionTelemetry object for display in Diagnostic Search.
+    # Send information about a single exception that occurred in the application.
+    # @param [Exception] exception the exception that the client wants to send.
+    # @param [Hash] options the options to create the {Channel::Contracts::ExceptionData} object.
+    # @option options [String] :handled_at the type of exception (defaults to: 'UserCode')
+    # @option options [Hash] :properties the set of custom properties the client wants attached to this
+    #   data item. (defaults to: {})
+    # @option options [Hash] :measurements the set of custom measurements the client wants to attach to
+    #   this data item (defaults to: {})
     def track_exception(exception, options={})
       if exception.is_a? Exception
+        parsed_stack = []
+        if exception.backtrace
+          frame_pattern = /^(?<file>.*):(?<line>\d+)(\.|:in `((?<method>.*)'$))/
+          counter = 0;
+          exception.backtrace.each do |frame|
+            match = frame_pattern.match frame
+            stack_frame = Channel::Contracts::StackFrame.new
+            stack_frame.assembly = 'Unknown'
+            stack_frame.file_name = match['file']
+            stack_frame.level = counter
+            stack_frame.line = match['line']
+            stack_frame.method = match['method']
+            parsed_stack << stack_frame
+            counter += 1
+          end
+        end
+
         details_attributes = {
           :id => 1,
           :outer_id => 0,
           :type_name => exception.class,
           :message => exception.message,
-          :has_full_stack => true,
-          :stack => exception.backtrace.join("\n")
+          :has_full_stack => exception.backtrace != nil,
+          :stack => (exception.backtrace.join("\n") if exception.backtrace),
+          :parsed_stack => parsed_stack
         }
         details = Channel::Contracts::ExceptionDetails.new details_attributes
 
         data_attributes = {
-          :handled_at => 'UserCode',
+          :handled_at => options.fetch(:handled_at,'UserCode'),
           :exceptions => [ details ],
           :properties => options.fetch(:properties) { {} },
           :measurements => options.fetch(:measurements) { {} }
@@ -61,7 +102,13 @@ module ApplicationInsights
       end
     end
 
-    # Send an EventTelemetry object for display in Diagnostic Search and aggregation in Metrics Explorer.
+    # Send information about a single event that has occurred in the context of the application.
+    # @param [String] name the data to associate to this event.
+    # @param [Hash] options the options to create the {Channel::Contracts::EventData} object.
+    # @option options [Hash] :properties the set of custom properties the client wants attached to this
+    #   data item. (defaults to: {})
+    # @option options [Hash] :measurements the set of custom measurements the client wants to attach to
+    #   this data item (defaults to: {})
     def track_event(name, options={})
       data_attributes = {
         :name => name || 'Null',
@@ -72,7 +119,24 @@ module ApplicationInsights
       self.channel.write(data, self.context)
     end
 
-    # Send a MetricTelemetry object for aggregation in Metric Explorer.
+    # Send information about a single metric data point that was captured for the application.
+    # @param [String] name the name of the metric that was captured.
+    # @param [Fixnum] value the value of the metric that was captured.
+    # @param [Hash] options the options to create the {Channel::Contracts::MetricData} object.
+    # @option options [Channel::Contracts::DataPointType] :type the type of the metric (defaults to:
+    #   {Channel::Contracts::DataPointType::AGGREGATION})
+    # @option options [Fixnum] :count the number of metrics that were aggregated into this data point
+    #   (defaults to: 0)
+    # @option options [Fixnum] :min the minimum of all metrics collected that were aggregated into this
+    #   data point (defaults to: 0)
+    # @option options [Fixnum] :max the maximum of all metrics collected that were aggregated into this
+    #   data point (defaults to: 0)
+    # @option options [Fixnum] :std_dev the standard deviation of all metrics collected that were aggregated
+    #   into this data point (defaults to: 0)
+    # @option options [Hash] :properties the set of custom properties the client wants attached to this
+    #   data item. (defaults to: {})
+    # @option options [Hash] :measurements the set of custom measurements the client wants to attach to
+    #   this data item (defaults to: {})
     def track_metric(name, value, options={})
       data_point_attributes = {
         :name => name || 'Null',
@@ -87,23 +151,28 @@ module ApplicationInsights
 
       data_attributes = {
         :metrics => [ data_point ],
-        :properties => options.fetch(:measurements) { {} }
+        :properties => options.fetch(:properties) { {} }
       }
       data = Channel::Contracts::MetricData.new data_attributes
       self.channel.write(data, self.context)
     end
 
-    # Send a trace message for display in Diagnostic Search.
+    # Sends a single trace statement.
+    # @param [String] name the trace statement.
+    # @param [Hash] options the options to create the {Channel::Contracts::EventData} object.
+    # @option options [Hash] :properties the set of custom properties the client wants attached to this
+    #   data item. (defaults to: {})
     def track_trace(name, options={})
       data_attributes = {
         :message => name || 'Null',
-        :properties => options.fetch(:measurements) { {} }
+        :properties => options.fetch(:properties) { {} }
       }
       data = Channel::Contracts::MessageData.new data_attributes
       self.channel.write(data, self.context)
     end
 
-    # Flushes the current queue.
+    # Flushes data in the queue. Data in the queue will be sent either immediately irrespective of what sender is
+    # being used.
     def flush
       self.channel.flush
     end