skylight 0.1.5.alpha2 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6059d5cc28b761943e1e644d04404a1f4420b41d
-  data.tar.gz: e9df2d646694636ef1f68db3787571249df39606
+  metadata.gz: ffd96c332034f1a8aac5a14cb5a326edc78b3940
+  data.tar.gz: 2013e889ac8555f1fbbe27b018c337c0039ed39c
 SHA512:
-  metadata.gz: 49ddf44811aef8f2f440712baef90ed957f87cf4caddacee72074e2d9ada901f7f7fd149645aa17ad0698a06c616f86feecec2b25641e41a900e667d5c3ad38c
-  data.tar.gz: e6ff2793abc7d6781ae8acf7ca196bb60f2e4ef2c4f49bf6f3de9b0ad9a7830d9b215af60049c85f2f968a2db3a2f42528de538d00098c2dd223d100c55693be
+  metadata.gz: ef18196dcd99d0eb39d6d47e0f92e0fe762e52c8fede06778bd44cd8e258de3eb453c2bbf65eab939d87b71f3df002106c8e278eb029339e00451713977cf330
+  data.tar.gz: d9bae247b299859a0e3095ad849c6ea24ef1d82affc3deba326cb2965b34ed5d2abc88cb67a1cf51fa10cb2b4cd939e088f2e059fcb4af786d9c8de40979cb80

data/CHANGELOG.md

@@ -1,6 +1,10 @@
 ## unreleased ##
 
+## 0.1.5 (May 31, 2013)
+
 * Provide a default CA cert when one is not already present
+* Expose Skylight.start! and Skylight.trace as APIs
+* Expose Skylight.instrument as an API for custom instrumentation.
 
 ## 0.1.4 (May 30, 2013)
 

data/lib/skylight.rb

@@ -50,12 +50,34 @@ module Skylight
   class TraceError       < RuntimeError; end
 
   TIERS = %w(
+    api
     app
     view
     db
     noise
     other)
 
+  TIER_REGEX = /^(?:#{TIERS.join('|')})(?:\.|$)/
+  CATEGORY_REGEX = /^[a-z0-9_-]+(?:\.[a-z0-9_-]+)*$/i
+
+  def self.start!(*args)
+    Instrumenter.start!(*args)
+  end
+
+  def self.stop!(*args)
+    Instrumenter.stop!(*args)
+  end
+
+  def self.trace(*args, &blk)
+    return yield unless inst = Instrumenter.instance
+    inst.trace(*args, &blk)
+  end
+
+  def self.instrument(*args, &blk)
+    return yield unless inst = Instrumenter.instance
+    inst.instrument(*args, &blk)
+  end
+
   RUBYBIN = File.join(
     RbConfig::CONFIG['bindir'],
     "#{RbConfig::CONFIG['ruby_install_name']}#{RbConfig::CONFIG['EXEEXT']}")

data/lib/skylight/instrumenter.rb

@@ -2,7 +2,8 @@ require 'thread'
 
 module Skylight
   class Instrumenter
-    KEY = :__skylight_current_trace
+    KEY  = :__skylight_current_trace
+    LOCK = Mutex.new
 
     include Util::Logging
 
@@ -14,8 +15,25 @@ module Skylight
       Thread.current[KEY] = trace
     end
 
+    def self.instance
+      @instance
+    end
+
     def self.start!(config = Config.new)
-      new(config).start!
+      return @instance if @instance
+
+      LOCK.synchronize do
+        return @instance if @instance
+        @instance = new(config).start!
+      end
+    end
+
+    def self.stop!
+      LOCK.synchronize do
+        return unless @instance
+        @instance.shutdown
+        @instance = nil
+      end
     end
 
     attr_reader :config, :gc
@@ -26,31 +44,19 @@ module Skylight
       end
 
       @gc = config.gc
-      @lock = Mutex.new
       @config = config
       @worker = config.worker.build
-      @started = false
       @subscriber = Subscriber.new(config)
     end
 
     def start!
-      # Quick check
-      return self if @started
       return unless config
 
-      @lock.synchronize do
-        # Ensure that the instrumenter has not been started now that the lock
-        # has been acquired.
-        return self if @started
-
-        t { "starting instrumenter" }
-        @config.validate!
-        @config.gc.enable
-        @worker.spawn
-        @subscriber.register!
-
-        @started = true
-      end
+      t { "starting instrumenter" }
+      @config.validate!
+      @config.gc.enable
+      @worker.spawn
+      @subscriber.register!
 
       self
 
@@ -60,19 +66,11 @@ module Skylight
     end
 
     def shutdown
-      @lock.synchronize do
-        return unless @started
-        @subscriber.unregister!
-        @worker.shutdown
-      end
+      @subscriber.unregister!
+      @worker.shutdown
     end
 
     def trace(endpoint = 'Unknown')
-      # Ignore everything unless the instrumenter has been started
-      unless @started
-        return yield
-      end
-
       # If a trace is already in progress, continue with that one
       if trace = Instrumenter.current_trace
         t { "already tracing" }
@@ -98,7 +96,8 @@ module Skylight
             if built && built.spans.empty?
               debug "trace invalid -- dropping; spans=0"
             elsif built
-              debug "trace invalid -- dropping; spans=%d; started_at=%d", built.spans, built.spans[-1].started_at
+              debug "trace invalid -- dropping; spans=%d; started_at=%d",
+                built.spans.length, built.spans[-1].started_at
             else
               debug "trace invalid -- dropping; trace=nil"
             end
@@ -109,6 +108,25 @@ module Skylight
       end
     end
 
+    def instrument(cat, *args)
+      cat = cat.to_s
+
+      unless cat =~ CATEGORY_REGEX
+        warn "invalid skylight instrumentation category; value=%s", cat
+        return yield
+      end
+
+      cat = "other.#{cat}" unless cat =~ TIER_REGEX
+
+      return yield unless sp = @subscriber.instrument(cat, *args)
+
+      begin
+        yield sp
+      ensure
+        @subscriber.done
+      end
+    end
+
   private
 
     def process(trace)

data/lib/skylight/messages/span.rb

@@ -16,6 +16,68 @@ module Skylight
       def initialize(attrs = nil)
         super if attrs
       end
+
+      class Builder
+
+        attr_reader \
+          :time,
+          :category,
+          :title,
+          :started_at,
+          :description,
+          :annotations
+
+        attr_accessor :children
+
+        def initialize(trace, time, started_at, cat, title, desc, annot)
+          @trace      = trace
+          @built      = false
+          @time       = time
+          @started_at = started_at
+          @category   = cat.to_s
+          @children   = 0
+          self.title  = title
+          self.description = desc
+        end
+
+        def endpoint=(name)
+          @trace.endpoint = name
+        end
+
+        def built?
+          @built
+        end
+
+        def build(duration)
+          @built = true
+          Span.new(
+            event: Event.new(
+              category: category,
+              title: title,
+              description: description),
+            annotations: to_annotations(annotations),
+            started_at: @started_at,
+            duration: duration && duration > 0 ? duration : nil,
+            children: @children > 0 ? @children : nil)
+        end
+
+        def title=(val)
+          val = nil unless val.respond_to?(:to_str)
+          @title = val && val.to_str
+        end
+
+        def description=(val)
+          val = nil unless val.respond_to?(:to_str)
+          @description = val && val.to_str
+        end
+
+      private
+
+        def to_annotations(val)
+          [] # TODO: Implement
+        end
+
+      end
     end
   end
 end

data/lib/skylight/messages/trace.rb

@@ -73,12 +73,12 @@ module Skylight
 
           sp = span(time, cat, title, desc, annot)
 
-          return self if :skip == sp
+          return if :skip == sp
 
           inc_children
-          @spans << sp
+          @spans << sp.build(0)
 
-          self
+          nil
         end
 
         def start(time, cat, title = nil, desc = nil, annot = {})
@@ -90,7 +90,9 @@ module Skylight
 
           push(sp)
 
-          self
+          return if :skip == sp
+
+          sp
         end
 
         def stop(time)
@@ -100,12 +102,11 @@ module Skylight
 
           sp = pop
 
-          return self if :skip == sp
+          return if :skip == sp
 
-          sp.duration = relativize(time) - sp.started_at
-          @spans << sp
+          @spans << sp.build(relativize(time) - sp.started_at)
 
-          self
+          nil
         end
 
         def build
@@ -123,30 +124,9 @@ module Skylight
         def span(time, cat, title, desc, annot)
           return cat if :skip == cat
 
-          sp = Span.new
-          sp.event         = event(cat, title, desc)
-          sp.annotations   = to_annotations(annot)
-          sp.started_at    = relativize(time)
-          sp.absolute_time = time
-
-          if sp.started_at < 0
-            @busted = true
-            raise TraceError, "[BUG] span started_at negative; event=#{cat};" \
-              " started_at=#{sp.started_at};" \
-              " duration=#{sp.duration}"
-          end
-
-          sp
-        end
-
-        def event(cat, title, desc)
-          title = nil unless title.respond_to?(:to_str)
-          desc  = nil unless desc.respond_to?(:to_str)
-
-          Event.new(
-            category:    cat.to_s,
-            title:       title && title.to_str,
-            description: desc && desc.to_str)
+          Span::Builder.new(
+            self, time, relativize(time),
+            cat, title, desc, annot)
         end
 
         def push(sp)
@@ -171,16 +151,12 @@ module Skylight
 
         def inc_children
           return unless sp = @parents.last
-          sp.children = (sp.children || 0) + 1
-        end
-
-        def to_annotations(annot)
-          [] # TODO: Implement
+          sp.children += 1
         end
 
         def relativize(time)
           if parent = @parents[-1]
-            ((time - parent.absolute_time) / 100).to_i
+            ((time - parent.time) / 100).to_i
           else
             ((time - @start) / 100).to_i
           end

data/lib/skylight/middleware.rb

@@ -1,18 +1,12 @@
 module Skylight
   class Middleware
 
-    def self.new(app, instrumenter, *)
-      return app unless instrumenter
-      super
-    end
-
-    def initialize(app, instrumenter)
+    def initialize(app)
       @app = app
-      @instrumenter = instrumenter
     end
 
     def call(env)
-      @instrumenter.trace("Rack") do |trace|
+      Skylight.trace "Rack" do |trace|
         trace.root 'app.rack.request' do
           @app.call(env)
         end

data/lib/skylight/normalizers/default.rb

@@ -1,10 +1,9 @@
 module Skylight
   module Normalizers
     class Default
-      REGEX = /^(?:#{TIERS.join('|')})(?:\.|$)/
 
       def normalize(trace, name, payload)
-        if name =~ REGEX
+        if name =~ TIER_REGEX
           annot = payload.dup
           [
             name,

data/lib/skylight/railtie.rb

@@ -14,9 +14,8 @@ module Skylight
     initializer 'skylight.configure' do |app|
       if activate?
         if config = load_skylight_config(app)
-          @instrumenter = Instrumenter.start!(config)
-
-          app.middleware.insert 0, Middleware, @instrumenter
+          Instrumenter.start!(config)
+          app.middleware.insert 0, Middleware
 
           Rails.logger.info "[SKYLIGHT] Skylight agent enabled"
         end

data/lib/skylight/subscriber.rb

@@ -20,6 +20,27 @@ module Skylight
       @subscriber = nil
     end
 
+    def instrument(category, *args)
+      return unless trace = Instrumenter.current_trace
+
+      annot = args.pop if Hash === args
+      title = args.shift
+      desc  = args.shift
+
+      trace.start(now - gc_time, category, title, desc, annot)
+    end
+
+    def done
+      return unless trace = Instrumenter.current_trace
+      trace.stop(now - gc_time)
+    end
+
+    #
+    #
+    # ===== ActiveSupport::Notifications API
+    #
+    #
+
     def start(name, id, payload)
       return unless trace = Instrumenter.current_trace
 

data/lib/skylight/version.rb

@@ -1,4 +1,4 @@
 module Skylight
-  VERSION = '0.1.5.alpha2'
+  VERSION = '0.1.5'
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skylight
 version: !ruby/object:Gem::Version
-  version: 0.1.5.alpha2
+  version: 0.1.5
 platform: ruby
 authors:
 - Tilde, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-30 00:00:00.000000000 Z
+date: 2013-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -157,9 +157,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.3