promproto 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 871334ffa068b6468e54037c4f9ec27afb7d0d58f876250664a5448a33024317
+  data.tar.gz: e09172bef789aaf9e87badebfde3b5e0ec807d137642c9029f01fd47a2c19087
+SHA512:
+  metadata.gz: 64ec3528751a00e64f98540acd3847d750bd3566abe8b084ee6b9e9378e77e75d07639419202ca0feba596ee21da1cd8ac8689daddfb9a190c229f3fba4d94fc
+  data.tar.gz: 589923e4bafcac52eea6536a1d17fd510701195cb6df5e1b78326d787851265610dd64249191eceee14d222be5ecbb38bd569d8cdc028894c798172c484443a4

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Lewis Buckley
+
+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,50 @@
+# Promproto
+
+A command-line tool to fetch and display Prometheus metrics in protobuf format.
+
+## Installation
+
+```bash
+gem install promproto
+```
+
+## Usage
+
+```bash
+# Fetch metrics from a target
+promproto localhost:9394
+
+# Watch mode - continuously refresh
+promproto -w localhost:9394
+
+# Custom refresh interval (in seconds)
+promproto -w -n 5 localhost:9394
+
+# Full URL
+promproto http://localhost:9394/metrics
+```
+
+## Features
+
+- Fetches metrics using the Prometheus protobuf exposition format
+- Color-coded output for easy reading
+- Supports both classic and native histograms
+- Watch mode for continuous monitoring
+- Automatic URL normalization (adds http:// and /metrics if missing)
+
+## Native Histograms
+
+When the server exports native histograms, promproto displays:
+- Schema and zero threshold
+- Zero bucket count
+- Positive and negative bucket spans with computed bounds
+- Visual bar charts for bucket counts
+
+## Requirements
+
+- Ruby 3.1+
+- google-protobuf gem
+
+## License
+
+MIT

data/exe/promproto

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/promproto"
+
+options = { watch: false, interval: Promproto::CLI::DEFAULT_WATCH_INTERVAL }
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: promproto [options] <target>"
+  opts.separator ""
+  opts.separator "Fetches Prometheus metrics in protobuf format and renders them."
+  opts.separator ""
+  opts.separator "Target can be:"
+  opts.separator "  - Full URL: http://localhost:9090/metrics"
+  opts.separator "  - Host:port: localhost:9090 (assumes http:// and /metrics)"
+  opts.separator "  - Host only: localhost (assumes http://, port 80, and /metrics)"
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-w", "--watch", "Continuously fetch and display metrics") do
+    options[:watch] = true
+  end
+
+  opts.on("-n", "--interval SECONDS", Integer, "Refresh interval in seconds (default: #{Promproto::CLI::DEFAULT_WATCH_INTERVAL})") do |n|
+    options[:interval] = n
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "promproto #{Promproto::VERSION}"
+    exit
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption => e
+  abort "#{e.message}\nUse --help for usage information."
+end
+
+if ARGV.empty?
+  puts parser
+  exit 1
+end
+
+url = Promproto.normalize_url(ARGV[0])
+Promproto::CLI.new(url, watch: options[:watch], interval: options[:interval]).run

data/lib/promproto/cli.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Promproto
+  class CLI
+    ACCEPT_HEADER = "application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited"
+    DEFAULT_WATCH_INTERVAL = 2
+
+    def initialize(url, watch: false, interval: DEFAULT_WATCH_INTERVAL)
+      @url = url
+      @watch = watch
+      @interval = interval
+    end
+
+    def run
+      if @watch
+        run_watch
+      else
+        run_once
+      end
+    end
+
+    private
+
+    def run_once
+      data = fetch_metrics
+      families = parse_delimited(data)
+      render(families)
+    rescue Errno::ECONNREFUSED => e
+      abort "Error: Connection refused to #{@url}\n\nMake sure the metrics server is running and accessible."
+    rescue Errno::ETIMEDOUT, Net::OpenTimeout
+      abort "Error: Connection timed out to #{@url}\n\nThe server may be unreachable or behind a firewall."
+    rescue SocketError => e
+      abort "Error: Could not resolve host for #{@url}\n\n#{e.message}"
+    rescue Net::ReadTimeout
+      abort "Error: Read timeout waiting for response from #{@url}"
+    rescue StandardError => e
+      abort "Error: #{e.message}"
+    end
+
+    def run_watch
+      loop do
+        print "\e[2J\e[H" # Clear screen and move cursor to top
+        puts "\e[90m#{Time.now.strftime("%Y-%m-%d %H:%M:%S")} - #{@url}\e[0m"
+        puts
+
+        begin
+          data = fetch_metrics
+          families = parse_delimited(data)
+          render(families)
+        rescue Errno::ECONNREFUSED
+          puts "\e[31mError: Connection refused\e[0m"
+          puts "\e[90mMake sure the metrics server is running and accessible.\e[0m"
+        rescue Errno::ETIMEDOUT, Net::OpenTimeout
+          puts "\e[31mError: Connection timed out\e[0m"
+        rescue SocketError => e
+          puts "\e[31mError: #{e.message}\e[0m"
+        rescue StandardError => e
+          puts "\e[31mError: #{e.message}\e[0m"
+        end
+
+        sleep @interval
+      end
+    rescue Interrupt
+      puts "\nStopped."
+    end
+
+    def fetch_metrics
+      uri = URI.parse(@url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      request["Accept"] = ACCEPT_HEADER
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise "HTTP #{response.code} #{response.message}"
+      end
+
+      content_type = response["Content-Type"] || ""
+      unless content_type.include?("application/vnd.google.protobuf")
+        warn "Warning: Server returned Content-Type: #{content_type}"
+        warn "Expected: #{ACCEPT_HEADER}"
+        warn ""
+      end
+
+      response.body
+    end
+
+    def parse_delimited(data)
+      families = []
+      pos = 0
+
+      while pos < data.bytesize
+        # Read varint length
+        len, bytes_read = read_varint(data, pos)
+        break if len.zero? || bytes_read.zero?
+
+        pos += bytes_read
+
+        break if pos + len > data.bytesize
+
+        msg_data = data[pos, len]
+        begin
+          family = Io::Prometheus::Client::MetricFamily.decode(msg_data)
+          families << family
+        rescue Google::Protobuf::ParseError => e
+          warn "Warning: Failed to decode message at offset #{pos}: #{e.message}"
+        end
+
+        pos += len
+      end
+
+      families
+    end
+
+    def read_varint(data, pos)
+      value = 0
+      shift = 0
+      bytes_read = 0
+
+      loop do
+        return [0, 0] if pos >= data.bytesize
+
+        byte = data.getbyte(pos)
+        pos += 1
+        bytes_read += 1
+
+        value |= (byte & 0x7F) << shift
+
+        break if (byte & 0x80).zero?
+
+        shift += 7
+        return [0, 0] if shift > 63 # Overflow protection
+      end
+
+      [value, bytes_read]
+    end
+
+    def render(families)
+      families.each do |family|
+        render_family(family)
+      end
+    end
+
+    def render_family(family)
+      puts "\e[1;36m#{family.name}\e[0m \e[33m(#{type_name(family.type)})\e[0m"
+      puts "  \e[90m#{family.help}\e[0m" unless family.help.empty?
+
+      family.metric.each do |metric|
+        render_metric(metric, family.type)
+      end
+      puts
+    end
+
+    def type_name(type)
+      case type
+      when :COUNTER then "counter"
+      when :GAUGE then "gauge"
+      when :SUMMARY then "summary"
+      when :HISTOGRAM then "histogram"
+      when :GAUGE_HISTOGRAM then "gauge_histogram"
+      when :UNTYPED then "untyped"
+      else type.to_s.downcase
+      end
+    end
+
+    def render_metric(metric, type)
+      labels = format_labels(metric.label)
+
+      case type
+      when :COUNTER
+        puts "  #{labels} \e[32m#{metric.counter.value}\e[0m"
+      when :GAUGE
+        puts "  #{labels} \e[32m#{metric.gauge.value}\e[0m"
+      when :SUMMARY
+        render_summary(metric, labels)
+      when :HISTOGRAM
+        render_histogram(metric, labels)
+      when :UNTYPED
+        puts "  #{labels} \e[32m#{metric.untyped.value}\e[0m"
+      end
+    end
+
+    def format_labels(labels)
+      return "" if labels.empty?
+
+      pairs = labels.map { |l| "\e[35m#{l.name}\e[0m=\"\e[34m#{l.value}\e[0m\"" }
+      "{#{pairs.join(", ")}}"
+    end
+
+    def render_summary(metric, labels)
+      summary = metric.summary
+      puts "  #{labels}"
+      puts "    count: \e[32m#{summary.sample_count}\e[0m  sum: \e[32m#{summary.sample_sum}\e[0m"
+      summary.quantile.each do |q|
+        puts "    p#{(q.quantile * 100).to_i}: \e[32m#{q.value}\e[0m"
+      end
+    end
+
+    def render_histogram(metric, labels)
+      histogram = metric.histogram
+      puts "  #{labels}"
+      puts "    count: \e[32m#{histogram.sample_count}\e[0m  sum: \e[32m#{format_number(histogram.sample_sum)}\e[0m"
+
+      # Check if this is a native histogram (has schema) or classic
+      if histogram.schema != 0 || histogram.positive_span.any? || histogram.negative_span.any?
+        render_native_histogram(histogram)
+      elsif histogram.bucket.any?
+        render_classic_histogram(histogram)
+      end
+    end
+
+    def render_native_histogram(histogram)
+      puts "    \e[90mschema: #{histogram.schema}  zero_threshold: #{histogram.zero_threshold}\e[0m"
+
+      if histogram.zero_count > 0
+        puts "    zero: \e[32m#{histogram.zero_count}\e[0m"
+      end
+
+      if histogram.negative_span.any?
+        puts "    \e[90mnegative buckets:\e[0m"
+        render_spans(histogram.negative_span, histogram.negative_delta, histogram.schema, negative: true)
+      end
+
+      if histogram.positive_span.any?
+        puts "    \e[90mpositive buckets:\e[0m"
+        render_spans(histogram.positive_span, histogram.positive_delta, histogram.schema, negative: false)
+      end
+    end
+
+    def render_spans(spans, deltas, schema, negative:)
+      bucket_idx = 0
+      count = 0
+      delta_idx = 0
+
+      spans.each do |span|
+        bucket_idx += span.offset
+
+        span.length.times do
+          break if delta_idx >= deltas.size
+
+          count += deltas[delta_idx]
+          delta_idx += 1
+
+          lower, upper = bucket_bounds(bucket_idx, schema)
+          if negative
+            lower, upper = -upper, -lower
+          end
+
+          bar = bar_chart(count, 20)
+          puts "      [#{format_bound(lower)}, #{format_bound(upper)}): #{bar} \e[32m#{count}\e[0m"
+
+          bucket_idx += 1
+        end
+      end
+    end
+
+    def bucket_bounds(index, schema)
+      base = 2.0 ** (2.0 ** -schema)
+      lower = base ** index
+      upper = base ** (index + 1)
+      [lower, upper]
+    end
+
+    def render_classic_histogram(histogram)
+      puts "    \e[90mclassic buckets:\e[0m"
+      histogram.bucket.each do |bucket|
+        bar = bar_chart(bucket.cumulative_count, 20)
+        puts "      le=#{format_bound(bucket.upper_bound)}: #{bar} \e[32m#{bucket.cumulative_count}\e[0m"
+      end
+    end
+
+    def bar_chart(value, max_width)
+      return "" if value <= 0
+
+      width = [Math.log10(value + 1) * max_width / 5, max_width].min.to_i
+      "\e[44m#{" " * width}\e[0m"
+    end
+
+    def format_bound(value)
+      if value.infinite?
+        value.positive? ? "+Inf" : "-Inf"
+      elsif value.abs >= 1000 || (value.abs < 0.001 && value != 0)
+        format("%.3e", value)
+      else
+        format("%.4g", value)
+      end
+    end
+
+    def format_number(value)
+      if value.abs >= 1000 || (value.abs < 0.001 && value != 0)
+        format("%.3e", value)
+      else
+        format("%.4g", value)
+      end
+    end
+  end
+end

data/lib/promproto/metrics_pb.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Prometheus client model protobuf definitions
+# Loaded from compiled FileDescriptorSet
+
+require "google/protobuf"
+require "google/protobuf/descriptor_pb"
+
+module Io
+  module Prometheus
+    module Client
+      # Load the compiled FileDescriptorSet
+      DESCRIPTOR_DATA = File.binread(
+        File.expand_path("metrics.pb", __dir__)
+      ).freeze
+
+      # Parse the FileDescriptorSet
+      FILE_DESCRIPTOR_SET = Google::Protobuf::FileDescriptorSet.decode(DESCRIPTOR_DATA)
+
+      # Add each file descriptor to a pool
+      DESCRIPTOR_POOL = Google::Protobuf::DescriptorPool.new
+      FILE_DESCRIPTOR_SET.file.each do |file_proto|
+        DESCRIPTOR_POOL.add_serialized_file(file_proto.to_proto)
+      end
+
+      LabelPair = DESCRIPTOR_POOL.lookup("io.prometheus.client.LabelPair").msgclass
+      Gauge = DESCRIPTOR_POOL.lookup("io.prometheus.client.Gauge").msgclass
+      Counter = DESCRIPTOR_POOL.lookup("io.prometheus.client.Counter").msgclass
+      Quantile = DESCRIPTOR_POOL.lookup("io.prometheus.client.Quantile").msgclass
+      Summary = DESCRIPTOR_POOL.lookup("io.prometheus.client.Summary").msgclass
+      Untyped = DESCRIPTOR_POOL.lookup("io.prometheus.client.Untyped").msgclass
+      BucketSpan = DESCRIPTOR_POOL.lookup("io.prometheus.client.BucketSpan").msgclass
+      Bucket = DESCRIPTOR_POOL.lookup("io.prometheus.client.Bucket").msgclass
+      Histogram = DESCRIPTOR_POOL.lookup("io.prometheus.client.Histogram").msgclass
+      Metric = DESCRIPTOR_POOL.lookup("io.prometheus.client.Metric").msgclass
+      MetricFamily = DESCRIPTOR_POOL.lookup("io.prometheus.client.MetricFamily").msgclass
+      MetricType = DESCRIPTOR_POOL.lookup("io.prometheus.client.MetricType").enummodule
+    end
+  end
+end

data/lib/promproto/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Promproto
+  VERSION = "0.1.0"
+end

data/lib/promproto.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "promproto/version"
+require_relative "promproto/metrics_pb"
+require_relative "promproto/cli"
+
+module Promproto
+  def self.normalize_url(input)
+    url = input.dup
+
+    # Add http:// if no scheme
+    unless url.match?(%r{^https?://})
+      url = "http://#{url}"
+    end
+
+    # Parse to check/add path
+    uri = URI.parse(url)
+
+    # Add /metrics if path is empty or just /
+    if uri.path.nil? || uri.path.empty? || uri.path == "/"
+      uri.path = "/metrics"
+    end
+
+    uri.to_s
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: promproto
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lewis Buckley
+bindir: exe
+cert_chain: []
+date: 2025-12-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.21'
+description: A command-line tool that fetches Prometheus metrics using the protobuf
+  exposition format and renders them with color-coded output. Supports both classic
+  and native histograms.
+email:
+- lewis@basecamp.com
+executables:
+- promproto
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- exe/promproto
+- lib/promproto.rb
+- lib/promproto/cli.rb
+- lib/promproto/metrics.pb
+- lib/promproto/metrics_pb.rb
+- lib/promproto/version.rb
+homepage: https://github.com/lewispb/promproto
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lewispb/promproto
+  source_code_uri: https://github.com/lewispb/promproto
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: CLI tool to fetch and display Prometheus metrics in protobuf format
+test_files: []