frankenstein 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f2e7a82ed23dd4f853c7d0eea1c8b0ac334977ec
-  data.tar.gz: f2431b5567a6086f2c9cafa07f6496d1039ebccb
+SHA256:
+  metadata.gz: 6ba12d5e4ad9e76a2bec62028b14952b2081b7ea16dbabf00eb14eb1db4b0ab6
+  data.tar.gz: 23d575919475820563f308fdb335e16089eb981c2350c3484e191330fc74d90d
 SHA512:
-  metadata.gz: 942dafc43941ce8724b387116463f90128780d67e97ecfadd8dde579273c9477cf3bea3447244cf23cfeadf7e004ba23675392e1060dc8d2f9e9f1fdf64966b6
-  data.tar.gz: 1a64333bb6f7c0ff58eebaeca68a921647b01e763e36362a7a6c3994127a3b3a1ca091b888806b713dda7fe9062decf89c66f09d6a4f45f4f78ec4f35815b250
+  metadata.gz: 6e8286ddd22170784525f2f81e76a0ff646e0ae91318539fb6fafac71c6fab537ffcdc33be5756ef048a16ea220a5ef5ce182c2ac5ab5dbdc956e4fd8d079676
+  data.tar.gz: f35c4da5e96629af26b9a49f47c4a639d3199025a437e63ab2ecd2f1ff2364529774935879f5c3014422e565aed4710727737848912cb1dc467b924f0f421248

data/frankenstein.gemspec

@@ -27,22 +27,17 @@ Gem::Specification.new do |s|
 
   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.8.0"
+  s.add_runtime_dependency "prometheus-client", "~> 2.0"
   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/collected_metric.rb

@@ -65,6 +65,9 @@ module Frankenstein
     #
     # @param docstring [#to_s] the descriptive help text for the metric.
     #
+    # @param labels [Array<Symbol>] the labels which all time series for this
+    #   metric must possess.
+    #
     # @param type [Symbol] what type of metric you're returning.  It's uncommon
     #   to want anything other than `:gauge` here (the default), because
     #   when you're collecting external data it's unlikely you'll be able to
@@ -87,8 +90,8 @@ module Frankenstein
     #
     # @param collector [Proc] the code to run on every scrape request.
     #
-    def initialize(name, docstring, type: :gauge, logger: Logger.new('/dev/null'), registry: Prometheus::Client.registry, &collector)
-      @validator = Prometheus::Client::LabelSetValidator.new
+    def initialize(name, docstring:, labels: [], type: :gauge, logger: Logger.new('/dev/null'), registry: Prometheus::Client.registry, &collector)
+      @validator = Prometheus::Client::LabelSetValidator.new(expected_labels: labels)
 
       validate_name(name)
       validate_docstring(docstring)
@@ -104,14 +107,14 @@ module Frankenstein
       @registry  = registry
       @collector = collector
 
-      @errors_metric = @registry.counter(:"#{@name}_collection_errors_total", "Errors encountered while collecting for #{@name}")
+      @errors_metric = @registry.counter(:"#{@name}_collection_errors_total", docstring: "Errors encountered while collecting for #{@name}")
       @registry.register(self)
     end
 
     # Retrieve the value for the given labelset.
     #
     def get(labels = {})
-      @validator.validate(labels)
+      @validator.validate_labelset!(labels)
 
       values[labels]
     end
@@ -126,7 +129,7 @@ module Frankenstein
             @errors_metric.increment(class: "NotAHashError")
             return {}
           end
-          results.keys.each { |labelset| @validator.validate(labelset) }
+          results.keys.each { |labelset| @validator.validate_labelset!(labelset) }
         end
       rescue StandardError => ex
         @logger.error(progname) { (["Exception in collection: #{ex.message} (#{ex.class})"] + ex.backtrace).join("\n  ") }

data/lib/frankenstein/process_metrics.rb

@@ -18,7 +18,7 @@ module Frankenstein
     # @param logger [Logger] where to log any problems which some sort of
     #
     def self.register(registry = Prometheus::Client.registry, logger: Logger.new("/dev/null"))
-      registry.gauge(:process_start_time_seconds, "Start time of the process since unix epoch in seconds").set({}, Time.now.to_f)
+      registry.gauge(:process_start_time_seconds, docstring: "Start time of the process since unix epoch in seconds").set(Time.now.to_f)
 
       page_size = Etc.sysconf(Etc::SC_PAGESIZE)
       hz        = Etc.sysconf(Etc::SC_CLK_TCK)
@@ -26,17 +26,17 @@ module Frankenstein
       stat_file = "/proc/#{Process.pid}/stat".freeze
 
       if File.exist?(stat_file)
-        Frankenstein::CollectedMetric.new(:process_cpu_seconds_total, "Total user and system CPU time spent in seconds", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_cpu_seconds_total, docstring: "Total user and system CPU time spent in seconds", registry: registry, logger: logger, labels: [:mode]) do
           stats = File.read(stat_file).split(" ")
           { { mode: "user" } => stats[13].to_f / hz, { mode: "system" } => stats[14].to_f / hz }
         end
 
-        Frankenstein::CollectedMetric.new(:process_virtual_memory_bytes, "Virtual memory size in bytes", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_virtual_memory_bytes, docstring: "Virtual memory size in bytes", registry: registry, logger: logger) do
           stats = File.read(stat_file).split(" ")
           { {} => stats[22].to_i }
         end
 
-        Frankenstein::CollectedMetric.new(:process_resident_memory_bytes, "Resident memory size in bytes", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_resident_memory_bytes, docstring: "Resident memory size in bytes", registry: registry, logger: logger) do
           stats = File.read(stat_file).split(" ")
           { {} => stats[23].to_i * page_size }
         end
@@ -45,23 +45,23 @@ module Frankenstein
       fd_dir = "/proc/#{Process.pid}/fd".freeze
 
       if File.exist?(fd_dir)
-        Frankenstein::CollectedMetric.new(:process_open_fds, "Number of open file descriptors", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_open_fds, docstring: "Number of open file descriptors", registry: registry, logger: logger) do
           { {} => Dir["#{fd_dir}/*"].length }
         end
       end
 
       if Process.respond_to?(:getrlimit)
-        Frankenstein::CollectedMetric.new(:process_max_fds, "Maximum number of open file descriptors", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_max_fds, docstring: "Maximum number of open file descriptors", registry: registry, logger: logger) do
           { {} => Process.getrlimit(:NOFILE).first }
         end
 
-        Frankenstein::CollectedMetric.new(:process_virtual_memory_max_bytes, "Maximum amount of virtual memory available in bytes", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_virtual_memory_max_bytes, docstring: "Maximum amount of virtual memory available in bytes", registry: registry, logger: logger) do
           { {} => Process.getrlimit(:AS).first }
         end
       end
 
       if GC.respond_to?(:stat) && GC.stat[:heap_allocated_pages]
-        Frankenstein::CollectedMetric.new(:process_heap_bytes, "Process heap size in bytes", registry: registry, logger: logger) do
+        Frankenstein::CollectedMetric.new(:process_heap_bytes, docstring: "Process heap size in bytes", registry: registry, logger: logger) do
           { {} => GC.stat[:heap_allocated_pages] * page_size }
         end
       end

data/lib/frankenstein/remove_time_series.rb

@@ -0,0 +1,25 @@
+module Frankenstein
+	# Mix-in to add #remove to Prometheus metrics
+	module RemoveTimeSeries
+		# Remove a time series from a metric.
+		#
+		# @param labels [Hash<Symbol, String>] the label set to remove.
+		#
+		def remove(labels)
+			@store.remove(labels)
+		end
+
+		# Mix-in to add #remove support to the default Synchronized metric store.
+		module SynchronizedMetricStore
+			# Remove a time series from the metric store.
+			#
+			# @private
+			def remove(labels)
+				@internal_store.delete(labels)
+			end
+		end
+	end
+end
+
+Prometheus::Client::Metric.include(Frankenstein::RemoveTimeSeries)
+Prometheus::Client::DataStores::Synchronized.const_get(:MetricStore).include(Frankenstein::RemoveTimeSeries::SynchronizedMetricStore)

data/lib/frankenstein/request.rb

@@ -65,17 +65,25 @@ module Frankenstein
     #   It should be a singular and indefinite noun phrase, to maximise the
     #   chances that it will fit neatly into the generated description text.
     #
+    # @param labels [Array<Symbol>] the names of the labels that will be
+    #   set on most of the metrics created by this instance.
+    #
+    # @param duration_labels [Array<Symbol>] the names of the labels which will
+    #   be set on the `_duration_seconds` histogram.  By default, the value
+    #   of the `labels` parameter will be used, but if you want to have a separate
+    #   label set for your duration histogram, this is what you want.
+    #
     # @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")
+    def initialize(prefix, labels: [], duration_labels: nil, outgoing: true, description: prefix, registry: Prometheus::Client.registry)
+      @requests   = registry.counter(:"#{prefix}_requests_total", docstring: "Number of #{description} requests #{outgoing ? 'sent' : 'received'}", labels: labels)
+      @durations  = registry.histogram(:"#{prefix}_request_duration_seconds", docstring: "Time taken to #{outgoing ? 'receive' : 'send'} a #{description} response", labels: duration_labels || labels)
+      @exceptions = registry.counter(:"#{prefix}_exceptions_total", docstring: "Number of exceptions raised by the #{description} code", labels: labels + [:class])
+      @current    = registry.gauge(:"#{prefix}_in_progress_count", docstring: "Number of #{description} requests currently in progress", labels: labels)
 
       # Prometheus::Client::Gauge doesn't (yet) have a built-in way to
       # atomically "adjust" a gauge, only get the current value and set a
@@ -149,7 +157,7 @@ module Frankenstein
     #   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
+    # @raise [Frankenstein::Request::NoBlockError] if you didn't pass a block to
     #   call.  There's nothing to instrument!
     #
     # @raise [Prometheus::Client::LabelSetValidator::LabelSetError] if you
@@ -170,21 +178,21 @@ module Frankenstein
           "No block passed to #{self.class}#measure"
       end
 
-      @requests.increment(labels, 1)
-      @mutex.synchronize { @current.set(labels, (@current.get(labels) || 0) + 1) }
+      @requests.increment(labels: labels)
+      @mutex.synchronize { @current.set((@current.get(labels: labels) || 0) + 1, labels: labels) }
 
       res_labels = labels.dup
 
       begin
         yield(res_labels).tap do
           elapsed_time = Time.now - start_time
-          @durations.observe(res_labels, elapsed_time)
+          @durations.observe(elapsed_time, labels: res_labels)
         end
       rescue Exception => ex
-        @exceptions.increment(labels.merge(class: ex.class.to_s), 1)
+        @exceptions.increment(labels: labels.merge(class: ex.class.to_s))
         raise
       ensure
-        @mutex.synchronize { @current.set(labels, @current.get(labels) - 1) }
+        @mutex.synchronize { @current.set(@current.get(labels: labels) - 1, labels: labels) }
       end
     end
   end

data/lib/frankenstein/ruby_gc_metrics.rb

@@ -15,7 +15,7 @@ module Frankenstein
     #
     def self.register(registry = Prometheus::Client.registry)
       GC.stat.each do |k, v|
-        Frankenstein::CollectedMetric.new(:"ruby_gc_#{k}", "Ruby GC parameter #{k}", registry: registry) do
+        Frankenstein::CollectedMetric.new(:"ruby_gc_#{k}", docstring: "Ruby GC parameter #{k}", registry: registry) do
           { {} => GC.stat[k] }
         end
       end

data/lib/frankenstein/ruby_vm_metrics.rb

@@ -15,7 +15,7 @@ module Frankenstein
     #
     def self.register(registry = Prometheus::Client.registry)
       RubyVM.stat.each do |k, v|
-        Frankenstein::CollectedMetric.new(:"ruby_vm_#{k}", "Ruby VM parameter #{k}", registry: registry) do
+        Frankenstein::CollectedMetric.new(:"ruby_vm_#{k}", docstring: "Ruby VM parameter #{k}", registry: registry) do
           { {} => RubyVM.stat[k] }
         end
       end

data/lib/frankenstein/server.rb

@@ -66,41 +66,35 @@ module Frankenstein
       @op_cv    = ConditionVariable.new
     end
 
-    # Start the server instance running in a separate thread.
+    # Start the server instance running.
     #
-    # This method returns once the server is just about ready to start serving
-    # requests.
+    # This method will return only after `#shutdown` is called (presumably from
+    # another thread).
     #
     def run
       @op_mutex.synchronize do
         return AlreadyRunningError if @server
 
-        @server_thread = Thread.new do
-          @op_mutex.synchronize do
-            begin
-              wrapped_logger = Frankenstein::Server::WEBrickLogger.new(logger: @logger, progname: "Frankenstein::Server")
-              @server = WEBrick::HTTPServer.new(Logger: wrapped_logger, BindAddress: nil, Port: @port, AccessLog: [[wrapped_logger, WEBrick::AccessLog::COMMON_LOG_FORMAT]])
-              @server.mount "/", Rack::Handler::WEBrick, app
-            rescue => ex
-              #:nocov:
-              @logger.fatal("Frankenstein::Server#run") { (["Exception while trying to create WEBrick::HTTPServer: #{ex.message} (#{ex.class})"] + ex.backtrace).join("\n  ") }
-              #:nocov:
-            ensure
-              @op_cv.signal
-            end
-          end
-
-          begin
-            @server.start if @server
-          rescue => ex
-            #:nocov:
-            @logger.fatal("Frankenstein::Server#run") { (["Exception while running WEBrick::HTTPServer: #{ex.message} (#{ex.class})"] + ex.backtrace).join("\n  ") }
-            #:nocov:
-          end
+        begin
+          wrapped_logger = Frankenstein::Server::WEBrickLogger.new(logger: @logger, progname: "Frankenstein::Server")
+          @server = WEBrick::HTTPServer.new(Logger: wrapped_logger, BindAddress: nil, Port: @port, AccessLog: [[wrapped_logger, WEBrick::AccessLog::COMMON_LOG_FORMAT]])
+          @server.mount "/", Rack::Handler::WEBrick, app
+        rescue => ex
+          #:nocov:
+          @logger.fatal("Frankenstein::Server#run") { (["Exception while trying to create WEBrick::HTTPServer: #{ex.message} (#{ex.class})"] + ex.backtrace).join("\n  ") }
+          #:nocov:
+        ensure
+          @op_cv.signal
         end
       end
 
-      @op_mutex.synchronize { @op_cv.wait(@op_mutex) until @server }
+      begin
+        @server.start if @server
+      rescue => ex
+        #:nocov:
+        @logger.fatal("Frankenstein::Server#run") { (["Exception while running WEBrick::HTTPServer: #{ex.message} (#{ex.class})"] + ex.backtrace).join("\n  ") }
+        #:nocov:
+      end
     end
 
     # Terminate a running server instance.
@@ -112,8 +106,6 @@ module Frankenstein
         return nil if @server.nil?
         @server.shutdown
         @server = nil
-        @server_thread.join
-        @server_thread = nil
       end
     end
 
@@ -125,9 +117,7 @@ module Frankenstein
         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: ->(_, _) { {} }
+          metrics_prefix: @metrics_prefix
         builder.use Prometheus::Middleware::Exporter, registry: @registry
         builder.run ->(_) { [301, { 'Location' => "/metrics", 'Content-Type' => 'text/plain' }, ["Try /metrics"]] }
         builder.to_app

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: frankenstein
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Matt Palmer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-13 00:00:00.000000000 Z
+date: 2020-06-01 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.8.0
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -94,20 +94,6 @@ dependencies:
     - - ">="
       - !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
@@ -164,20 +150,6 @@ dependencies:
     - - ">="
       - !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
@@ -217,7 +189,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".rubocop.yml"
 - ".travis.yml"
 - ".yardopts"
 - CODE_OF_CONDUCT.md
@@ -229,6 +200,7 @@ files:
 - lib/frankenstein/collected_metric.rb
 - lib/frankenstein/error.rb
 - lib/frankenstein/process_metrics.rb
+- lib/frankenstein/remove_time_series.rb
 - lib/frankenstein/request.rb
 - lib/frankenstein/ruby_gc_metrics.rb
 - lib/frankenstein/ruby_vm_metrics.rb
@@ -252,8 +224,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: or, the Modern Prometheus

data/.rubocop.yml

@@ -1,104 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.4
-  DisabledByDefault: true
-
-# Prefer &&/|| over and/or.
-Style/AndOr:
-  Enabled: true
-
-# Do not use braces for hash literals when they are the last argument of a
-# method call.
-Style/BracesAroundHashParameters:
-  Enabled: true
-
-# Align `when` with `case`.
-Layout/CaseIndentation:
-  Enabled: true
-
-# Align comments with method definitions.
-Layout/CommentIndentation:
-  Enabled: true
-
-# No extra empty lines.
-Layout/EmptyLines:
-  Enabled: true
-
-# Use Ruby >= 1.9 syntax for hashes. Prefer { a: :b } over { :a => :b }.
-Style/HashSyntax:
-  Enabled: true
-
-# Two spaces, no tabs (for indentation).
-Layout/IndentationWidth:
-  Enabled: true
-
-Layout/SpaceAfterColon:
-  Enabled: true
-
-Layout/SpaceAfterComma:
-  Enabled: true
-
-Layout/SpaceAroundEqualsInParameterDefault:
-  Enabled: true
-
-Layout/SpaceAroundKeyword:
-  Enabled: true
-
-Layout/SpaceAroundOperators:
-  Enabled: true
-
-Layout/SpaceBeforeFirstArg:
-    Enabled: true
-
-# Defining a method with parameters needs parentheses.
-Style/MethodDefParentheses:
-  Enabled: true
-
-# Use `foo {}` not `foo{}`.
-Layout/SpaceBeforeBlockBraces:
-  Enabled: true
-
-# Use `foo { bar }` not `foo {bar}`.
-Layout/SpaceInsideBlockBraces:
-  Enabled: true
-
-# Use `{ a: 1 }` not `{a:1}`.
-Layout/SpaceInsideHashLiteralBraces:
-  Enabled: true
-
-Layout/SpaceInsideParens:
-  Enabled: true
-
-# Detect hard tabs, no hard tabs.
-Layout/Tab:
-  Enabled: true
-
-# Blank lines should not have any spaces.
-Layout/TrailingBlankLines:
-  Enabled: true
-
-# No trailing whitespace.
-Layout/TrailingWhitespace:
-  Enabled: true
-
-Lint/BlockAlignment:
-  Enabled: true
-
-# Align `end` with the matching keyword or starting expression except for
-# assignments, where it should be aligned with the LHS.
-Lint/EndAlignment:
-  Enabled: true
-  EnforcedStyleAlignWith: variable
-
-# Use my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
-Lint/RequireParentheses:
-  Enabled: true
-
-Layout/MultilineMethodCallIndentation:
-  Enabled: true
-  EnforcedStyle: indented
-
-Layout/AlignHash:
-  Enabled: true
-
-Bundler/OrderedGems:
-  Enabled: false