fintop 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 0.0.1 (4/1/2014)
+
+- Initial version of Fintop. Probes stats and threads endpoints of Finagle
+  servers built on [TwitterServer](http://twitter.github.io/twitter-server/)
+  with either [Ostrich](https://github.com/twitter/ostrich) or
+  [MetricsTM](https://github.com/twitter/commons/tree/master/src/java/com/twitter/common/metrics).
+  Prints basic statistics in top-like tabular output.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in fintop.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Evan Meagher
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,30 @@
+# fintop
+
+A top-like utility for monitoring [Finagle](http://github.com/twitter/finagle) servers.
+
+## Installation
+
+The `fintop` gem hasn't been published yet, so is currently only usable from
+source. To install `fintop` locally, clone this repository and run
+`rake install` from within the repository's root directory.
+
+## Usage
+
+`fintop` is intended to be used in a similar fashion as the `top` suite of
+monitoring programs. For example, given two Finagle servers running locally,
+running `fintop` could look like this:
+
+    $ fintop
+    Finagle processes: 2, Threads: 44 total, 30 runnable, 14 waiting
+
+    PID     PORT   CPU   #TH   #NOND  #RUN   #WAIT   #TWAIT   TXKB       RXKB
+    14909   1110   4.0   22    1      15     4       3        351        363
+    14905   9990   4.0   22    1      15     4       3        325        823
+
+## Contributing
+
+1. [Fork the repository](http://github.com/evnm/fintop/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. [Create new Pull Request](https://help.github.com/articles/creating-a-pull-request)

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end

data/bin/fintop

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require 'fintop/printer'
+require 'fintop/probe'
+require 'fintop/threads'
+
+finagle_procs = Fintop::Probe.apply
+Fintop::Printer.apply(finagle_procs)
+

data/fintop.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fintop/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'fintop'
+  s.version       = Fintop::VERSION
+  s.authors       = ['Evan Meagher']
+  s.email         = ['evan.meagher@gmail.com']
+  s.summary       = %q{A top-like utility for monitoring Finagle servers}
+  s.license       = 'MIT'
+
+  s.files         = `git ls-files -z`.split("\x0")
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'bundler', '~> 1.5'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'test-unit', '~> 2.5'
+
+  s.add_dependency 'json'
+end

data/lib/fintop.rb

@@ -0,0 +1,8 @@
+require 'fintop/metrics'
+require 'fintop/printer'
+require 'fintop/probe'
+require 'fintop/threads'
+require 'fintop/version'
+
+module Fintop
+end

data/lib/fintop/metrics.rb

@@ -0,0 +1,78 @@
+require 'json'
+require 'net/http'
+
+module Fintop
+  # Contains functions that gather Finagle application metrics.
+  module Metrics
+    extend self
+
+    # Query a Finagle server's stats endpoint to produce a hash of metrics.
+    #
+    # @param finp [FinagleProcess]
+    def apply(finp)
+      case finp.stats_lib
+      when :metrics_tm
+        scrape_metrics_tm(finp.admin_port)
+      when :ostrich
+        scrape_ostrich(finp.admin_port)
+      else
+        raise ArgumentError.new('invalid `FinagleProcess.stats_lib` symbol')
+      end
+    end
+
+    # Parses a JSON object of MetricsTM-style stats into a hash.
+    #
+    # @param json_str [String] a JSON string of MetricsRM-style stats data
+    def process_metrics_tm_json(json_str)
+      result = {}
+      JSON.parse(json_str).each { |k, v|
+        prefix, rest = k.split('/', 2)
+        (result[prefix] ||= {})[rest] = v
+      }
+      result
+    end
+
+    # Parses a JSON object of Ostrich-style stats into a hash.
+    #
+    # @param json_str [String] a JSON string of Ostrich-style stats data
+    def process_ostrich_json(json_str)
+      json = JSON.parse(json_str)
+
+      # Note: We currently only gather counter and gauge data.
+      result = {}
+      json['counters'].merge(json['gauges']).each { |k, v|
+        # Do a dance in order to get around the fact that Ostrich doesn't prefix
+        # JVM-related metrics with "jvm/".
+        until_first_slash, slash_rest = k.split('/', 2)
+        until_first_underscore, us_rest = until_first_slash.split('_', 2)
+        prefix = until_first_underscore
+        rest = us_rest.to_s + slash_rest.to_s
+        (result[prefix] ||= {})[rest] = v
+      }
+      result
+    end
+
+    # Fetch metrics from a MetricsTM stats endpoint (/admin/metrics.json).
+    # Returns a nested hash keyed by the metric prefix.
+    # i.e. { jvm => { uptime => 18251.0, fd_count = 203.0, ... }, ... }
+    #
+    # @param admin_port [Fixnum]
+    def scrape_metrics_tm(admin_port)
+      json_str = Net::HTTP.get(
+        URI.parse("http://localhost:#{admin_port}/admin/metrics.json")
+      )
+
+      process_metrics_tm_json(json_str)
+    end
+
+    # Fetch metrics from an Ostrich stats endpoint (/stats.json).
+    # Returns a nested hash keyed by the metric prefix.
+    # i.e. { jvm => { uptime => 18251.0, fd_count = 203.0, ... }, ... }
+    #
+    # @param admin_port [Fixnum]
+    def scrape_ostrich(admin_port)
+      json_str = Net::HTTP.get(URI.parse("http://localhost:#{admin_port}/stats.json"))
+      process_ostrich_json(json_str)
+    end
+  end
+end

data/lib/fintop/printer.rb

@@ -0,0 +1,107 @@
+require 'fintop/metrics'
+require 'pp'
+
+module Fintop
+  # Contains functions that gather and print operational data on local
+  # Finagle processes.
+  module Printer
+    extend self
+
+    # Given an array of Fintop::Probe::FinagleProcess objects, gather data
+    # and print output.
+    #
+    # @param finagle_procs [Array<FinagleProcess>]
+    def apply(finagle_procs)
+      if finagle_procs.empty?
+        puts 'Finagle processes: 0'
+        exit
+      end
+
+      # Create a hash of pid=>ThreadsData objects.
+      threads_data_hash = Hash[
+        finagle_procs.map { |finp|
+          [finp.pid, Fintop::ThreadsData.new(finp.admin_port)]
+        }
+      ]
+
+      metrics_hash = Hash[
+        finagle_procs.map { |finp|
+          [finp.pid, Fintop::Metrics.apply(finp)]
+        }
+      ]
+
+      print_header(threads_data_hash)
+
+      finagle_procs.each { |finp|
+        threads_data = threads_data_hash[finp.pid]
+        metrics = metrics_hash[finp.pid]
+
+        tx_bytes, rx_bytes = [0, 0]
+        metrics.values.each { |scoped_metrics|
+          scoped_metrics.each { |k, v|
+            if not (k =~ /\/sent_bytes$/).nil?
+              tx_bytes = v / 1024
+            elsif not (k =~ /\/received_bytes$/).nil?
+              rx_bytes = v / 1024
+            end
+          }
+        }
+
+        printf(
+          @@row_format_str,
+          finp.pid,
+          finp.admin_port,
+          metrics['jvm']['num_cpus'].to_f,
+          threads_data.num_threads,
+          threads_data.num_non_daemon,
+          threads_data.num_runnable,
+          threads_data.num_waiting,
+          threads_data.num_timed_waiting,
+          tx_bytes,
+          rx_bytes
+        )
+      }
+    end
+
+    private
+
+    @@row_format_str = "%-7s %-6s %-5s %-5s %-6s %-6s %-7s %-8s %-10s %-10s\n"
+
+    # Print a total process/thread synopsis and column headers.
+    #
+    # @param threads_data_hash [Hash<Fixnum, ThreadsData>] a hash of pids and
+    # their corresponding ThreadsData objects.
+    def print_header(threads_data_hash)
+      total_threads = threads_data_hash.values.map { |t|
+        t.num_threads
+      }.inject(:+)
+
+      runnable_threads = threads_data_hash.values.map { |t|
+        t.num_runnable
+      }.inject(:+)
+
+      waiting_threads = threads_data_hash.values.map { |t|
+        t.num_waiting + t.num_timed_waiting
+      }.inject(:+)
+
+      puts "Finagle processes: #{threads_data_hash.size}, "\
+           "Threads: #{total_threads} total, "\
+           "#{runnable_threads} runnable, "\
+           "#{waiting_threads} waiting"
+      puts
+      printf(
+        @@row_format_str,
+        'PID',
+        'PORT',
+        'CPU',
+        '#TH',
+        '#NOND',
+        '#RUN',
+        '#WAIT',
+        '#TWAIT',
+        'TXKB',
+        'RXKB'
+      )
+    end
+  end
+end

data/lib/fintop/probe.rb

@@ -0,0 +1,68 @@
+require 'net/http'
+require 'timeout'
+
+module Fintop
+  # Contains functions for probing a system to discover Finagle server
+  # processes running locally.
+  module Probe
+    extend self
+
+    class FinagleProcess
+      attr_reader :pid
+      attr_reader :admin_port
+      attr_reader :stats_lib
+
+      def initialize(pid, admin_port, stats_lib)
+        @pid = pid
+        @admin_port = admin_port
+        @stats_lib = stats_lib
+      end
+    end
+
+    # Probe localhost for Finagle servers.
+    #
+    # Probing targets are Java processes listening on a TCP socket serving
+    # the path "/admin". Function returns an array of FinagleProcess objects
+    def apply
+      # Invoke jps and filter out nailgun servers and the jps process itself.
+      jps_cmd_str = '$JAVA_HOME/bin/jps | '\
+                    'grep -v NGServer | '\
+                    'grep -v Jps | '\
+                    "awk '{print $1}'"
+
+      finagle_pids = `#{jps_cmd_str}`.split.map { |pid|
+        # Filter for the processes that are listening on a TCP port.
+        lsof_cmd_str = "lsof -P -i tcp -a -p #{pid} | grep LISTEN | awk '{print $9}'"
+        port_match = /\d+/.match(`#{lsof_cmd_str}`)
+        port_match && [pid, port_match[0]]
+      }.compact.map { |pid, admin_port|
+        # Probe the possible ping endpoints to determine which (if any) stats
+        # library is in use.
+        begin
+          # Manual timeout to bail out of hung requests to un-listened-on ports.
+          Timeout::timeout(0.3) do
+            if is_resolvable(admin_port, '/admin/metrics.json')
+              FinagleProcess.new(pid, admin_port, :metrics_tm)
+            elsif is_resolvable(admin_port, '/stats.json')
+              FinagleProcess.new(pid, admin_port, :ostrich)
+            else
+              nil
+            end
+          end
+        rescue Errno::ECONNREFUSED, Timeout::Error
+          nil
+        end
+      }.compact
+    end
+
+    # Returns true if localhost:admin_port/path is resolvable.
+    #
+    # @param admin_port [Fixnum]
+    # @param path [String]
+    def is_resolvable(admin_port, path)
+      Net::HTTP.start('localhost', admin_port) { |http|
+        http.head(path).code.to_i == 200
+      }
+    end
+  end
+end

data/lib/fintop/threads.rb

@@ -0,0 +1,43 @@
+require 'json'
+require 'net/http'
+
+module Fintop
+  # Container class for data gathered from a Finagle server's
+  # thread-dump endpoint.
+  class ThreadsData
+    attr_reader :num_threads
+    attr_reader :num_runnable
+    attr_reader :num_waiting
+    attr_reader :num_timed_waiting
+    attr_reader :num_non_daemon
+
+    # Initialize a ThreadsData object for a Finagle server's on a given
+    # port's "/admin/threads" endpoint.
+    #
+    # @param admin_port [Fixnum]
+    def initialize(admin_port)
+      json_str = Net::HTTP.get(
+        URI.parse("http://localhost:#{admin_port}/admin/threads")
+      )
+
+      @threads = JSON.parse(json_str)['threads'].to_a
+      @num_threads = @threads.size
+
+      @num_runnable = @threads.count { |tid, thread|
+        thread['state'] == 'RUNNABLE'
+      }
+
+      @num_waiting = @threads.count { |tid, thread|
+        thread['state'] == 'WAITING'
+      }
+
+      @num_timed_waiting = @threads.count { |tid, thread|
+        thread['state'] == 'TIMED_WAITING'
+      }
+
+      @num_non_daemon = @threads.count { |tid, thread|
+        thread['daemon'] == false
+      }
+    end
+  end
+end

data/lib/fintop/version.rb

@@ -0,0 +1,3 @@
+module Fintop
+  VERSION = '0.0.1'
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+TEST_DIR = File.dirname(__FILE__)
+%w(lib test).each do |dir|
+  $LOAD_PATH.unshift "#{TEST_DIR}/../#{dir}"
+end
+
+require 'test/unit'
+require 'rubygems'

data/test/test_metrics.rb

@@ -0,0 +1,50 @@
+require 'test_helper'
+require 'fintop/metrics'
+
+class MetricsTest < Test::Unit::TestCase
+  def test_process_ostrich_json_parses_valid_json_string
+    json_str = %q{{"counters":{"srv\/http\/received_bytes":37},"gauges":{"jvm_uptime":219,"srv\/http\/connections":1}}}
+    expected = {
+      'srv'=>{'http/received_bytes'=>37,'http/connections'=>1},
+      'jvm'=>{'uptime'=>219}
+    }
+    output = Fintop::Metrics.process_ostrich_json(json_str)
+
+    assert_equal(output, expected)
+  end
+
+  def test_process_ostrich_json_throws_on_empty_string
+    assert_raise JSON::ParserError do
+      Fintop::Metrics.process_ostrich_json("")
+    end
+  end
+
+  def test_process_ostrich_json_throws_on_invalid_json_string
+    assert_raise JSON::ParserError do
+      Fintop::Metrics.process_ostrich_json("{j")
+    end
+  end
+
+  def test_process_metrics_tm_json_parses_valid_json_string
+    json_str = %q{{"jvm\/uptime":183.0,"srv\/http\/connections":1.0,"srv\/http\/received_bytes":96}}
+    expected = {
+      'srv'=>{'http/received_bytes'=>96,'http/connections'=>1.0},
+      'jvm'=>{'uptime'=>183.0}
+    }
+    output = Fintop::Metrics.process_metrics_tm_json(json_str)
+
+    assert_equal(output, expected)
+  end
+
+  def test_process_metrics_tm_json_throws_on_empty_string
+    assert_raise JSON::ParserError do
+      Fintop::Metrics.process_metrics_tm_json("")
+    end
+  end
+
+  def test_process_metrics_tm_json_throws_on_invalid_json_string
+    assert_raise JSON::ParserError do
+      Fintop::Metrics.process_metrics_tm_json("{j")
+    end
+  end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification 
+name: fintop
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Evan Meagher
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2014-04-01 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 1
+        - 5
+        version: "1.5"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 2
+        - 5
+        version: "2.5"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id004
+description: 
+email: 
+- evan.meagher@gmail.com
+executables: 
+- fintop
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/fintop
+- fintop.gemspec
+- lib/fintop.rb
+- lib/fintop/metrics.rb
+- lib/fintop/printer.rb
+- lib/fintop/probe.rb
+- lib/fintop/threads.rb
+- lib/fintop/version.rb
+- test/test_helper.rb
+- test/test_metrics.rb
+has_rdoc: true
+homepage: 
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A top-like utility for monitoring Finagle servers
+test_files: 
+- test/test_helper.rb
+- test/test_metrics.rb