frankenstein 0.1.0

data/README.md

@@ -0,0 +1,58 @@
+Frankenstein, or the Modern Prometheus, is a collection of tools and
+patterns to make instrumenting a Ruby application just a little bit simpler. 
+
+
+# Installation
+
+It's a gem:
+
+    gem install frankenstein
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'frankenstein'
+
+If you're the sturdy type that likes to run from git:
+
+    rake install
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+The following classes are available; please see their documentation for more
+details.
+
+* **`Frankenstein::Server`**: a simple Webrick-based HTTP server you can
+  easily embed in your application to serve metrics requests.
+
+* **`Frankenstein::Request`**: collect [basic
+  metrics](https://honeycomb.io/blog/2017/01/instrumentation-the-first-four-things-you-measure/)
+  about the requests your service receives and makes.
+
+
+# Contributing
+
+See CONTRIBUTING.md.
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2017  Civilized Discourse Contruction Kit Inc.
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/frankenstein.gemspec

@@ -0,0 +1,48 @@
+begin
+  require 'git-version-bump'
+rescue LoadError
+  nil
+end
+
+Gem::Specification.new do |s|
+  s.name = "frankenstein"
+
+  s.version = GVB.version rescue "0.0.0.1.NOGVB"
+  s.date    = GVB.date    rescue Time.now.strftime("%Y-%m-%d")
+
+  s.platform = Gem::Platform::RUBY
+
+  s.summary  = "or, the Modern Prometheus"
+  s.description = <<~EOF
+    This is a collection of useful tools to help you in more easily
+    instrumenting Ruby applications for the Prometheus monitoring
+    system.
+  EOF
+
+  s.authors  = ["Matt Palmer"]
+  s.email    = ["matt.palmer@discourse.org"]
+  s.homepage = "https://github.com/discourse/frankenstein"
+
+  s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(G|spec|Rakefile)/ }
+
+  s.required_ruby_version = ">= 2.3.0"
+
+  # prometheus-client provides no guaranteed backwards compatibility,
+  # and in fact happily breaks things with no notice, so we're stuck
+  # with hard-coding a specific version to avoid unexpected disaster.
+  s.add_runtime_dependency "prometheus-client", "0.7.1"
+  s.add_runtime_dependency "rack", "~> 2.0"
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'github-release'
+  s.add_development_dependency 'git-version-bump'
+  s.add_development_dependency 'guard-rspec'
+  s.add_development_dependency 'guard-rubocop'
+  s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'rake', "~> 12.0"
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'yard'
+end

data/lib/frankenstein.rb

@@ -0,0 +1,6 @@
+# Base module for all Frankenstein functionality.
+module Frankenstein; end
+
+require 'frankenstein/errors'
+require 'frankenstein/request'
+require 'frankenstein/server'

data/lib/frankenstein/error.rb

@@ -0,0 +1,4 @@
+module Frankenstein
+  # Base class of all exceptions raised by Frankenstein itself
+  class Error < StandardError; end
+end

data/lib/frankenstein/request.rb

@@ -0,0 +1,191 @@
+require 'prometheus/client'
+
+require 'frankenstein/error'
+
+module Frankenstein
+  # A common pattern for statistical instrumentation is to capture a few basic
+  # numbers for all incoming and outgoing requests to the service.  Since this
+  # is a common pattern, we can abstract that behaviour into a common class,
+  # which simplifies the external interface for maintaining statistics in this
+  # common case.
+  #
+  # For more information on this pattern, see
+  # https://honeycomb.io/blog/2017/01/instrumentation-the-first-four-things-you-measure/
+  #
+  class Request
+    # No block was passed to #measure.
+    class NoBlockError < Frankenstein::Error; end
+
+    # Create a new request instrumentation package.
+    #
+    # A "request", for the purposes of this discussion, is a distinct
+    # interaction with an external system, typically either the receipt of some
+    # sort of communication from another system which needs a response by this
+    # system (the one being instrumented), or else the communication to another
+    # system from this one for which we are expecting an answer.  Each instance
+    # of this class should be used to instrument all requests of a particular
+    # type.
+    #
+    # For each instance of this class, the following metrics will be created:
+    #
+    # * `<prefix>_requests_total` -- a counter indicating the total number
+    #   of requests started (initiated or received by the system).  Labels on
+    #   this metric are taken from the label set passed to #measure.
+    #
+    # * `<prefix>_request_duration_seconds` -- a histogram for the response
+    #   times of successful responses (that is, where no exception was raised).
+    #   You can get the count of total successful responses from
+    #   `<prefix>_request_duration_seconds_count`.  Labels on this metric
+    #   are taken from the labels set generated during the measured run (as
+    #   generated by manipulating the hash yielded to your block).
+    #
+    # * `<prefix>_exceptions_total` -- a count of the number of exceptions
+    #   raised during processing.  A label, `class`, indicates the class of
+    #   the exception raised.  Labels on this metric are taken from the
+    #   label set passed to #measure, along with a special label `class`
+    #   to indicate the class of the exception raised.
+    #
+    # * `<prefix>_in_progress_count` -- a gauge indicating how many requests
+    #   are currently in progress as at the time of the scrape.  Labels on this
+    #   metric are taken from the label set passed to #measure.
+    #
+    # @param prefix [#to_s] the string that will be prepended to all of the
+    #   Prometheus metric names generated for this instrumentation.  The prefix
+    #   you choose should include both the application name (typically the
+    #   first word) as well as a unique identifier for the request type itself.
+    #   Multiple words should be underscore separated.
+    #
+    # @param outgoing [Boolean] whether this Request instance is collecting
+    #   data on incoming requests or outgoing requests (the default, as usually
+    #   there is one incoming request handler, but there can easily be several
+    #   outgoing request types).  It is only used to customise the metric
+    #   description text for the metrics, so it's not crucially important.
+    #
+    # @param description [#to_s] a short explanation of what this is measuring.
+    #   It should be a singular and indefinite noun phrase, to maximise the
+    #   chances that it will fit neatly into the generated description text.
+    #
+    # @param registry [Prometheus::Client::Registry] the client registry in
+    #   which all the metrics will be created.  The default will put all the
+    #   metrics in the Prometheus Client's default registry, which may or may
+    #   not be what you're up for.  If you're using Frankenstein::Server, you
+    #   want `stats_server.registry`.
+    #
+    def initialize(prefix, outgoing: true, description: prefix, registry: Prometheus::Client.registry)
+      @requests   = registry.counter(:"#{prefix}_requests_total", "Number of #{description} requests #{outgoing ? 'sent' : 'received'}")
+      @durations  = registry.histogram(:"#{prefix}_request_duration_seconds", "Time taken to #{outgoing ? 'receive' : 'send'} a #{description} response")
+      @exceptions = registry.counter(:"#{prefix}_exceptions_total", "Number of exceptions raised by the #{description} code")
+      @current    = registry.gauge(:"#{prefix}_in_progress_count", "Number of #{description} requests currently in progress")
+
+      # Prometheus::Client::Gauge doesn't (yet) have a built-in way to
+      # atomically "adjust" a gauge, only get the current value and set a
+      # new value.  To avoid the resulting textbook race condition, we
+      # need to wrap the get/set pair of operations in this handy-dandy
+      # mutex.
+      @mutex = Mutex.new
+    end
+
+    # Instrument an instance of the request.
+    #
+    # Each time a particular external communication occurs, it should be
+    # wrapped by a call to this method.  Request-related statistics (that
+    # the request has been made or received) are updated before the passed
+    # block is executed, and then after the block completes,
+    # response-related statistics (duration or exception) are recorded.  The
+    # number of currently-in-progress instances of the request are also kept
+    # track of.
+    #
+    # @param labels [Hash] a set of labels that can help to differentiate
+    #   different sorts of requests.  These labels are applied to the
+    #   `<prefix>_requests_total` and `<prefix>_in_progress_count` metrics, as
+    #   well as the `<prefix>_exceptions_total` metric, if an exception is
+    #   raised.
+    #
+    #   Don't get too fancy with this label set -- it's unusual that this is
+    #   actually useful in practice.  However it is provided for those unusual
+    #   cases where it isn't a bad idea.  Your go-to solution should be to
+    #   label the `<prefix>_request_duration_seconds` metric (by modifying the
+    #   hash yielded to the block you pass to #measure), rather than using
+    #   this parameter with wild abandon.
+    #
+    #   Serious talk time: I've been there.  It seems like a great idea at
+    #   first, to differentiate requests with lots of labels, but it usually
+    #   just ends up turning into a giant mess.  Primarily, due to the way that
+    #   Prometheus deals with label sets, if you *ever* use a label on *any* of
+    #   your requests, you need to set the same label to some value on *all* of
+    #   your requests.  So, unless you can say with certainty that every
+    #   request you receive will logically have some meaningful value for a
+    #   given label, you shouldn't use it.
+    #
+    #   **NOTE**: the labelset you specify here will be the default labelset
+    #   applied to the `<prefix>_request_duration_seconds` metric.  If you need
+    #   to remove a label from the response, use `labels.replace` or
+    #   `labels.delete` to remove the key.
+    #
+    # @yield [Hash] the labels that will be applied to the
+    #   `<Prefix>_request_duration_seconds` metric.
+    #
+    #   In order for your label set to be applied, you must *mutate the
+    #   hash that is yielded*, rather than overwriting it.  That means,
+    #   for example, that the following code **will not work**:
+    #
+    #       req_stats.measure do |labels|
+    #         labels = {foo: 'bar', baz: 'wombat'}
+    #         ...
+    #
+    #   Instead, you need to either set each key one by one, or use the
+    #   handy-dandy Hash#replace method, like this:
+    #
+    #       req_stats.measure do |labels|
+    #         labels.replace(foo: 'bar', baz: 'wombat')
+    #         ...
+    #
+    #   If your labels are not being applied to your response histogram,
+    #   check for any assignment to the yielded variable.  It's *really* easy
+    #   to do by mistake.
+    #
+    #   **NOTE WELL**: The Prometheus specification (assuming it exists)
+    #   apparently requires that all of the instances of a given metric
+    #   have the same set of labels.  If you fail to do this, an exception
+    #   will be raised by Prometheus after the block is executed.
+    #
+    # @raise [Prometheus::Request::NoBlockError] if you didn't pass a block to
+    #   call.  There's nothing to instrument!
+    #
+    # @raise [Prometheus::Client::LabelSetValidator::LabelSetError] if you
+    #   violate any written or unwritten rules about how Prometheus label
+    #   sets should be constructed.
+    #
+    # @raise [Exception] any exception raised by the executed block will
+    #   be re-raised by this method after statistics collection is
+    #   complete.
+    #
+    # @return [Object] whatever was returned by the block passed.
+    #
+    def measure(labels = {})
+      start_time = Time.now
+
+      unless block_given?
+        raise NoBlockError,
+          "No block passed to #{self.class}#measure"
+      end
+
+      @requests.increment(labels, 1)
+      @mutex.synchronize { @current.set(labels, (@current.get(labels) || 0) + 1) }
+
+      res_labels = labels.dup
+
+      begin
+        yield(res_labels).tap do
+          elapsed_time = Time.now - start_time
+          @durations.observe(res_labels, elapsed_time)
+        end
+      rescue Exception => ex
+        @exceptions.increment(labels.merge(class: ex.class.to_s), 1)
+        raise
+      ensure
+        @mutex.synchronize { @current.set(labels, @current.get(labels) - 1) }
+      end
+    end
+  end
+end

data/lib/frankenstein/server.rb

@@ -0,0 +1,121 @@
+require 'logger'
+require 'prometheus/client'
+require 'prometheus/middleware/collector'
+require 'prometheus/middleware/exporter'
+require 'rack'
+require 'rack/builder'
+require 'rack/handler/webrick'
+require 'rack/deflater'
+
+require 'frankenstein/error'
+
+module Frankenstein
+  # A straightforward Prometheus metrics server.
+  #
+  # When you're looking to instrument your application which isn't, itself, a
+  # HTTP service, you need this class.  It spawns a WEBrick server on a port you
+  # specify, and gives you a registry to put your metrics into.  That's pretty
+  # much it.
+  #
+  # The simplest example possible:
+  #
+  #     stats_server = Frankenstein::Server.new
+  #     stats_server.run   # We are now serving stats on port 8080!
+  #     counter = stats_server.registry.counter(:seconds_count, "Number of seconds")
+  #     # Give the counter something to count
+  #     loop { counter.increment({}) }
+  #
+  # Now if you hit http://localhost:8080/metrics you should see a counter
+  # gradually going up, along with stats about the Frankenstein HTTP server
+  # itself.  Neato!
+  #
+  # You can change how the webserver logs, and the port it listens on, with options
+  # to #new.  If for some reason you need to shut down the webserver manually, use
+  # #shutdown.
+  #
+  class Server
+    # Indicate that the server is already running
+    class AlreadyRunningError < Frankenstein::Error; end
+
+    # The instance of Prometheus::Client::Registry that contains the metrics
+    # that will be presented by this instance of Frankenstein::Server.
+    attr_reader :registry
+
+    # Create a new server instance.
+    #
+    # @param port [Integer] the TCP to listen on.
+    #
+    # @param logger [Logger] send log messages from WEBrick to this logger.
+    #   If not specified, all log messages will be silently eaten.
+    #
+    # @param metrics_prefix [#to_s] The prefix to apply to the metrics exposed
+    #   instrumenting the metrics server itself.
+    #
+    # @param registry [Prometheus::Client::Registry] if you want to use an existing
+    #   metrics registry for this server, pass it in here.  Otherwise, a new one
+    #   will be created for you, and be made available via #registry.
+    #
+    def initialize(port: 8080, logger: nil, metrics_prefix: "frankenstein_server", registry: Prometheus::Client::Registry.new)
+      @port           = port
+      @logger         = logger || Logger.new(RbConfig::CONFIG['host_os'] =~ /mingw|mswin/ ? 'NUL' : '/dev/null')
+      @metrics_prefix = metrics_prefix
+      @registry       = registry
+
+      @op_mutex = Mutex.new
+      @op_cv    = ConditionVariable.new
+    end
+
+    # Start the server instance running.
+    #
+    # This method returns once the server is just about ready to start serving
+    # requests.
+    #
+    def run
+      @op_mutex.synchronize do
+        return AlreadyRunningError if @server
+
+        @server_thread = Thread.new do
+          @op_mutex.synchronize do
+            @server = WEBrick::HTTPServer.new(Logger: @logger, BindAddress: nil, Port: @port)
+            @server.mount "/", Rack::Handler::WEBrick, app
+            @op_cv.signal
+          end
+          @server.start
+        end
+      end
+
+      @op_mutex.synchronize { @op_cv.wait(@op_mutex) until @server }
+    end
+
+    # Terminate a running server instance.
+    #
+    # If the server isn't currently running, this call is a no-op.
+    #
+    def shutdown
+      @op_mutex.synchronize do
+        return nil if @server.nil?
+        @server.shutdown
+        @server = nil
+        @server_thread.join
+        @server_thread = nil
+      end
+    end
+
+    private
+
+    def app
+      @app ||= begin
+        builder = Rack::Builder.new
+        builder.use Rack::Deflater, if: ->(_, _, _, body) { body.any? && body[0].length > 512 }
+        builder.use Prometheus::Middleware::Collector,
+          registry: @registry,
+          metrics_prefix: @metrics_prefix,
+          counter_label_builder: ->(_, _) { {} },
+          duration_label_builder: ->(_, _) { {} }
+        builder.use Prometheus::Middleware::Exporter, registry: @registry
+        builder.run ->(_) { [301, { 'Location' => "/metrics", 'Content-Type' => 'text/plain' }, ["Try /metrics"]] }
+        builder.to_app
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,255 @@
+--- !ruby/object:Gem::Specification
+name: frankenstein
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Palmer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-08-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prometheus-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: git-version-bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  This is a collection of useful tools to help you in more easily
+  instrumenting Ruby applications for the Prometheus monitoring
+  system.
+email:
+- matt.palmer@discourse.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".travis.yml"
+- ".yardopts"
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENCE
+- README.md
+- frankenstein.gemspec
+- lib/frankenstein.rb
+- lib/frankenstein/error.rb
+- lib/frankenstein/request.rb
+- lib/frankenstein/server.rb
+homepage: https://github.com/discourse/frankenstein
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: or, the Modern Prometheus
+test_files: []