html-pipeline 0.0.10 → 0.0.11

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 0.0.11
+
+  * add instrumentation support. readme cleanup mtodd #45
+
 ## 0.0.10
 
   * add bin/html-pipeline util indirect #44

data/README.md

@@ -53,9 +53,7 @@ pipeline = HTML::Pipeline.new [
 result = pipeline.call <<-CODE
 This is *great*:
 
-``` ruby
-some_code(:first)
-```
+    some_code(:first)
 
 CODE
 result[:output].to_s
@@ -178,7 +176,7 @@ require 'uri'
 class RootRelativeFilter < HTML::Pipeline::Filter
 
   def call
-    doc.search("img").each do |img| 
+    doc.search("img").each do |img|
       next if img['src'].nil?
       src = img['src'].strip
       if src.start_with? '/'
@@ -197,6 +195,44 @@ Now this filter can be used in a pipeline:
 Pipeline.new [ RootRelativeFilter ], { :base_url => 'http://somehost.com' }
 ```
 
+## Instrumenting
+
+To instrument each filter and a full pipeline call, set an
+[ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)
+service object on a pipeline object. New pipeline objects will default to the
+`HTML::Pipeline.default_instrumentation_service` object.
+
+``` ruby
+# the AS::Notifications-compatible service object
+service = ActiveSupport::Notifications
+
+# instrument a specific pipeline
+pipeline = HTML::Pipeline.new [MarkdownFilter], context
+pipeline.instrumentation_service = service
+
+# or instrument all new pipelines
+HTML::Pipeline.default_instrumentation_service = service
+```
+
+Filters are instrumented when they are run through the pipeline. A
+`call_filter.html_pipeline` event is published once the filter finishes. The
+`payload` should include the `filter` name. Each filter will trigger its own
+instrumentation call.
+
+``` ruby
+service.subscribe "call_filter.html_pipeline" do |event, start, ending, transaction_id, payload|
+  payload[:filter] #=> "MarkdownFilter"
+end
+```
+
+The full pipeline is also instrumented:
+
+``` ruby
+service.subscribe "call_pipeline.html_pipeline" do |event, start, ending, transaction_id, payload|
+  payload[:filters] #=> ["MarkdownFilter"]
+end
+```
+
 ## Development
 
 To see what has changed in recent versions, see the [CHANGELOG](https://github.com/jch/html-pipeline/blob/master/CHANGELOG.md).

data/lib/html/pipeline.rb

@@ -61,11 +61,21 @@ module HTML
     # Public: Returns an Array of Filter objects for this Pipeline.
     attr_reader :filters
 
+    # Public: Instrumentation service for the pipeline.
+    # Set an ActiveSupport::Notifications compatible object to enable.
+    attr_accessor :instrumentation_service
+
+    class << self
+      # Public: Default instrumentation service for new pipeline objects.
+      attr_accessor :default_instrumentation_service
+    end
+
     def initialize(filters, default_context = {}, result_class = nil)
       raise ArgumentError, "default_context cannot be nil" if default_context.nil?
       @filters = filters.flatten.freeze
       @default_context = default_context.freeze
       @result_class = result_class || Hash
+      @instrumentation_service = self.class.default_instrumentation_service
     end
 
     # Apply all filters in the pipeline to the given HTML.
@@ -84,10 +94,37 @@ module HTML
       context = @default_context.merge(context)
       context = context.freeze
       result ||= @result_class.new
-      result[:output] = @filters.inject(html) { |doc, filter| filter.call(doc, context, result) }
+      instrument "call_pipeline.html_pipeline", :filters => @filters.map(&:name) do
+        result[:output] =
+          @filters.inject(html) do |doc, filter|
+            perform_filter(filter, doc, context, result)
+          end
+      end
       result
     end
 
+    # Internal: Applies a specific filter to the supplied doc.
+    #
+    # The filter is instrumented.
+    #
+    # Returns the result of the filter.
+    def perform_filter(filter, doc, context, result)
+      instrument "call_filter.html_pipeline", :filter => filter.name do
+        filter.call(doc, context, result)
+      end
+    end
+
+    # Internal: if the `instrumentation_service` object is set, instruments the
+    # block, otherwise the block is ran without instrumentation.
+    #
+    # Returns the result of the provided block.
+    def instrument(event, payload = nil)
+      return yield unless instrumentation_service
+      instrumentation_service.instrument event, payload do
+        yield
+      end
+    end
+
     # Like call but guarantee the value returned is a DocumentFragment.
     # Pipelines may return a DocumentFragment or a String. Callers that need a
     # DocumentFragment should use this method.

data/lib/html/pipeline/version.rb

@@ -1,5 +1,5 @@
 module HTML
   class Pipeline
-    VERSION = "0.0.10"
+    VERSION = "0.0.11"
   end
 end

data/test/helpers/mocked_instrumentation_service.rb

@@ -0,0 +1,15 @@
+class MockedInstrumentationService
+  attr_reader :events
+  def initialize(event = nil, events = [])
+    @events = events
+    subscribe event
+  end
+  def instrument(event, payload = nil)
+    res = yield
+    events << [event, payload, res] if @subscribe == event
+    res
+  end
+  def subscribe(event)
+    @subscribe = event
+  end
+end

data/test/html/pipeline_test.rb

@@ -0,0 +1,52 @@
+require "test_helper"
+require "helpers/mocked_instrumentation_service"
+
+class HTML::PipelineTest < Test::Unit::TestCase
+  Pipeline = HTML::Pipeline
+  class TestFilter
+    def self.call(input, context, result)
+      input
+    end
+  end
+
+  def setup
+    @context = {}
+    @result_class = Hash
+    @pipeline = Pipeline.new [TestFilter], @context, @result_class
+  end
+
+  def test_filter_instrumentation
+    service = MockedInstrumentationService.new
+    service.subscribe "call_filter.html_pipeline"
+    @pipeline.instrumentation_service = service
+    filter("hello")
+    event, payload, res = service.events.pop
+    assert event, "event expected"
+    assert_equal "call_filter.html_pipeline", event
+    assert_equal TestFilter.name, payload[:filter]
+  end
+
+  def test_pipeline_instrumentation
+    service = MockedInstrumentationService.new
+    service.subscribe "call_pipeline.html_pipeline"
+    @pipeline.instrumentation_service = service
+    filter("hello")
+    event, payload, res = service.events.pop
+    assert event, "event expected"
+    assert_equal "call_pipeline.html_pipeline", event
+    assert_equal @pipeline.filters.map(&:name), payload[:filters]
+  end
+
+  def test_default_instrumentation_service
+    service = 'default'
+    Pipeline.default_instrumentation_service = service
+    pipeline = Pipeline.new [], @context, @result_class
+    assert_equal service, pipeline.instrumentation_service
+  ensure
+    Pipeline.default_instrumentation_service = nil
+  end
+
+  def filter(input)
+    @pipeline.call(input)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: html-pipeline
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-21 00:00:00.000000000 Z
+date: 2013-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gemoji
@@ -176,6 +176,7 @@ files:
 - lib/html/pipeline/textile_filter.rb
 - lib/html/pipeline/toc_filter.rb
 - lib/html/pipeline/version.rb
+- test/helpers/mocked_instrumentation_service.rb
 - test/html/pipeline/absolute_source_filter_test.rb
 - test/html/pipeline/autolink_filter_test.rb
 - test/html/pipeline/camo_filter_test.rb
@@ -186,6 +187,7 @@ files:
 - test/html/pipeline/plain_text_input_filter_test.rb
 - test/html/pipeline/sanitization_filter_test.rb
 - test/html/pipeline/toc_filter_test.rb
+- test/html/pipeline_test.rb
 - test/test_helper.rb
 homepage: https://github.com/jch/html-pipeline
 licenses:
@@ -213,6 +215,7 @@ signing_key:
 specification_version: 3
 summary: Helpers for processing content through a chain of filters
 test_files:
+- test/helpers/mocked_instrumentation_service.rb
 - test/html/pipeline/absolute_source_filter_test.rb
 - test/html/pipeline/autolink_filter_test.rb
 - test/html/pipeline/camo_filter_test.rb
@@ -223,4 +226,5 @@ test_files:
 - test/html/pipeline/plain_text_input_filter_test.rb
 - test/html/pipeline/sanitization_filter_test.rb
 - test/html/pipeline/toc_filter_test.rb
+- test/html/pipeline_test.rb
 - test/test_helper.rb