emrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 67a0d802b62cf9845b629d83b043030c9140e9c8d931c7937aaa03ad3dec1f27
+  data.tar.gz: 425652e89206e2e1b5ad1e714b49ce7928302cb87616d1def2c8bc6b642a1c80
+SHA512:
+  metadata.gz: 42efa7169bf01425067f988fb20c0c54c9a1c87a149dca417b3f14f2d0fc4b6a7d5bed286ee16b51ac0745009f5cfbc9712d0c441a2b56ea09924279af0325ff
+  data.tar.gz: 6fc41dfa38ab82be8d310d7fd04ac4c8530f2a3c3c8a7ad9d3766795df7b1ac0f13ef272b6a2e452a4eba8773094405a6a834308d06f9a21fa47bb4626df54c7

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,31 @@
+AllCops:
+  SuggestExtensions: false
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - example/**/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/**.rb
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/README.md

@@ -0,0 +1,188 @@
+# Easy Metrics (rb)
+This project provides a facility for instrumenting applications with [Prometheus](https://github.com/prometheus/client_ruby) metrics.
+
+
+## Usage
+### [Examples TL;DR](./example)
+
+Add the gem to your project:
+```
+  bundle add emrb
+```
+
+
+### Basic usage
+
+```ruby
+require "emrb"
+
+class Metrics
+  # Emrb::Instruments provides all necessary methods for creating instruments.
+  include Emrb::Instruments  
+  # Instruments can be defined as the following:
+  counter :my_counter
+end
+
+# Perform measurements.
+Metrics.my_counter.inc
+```
+
+## Features
+### Supported metrics
+
+All [Prometheus metrics](https://github.com/prometheus/client_ruby?tab=readme-ov-file#metrics) 
+are supported and can be created the same way as in the example above.
+
+### Providing metric-specific configs
+
+Most of the provided methods are nothing but a shorthand for creating instruments (with some facilities): 
+```ruby
+require "emrb"
+
+class Metrics
+  include Emrb::Instruments
+  #                                          /-> All other options for each metric
+  #                                          |   follow the original client's syntax.
+  counter :my_counter, "this is my counter", labels: [:my_label]
+  #   _________________/
+  #   \_> This is the "docstring" value used for creating 
+  #       metrics using the Prometheus client. 
+  #       This is the only API-breaking option
+  #       for enhancing usability. Defaults to "..." when absent. 
+end
+```
+
+When your metric requires multiple options, a single line may become unwieldy. In such cases, you can use a block to define the metric config:
+
+```ruby
+require "emrb"
+
+class Metrics
+  include Emrb::Instruments
+  
+  # The block should return a hash containing all the desired options.
+  # When a block is used, other options passed inline are ignored.
+  histogram :my_histogram do
+    {
+      labels: [:label1, :label2],
+      preset_labels: { label1: "bar" },  
+      buckets: [0.9, 1.0, ...]
+    }
+  end
+end
+```
+
+### Presets
+If more than one of your metrics leverages the same `preset_labels`, the following is possible:
+
+```ruby
+require "emrb"
+
+class Metrics
+  include Emrb::Instruments
+  
+  # Apply preset labels to multiple metrics within a block.
+  with_presets label_a: "value_a", label_b: "value_b" do
+    counter :counter_a
+    counter :counter_b, labels: [:label_c]
+    #                    \_> You can continue configuring 
+    #                        each metric as usual.
+    #                        The preset labels will be merged
+    #                        with the specific ones.
+  end
+end
+# Metrics.counter_a.labels => [:label_a, :label_b]
+# Metrics.counter_b.labels => [:label_a, :label_b, :label_c]
+```
+
+### Subsystems
+
+You can organize your metrics into subsystems, allowing different components of your application to group related metrics:
+
+```ruby
+require "emrb"
+
+class Metrics
+  include Emrb::Instruments
+  subsystem :http do
+    histogram :request_duration, "duration of requests" do
+      { labels: [:method, :path] }
+    end
+  end
+  
+  subsystem :postgres do
+    #                    / -> Subsystems also accepts presets.
+    #                   |
+    subsystem :replica, op: "read" do
+      counter :op_count
+    end
+    
+    subsystem :master do
+      counter :op_count, labels: [:op]
+    end
+  end
+end
+```
+
+Metrics within a subsystem are scoped by the subsystem's name. To access metrics within a subsystem:
+
+```ruby
+Metrics.postgres.master.op_count
+```
+
+### Subsystem's metrics name
+
+Metrics created within subsystems are prefixed with the subsystem's name. For example:
+* The `request_duration` metric within the `http` subsystem  will be named `http_request_duration`
+* The `op_count` metric of `postgres.master` will be named `postgres_master_op_count`.
+
+## Exposing metrics
+
+Both [`Prometheus::Middleware::Exporter`](https://github.com/prometheus/client_ruby/blob/main/lib/prometheus/middleware/exporter.rb) 
+and [`Prometheus::Middleware::Collector`](https://github.com/prometheus/client_ruby/blob/main/lib/prometheus/middleware/collector.rb) 
+are [Rack middlewares](https://github.com/rack/rack) included in this gem as `Emrb::Exporter` and `Emrb::Collector`.
+<br>
+
+If you're unfamiliar with how to use these middlewares, the [http example](./example/http/main.rb) provides a demonstration.
+
+## Pushing metrics
+
+```ruby
+require "emrb"
+
+class Metrics
+  include Emrb::Instruments  
+  counter :my_counter
+end
+
+# Perform measurements.
+Metrics.my_counter.inc
+
+# Push the current registry state to your gateway.
+Metrics.push("example", gateway: "http://localhost:9091")
+```
+
+## License
+```
+The MIT License (MIT)
+
+Copyright (c) 2024 Felipe Mariotti, Vito Sartori
+
+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/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/example/http/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "emrb", path: "../../"
+
+gem "sinatra", "~> 4.0"
+
+gem "rackup", "~> 2.1"

data/example/http/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: ../..
+  specs:
+    emrb (0.1.0)
+      prometheus-client (~> 4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.2.0)
+    mustermann (3.0.3)
+      ruby2_keywords (~> 0.0.1)
+    prometheus-client (4.2.3)
+      base64
+    rack (3.1.7)
+    rack-protection (4.0.0)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0, < 4)
+    rack-session (2.0.0)
+      rack (>= 3.0.0)
+    rackup (2.1.0)
+      rack (>= 3)
+      webrick (~> 1.8)
+    ruby2_keywords (0.0.5)
+    sinatra (4.0.0)
+      mustermann (~> 3.0)
+      rack (>= 3.0.0, < 4)
+      rack-protection (= 4.0.0)
+      rack-session (>= 2.0.0, < 3)
+      tilt (~> 2.0)
+    tilt (2.4.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  emrb!
+  rackup (~> 2.1)
+  sinatra (~> 4.0)
+
+BUNDLED WITH
+   2.5.18

data/example/http/main.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "emrb"
+require "sinatra/base"
+
+class App < Sinatra::Base
+  class Metrics
+    include Emrb::Instruments
+    histogram :request_duration, "Request duration" do 
+       { labels: [:path, :method], buckets: [0.1, 0.2] }
+    end
+  end
+  
+  # Metrics will be exposed at /metrics
+  use Emrb::Exporter
+  
+  def measure_request_duration
+    labels = { path: request.path, method: request.env["REQUEST_METHOD"].downcase }
+    now = Time.now
+    yield
+    
+  ensure
+    Metrics.request_duration.observe(Time.now - now, labels:)
+  end
+  
+  get "/" do
+    measure_request_duration { [200, "OK" ] }
+  end
+end
+
+App.run!

data/example/push/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "emrb", path: "../../"

data/example/push/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: ../..
+  specs:
+    emrb (0.1.0)
+      prometheus-client (~> 4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.2.0)
+    prometheus-client (4.2.3)
+      base64
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  emrb!
+
+BUNDLED WITH
+   2.5.18

data/example/push/compose.yaml

@@ -0,0 +1,15 @@
+services: 
+  prom-pushgateway:
+    image: prom/pushgateway
+    ports: 
+      - 9091:9091
+  prometheus:
+    image: prom/prometheus
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+    ports:
+      - 9090:9090
+    network_mode: host

data/example/push/main.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "emrb"
+
+class Job
+  class Metrics
+    include Emrb::Instruments
+    counter :done_stuff, "how much stuff was done"
+  end
+  
+  def do_stuff
+    # Do stuff
+    Metrics.done_stuff.inc
+    Metrics.push("example", gateway: "http://localhost:9091")
+  end
+end
+
+j = Job.new
+
+t = Thread.new do
+  10.times do
+    j.do_stuff
+    sleep 1
+  end
+end
+
+t.join

data/example/push/prometheus.yml

@@ -0,0 +1,10 @@
+global:
+  scrape_interval: 3s
+scrape_configs:
+- job_name: dev-push-gateway
+  metrics_path: /metrics
+  scheme: http
+  static_configs:
+  - targets: ['localhost:9091']
+    labels:
+      service: 'prom-pushgateway'

data/lib/emrb/ext/prometheus.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Prometheus
+  module Client
+    # Internal: Extension of Prometheus::Client::Counter
+    # that can be used for implementing facilities.
+    class Counter
+      alias inc increment
+    end
+
+    # Internal: Extension of Prometheus::Client::Gauge
+    # that can be used for implementing facilities.
+    class Gauge
+      alias inc increment
+      alias dec decrement
+    end
+
+    # Internal: Extension of Prometheus::Client::Histogram
+    # that can be used for implementing facilities.
+    class Histogram
+      alias obs observe
+    end
+
+    # Internal: Extension of Prometheus::Client::Summary
+    # that can be used for implementing facilities.
+    class Summary
+      alias obs observe
+    end
+  end
+end

data/lib/emrb/instruments/exporters.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Emrb
+  # Rack middleware that provides a sample implementation of a
+  # Prometheus HTTP exposition endpoint.
+  #
+  # By default it will export the state of the global registry and expose it
+  # under `/metrics`. Use the `:registry` and `:path` options to change the
+  # defaults.
+  # Original source: https://github.com/prometheus/client_ruby/blob/main/lib/prometheus/middleware/exporter.rb
+  Exporter = Prometheus::Middleware::Exporter
+
+  # Rack middleware that provides a sample implementation of a
+  # HTTP tracer.
+  #
+  # By default metrics are registered on the global registry. Set the
+  # `:registry` option to use a custom registry.
+  #
+  # By default metrics all have the prefix "http_server". Set
+  # `:metrics_prefix` to something else if you like.
+  #
+  # The request counter metric is broken down by code, method and path.
+  # The request duration metric is broken down by method and path.
+  # Original source: https://github.com/prometheus/client_ruby/blob/main/lib/prometheus/middleware/collector.rb
+  Collector = Prometheus::Middleware::Collector
+end

data/lib/emrb/instruments/instruments.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module Emrb
+  # Instruments provide the class methods to create metrics.
+  module Instruments
+    def self.included(base) = base.extend(ClassMethods)
+
+    # CollidingNameError indicates that a declared instrument will clash with a library method. Use another name.
+    class CollidingNameError < StandardError
+      def initialize(name) = super("Identifying an instrument with #{name} will override the class method")
+    end
+
+    # Provides the instrumentation facilities when including/extending Instruments.
+    module ClassMethods
+      FORBIDDEN_IDENTIFIERS = instance_methods
+
+      # Initializes a new Prometheus counter using the provided identifier, documentation,
+      # and either optional keyword arguments or a block that returns the keyword arguments.
+      # The block takes precedence when supplied.
+      #
+      # identifier - The counter identifier.
+      # docs       - The instrument docstring. Defaults to "..."
+      #
+      # Usage example:
+      #
+      # class MyApp
+      #   class Metrics
+      #     include Emrb::Instruments
+      #     counter :visits, "Number of visits the app has received"
+      #   end
+      #
+      #   def handle_visits
+      #     Metrics.visits.inc
+      #     ...
+      #   end
+      # end
+      #
+      # For a complete list of options and functionalities for creating and utilizing a Counter,
+      # refer to the Prometheus client documentation:
+      # https://github.com/prometheus/client_ruby?tab=readme-ov-file#counter
+      def counter(identifier, docs = "...", **, &)
+        check_identifier!(identifier)
+        opts = block_opts(**, &)
+        State.counter(id_for(identifier), docs, **opts).tap do |c|
+          define_singleton_method(identifier) { c }
+        end
+      end
+
+      # Initializes a new Prometheus gauge using the provided identifier, documentation,
+      # and either optional keyword arguments or a block that returns the keyword arguments.
+      # The block takes precedence when supplied.
+      #
+      # identifier - The counter identifier.
+      # docs       - The instrument docstring. Defaults to "..."
+      #
+      # Usage example:
+      #
+      # class Thermometer
+      #   class Metrics
+      #     include Emrb::Instruments
+      #     gauge :current_temperature, "current temperature"
+      #   end
+      #
+      #   def set_current_temp
+      #     temp = < ... >
+      #     Metrics.current_temperature.set(temp)
+      #   end
+      # end
+      #
+      # For a full list of options and functionalities for creating and utilizing a Gauge,
+      # refer to the Prometheus client documentation:
+      # https://github.com/prometheus/client_ruby?tab=readme-ov-file#gauge
+      def gauge(identifier, docs, **, &)
+        check_identifier!(identifier)
+        opts = block_opts(**, &)
+        State.gauge(id_for(identifier), docs, **opts).tap do |g|
+          define_singleton_method(identifier) { g }
+        end
+      end
+
+      # Initializes a new Prometheus histogram using the provided identifier, documentation,
+      # and either optional keyword arguments or a block that returns the keyword arguments.
+      # The block takes precedence when supplied.
+      #
+      # identifier - The counter identifier.
+      # docs       - The instrument docstring. Defaults to "..."
+      #
+      # Usage example:
+      #
+      # class MyApp
+      #   class Metrics
+      #     include Emrb::Instruments
+      #     histogram :request_duration, "Duration of requests" do
+      #       { labels: [:path, :method], buckets: [0.1, 0.2] }
+      #      end
+      #   end
+      #
+      #   def measure_request_duration
+      #     labels = { path: request.path, method: request.env["REQUEST_METHOD"].downcase }      #
+      #     Metrics.request_duration.observe(Benchmark.realtime { yield }, labels: )
+      #   end
+      #
+      #   get "/" do
+      #     measure_request_duration { [200, "OK"] }
+      #   end
+      # end
+      #
+      # For all available options and functionalities for creating and utilizing a Histogram,
+      # refer to the Prometheus client documentation:
+      # https://github.com/prometheus/client_ruby?tab=readme-ov-file#histogram
+      def histogram(identifier, docs, **, &)
+        check_identifier!(identifier)
+        opts = block_opts(**, &)
+        State.histogram(id_for(identifier), docs, **opts).tap do |h|
+          define_singleton_method(identifier) { h }
+        end
+      end
+
+      # Initializes a new Prometheus summary using the provided identifier, documentation,
+      # and either optional keyword arguments or a block that returns the keyword arguments.
+      # The block takes precedence when supplied.
+      #
+      # identifier - The counter identifier.
+      # docs       - The instrument docstring. Defaults to "..."
+      #
+      # Usage example:
+      #
+      # class MyApp
+      #   class Metrics
+      #     include Emrb::Instruments
+      #     summary :call_duration, "Duration of a given call"
+      #   end
+
+      #   def do_a_call
+      #     Metrics.call_duration.observe(Benchmark.realtime { < ... > })
+      #   end
+      # end
+      #
+      # For a complete list of options and functionalities for creating and utilizing a Summary,
+      # refer to the Prometheus client documentation:
+      # https://github.com/prometheus/client_ruby?tab=readme-ov-file#summary
+      def summary(identifier, docs, **, &)
+        check_identifier!(identifier)
+        opts = block_opts(**, &)
+        State.summary(id_for(identifier), docs, **opts).tap do |s|
+          define_singleton_method(identifier) { s }
+        end
+      end
+
+      # push the current registry state to a Pushgateway.
+      # It receives an obligatory job identifier, and optionally all supported
+      # keyword arguments of a Prometheus::Client::Push.
+      #
+      # job - Job identifier
+      #
+      # Usage example:
+      #
+      # class MyJob
+      #   class Metrics
+      #     include Emrb::Instruments
+      #     counter :processed_tasks
+      #   end
+      #
+      #   def do_the_things
+      #     begin
+      #       tasks.each do |t|
+      #         < ... >
+      #         Metrics.processed_tasks.inc
+      #       end
+      #     rescue
+      #         < ... >
+      #     ensure
+      #       Metrics.push("job_name")
+      #     end
+      #   end
+      # end
+      def push(job, **) = State.push(job, **)
+
+      # Allows instruments to be declared with preset labels.
+      #
+      # labels - A hash containing the preset labels and values
+      #
+      # Usage example:
+      #
+      # class Metrics
+      #   include Emrb::Instruments
+      #   with_presets my: "label", other: "label" do
+      #     counter :my_counter, "a counter"
+      #   end
+      # end
+      #
+      # Metrics.my_counter.labels => [:my, :other]
+      # Metrics.my_counter.preset_labels => { my: "label", other: "label" }
+      def with_presets(**labels, &)
+        raise LocalJumpError, "no block given" unless block_given?
+        raise ArgumentError, "labels are empty" if labels.nil? || labels.empty?
+
+        old = (@presets ||= {})
+        current = old.merge labels
+        @presets = current
+        instance_eval(&)
+        @presets = old
+      end
+
+      # Provides a way to compose metrics for different subsystems.
+      # All instruments created within a subsystem will have their identifiers
+      # prefixed with the prefix param.
+      #
+      # prefix          - determines the prefix of all instruments declared
+      #                   within the subsystem and how to access those instruments
+      #                   within the implementation.
+      #
+      # inherit_presets - determines whether or not to inherit presets from
+      #                   the parent. Defaults to false.
+      #
+      # presets         - preset of labels to be used by all Instruments
+      #                   of a given subsystem.
+      #
+      # Usage example:
+      #
+      # class Metrics
+      #   subsystem :http do
+      #     histogram :request_duration, "duration of requests" do
+      #       { labels: [:method, :path] }
+      #     end
+      #   end
+      #
+      #   subsystem :postgres do
+      #     subsystem :master, op: "write" do
+      #       counter :op_count
+      #     end
+      #
+      #     subsystem :replica, op: "read" do
+      #       counter :op_count
+      #     end
+      #   end
+      # end
+      #
+      # # Acessing instruments:
+      # Metrics.http.request_duration
+      # Metrics.postgres.master.op_count
+      # Metrics.postgres.replica.op_count
+      # rubocop:disable Metrics/MethodLength
+      def subsystem(prefix, inherit_presets: false, **presets, &)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        s_prefix = prefix.to_s
+        s_prefix.delete_suffix! "_" if s_prefix.end_with? "_"
+        subsystem = id_for(s_prefix.to_sym)
+
+        presets.merge! @presets if inherit_presets && !@presets.nil?
+
+        s = Class.new
+        s.include(Instruments)
+        s.instance_variable_set(:@subsystem, subsystem)
+        s.instance_variable_set(:@presets, presets)
+        s.instance_eval(&)
+        define_singleton_method(prefix) { s }
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Internal: validates whether to concatenate the given identifier with
+      # a pre-existing susbsystem name.
+      def id_for(identifier)
+        return identifier unless @subsystem
+
+        :"#{@subsystem}_#{identifier}"
+      end
+
+      # Internal: Validates the provided options to create a given instrument
+      # and performs the merge of all options with presets when they are present.
+      def block_opts(**opts, &)
+        res = block_given? ? yield : opts
+        return res if @presets.nil?
+
+        res[:labels] = [] if res[:labels].nil?
+        res[:labels].append(*@presets.keys)
+
+        if res[:preset_labels].nil?
+          res[:preset_labels] = @presets
+          return res
+        end
+
+        res[:preset_labels].merge!(**@presets)
+        res
+      end
+
+      # Internal: Validates whether the given identifier might override one of the class methods.
+      # In a positive case, raises CollidingNameError.
+      def check_identifier!(id)
+        raise Instruments::CollidingNameError, id if FORBIDDEN_IDENTIFIERS.include? id
+      end
+    end
+  end
+end

data/lib/emrb/instruments/state.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Emrb
+  module Instruments
+    # Internal: State is responsible for interacting with the Prometheus client.
+    class State
+      # Internal: All supported Prometheus metrics.
+      INSTRUMENTS = {
+        c: Prometheus::Client::Counter,
+        g: Prometheus::Client::Gauge,
+        h: Prometheus::Client::Histogram,
+        s: Prometheus::Client::Summary
+      }.freeze
+
+      class << self
+        # Internal: creates, registers, and returns a new Prometheus::Client::Counter.
+        # Requires an instrument identifier and a docstring as mandatory arguments,
+        # with optional keyword arguments supported by the Prometheus Counter.
+        # Prom docs: https://github.com/prometheus/client_ruby?tab=readme-ov-file#counter
+        def counter(identifier, docstring, **)
+          INSTRUMENTS[:c].new(identifier, docstring:, **).tap { reg.register _1 }
+        end
+
+        # Internal: creates, registers, and returns a new Prometheus::Client::Gauge.
+        # Requires an instrument identifier and a docstring as mandatory arguments,
+        # with optional keyword arguments supported by the Prometheus Gauge.
+        # Prom docs: https://github.com/prometheus/client_ruby?tab=readme-ov-file#gauge
+        def gauge(identifier, docstring, **)
+          INSTRUMENTS[:g].new(identifier, docstring:, **).tap { reg.register _1 }
+        end
+
+        # Internal: creates, registers, and returns a new Prometheus::Client::Histogram.
+        # Requires an instrument identifier and a docstring as mandatory arguments,
+        # with optional keyword arguments supported by the Prometheus Histogram.
+        # Prom docs: https://github.com/prometheus/client_ruby?tab=readme-ov-file#histogram
+        def histogram(identifier, docstring, **)
+          INSTRUMENTS[:h].new(identifier, docstring:, **).tap { reg.register _1 }
+        end
+
+        # Internal: creates, registers, and returns a new Prometheus::Client::Summary.
+        # Requires an instrument identifier and a docstring as mandatory arguments,
+        # with optional keyword arguments supported by the Prometheus Summary.
+        # Prom docs: https://github.com/prometheus/client_ruby?tab=readme-ov-file#summary
+        def summary(identifier, docstring, **)
+          INSTRUMENTS[:s].new(identifier, docstring:, **).tap { reg.register _1 }
+        end
+
+        # Internal: pushes the current registry state to a Pushgateway.
+        # It receives an obligatory job identifier, and optionally all supported
+        # keyword arguments of a new push.
+        # Prom docs: https://github.com/prometheus/client_ruby?tab=readme-ov-file#pushgateway
+        def push(job, **) = Prometheus::Client::Push.new(job:, **).add(reg)
+
+        # Internal: returns the current client registry.
+        def reg = Prometheus::Client.registry
+      end
+    end
+  end
+end

data/lib/emrb/instruments.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "instruments/state"
+require_relative "instruments/instruments"
+require_relative "instruments/exporters"

data/lib/emrb/version.rb

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

data/lib/emrb.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "prometheus"
+require "prometheus/client/push"
+require "prometheus/middleware/collector"
+require "prometheus/middleware/exporter"
+require_relative "emrb/ext/prometheus"
+
+require_relative "emrb/version"
+require_relative "emrb/instruments"
+
+# Emrb provides a facility for instrumenting applications with prometheus metrics.
+# All instruments can be used the same way as in prometheus-client, and are
+# registered within the same registry.
+# Both Prometheus::Middleware::Collector and Prometheus::Middleware::Exporter
+# can be accessed using Emrb::Collector and Emrb::Exporter.
+module Emrb
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: emrb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Felipe Mariotti
+- Vito Sartori
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prometheus-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: Easy prometheus instrumentation for Ruby applications
+email:
+- felipe.mtt95@gmail.com
+- hey@vito.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- README.md
+- Rakefile
+- example/http/Gemfile
+- example/http/Gemfile.lock
+- example/http/main.rb
+- example/push/Gemfile
+- example/push/Gemfile.lock
+- example/push/compose.yaml
+- example/push/main.rb
+- example/push/prometheus.yml
+- lib/emrb.rb
+- lib/emrb/ext/prometheus.rb
+- lib/emrb/instruments.rb
+- lib/emrb/instruments/exporters.rb
+- lib/emrb/instruments/instruments.rb
+- lib/emrb/instruments/state.rb
+- lib/emrb/version.rb
+homepage: https://github.com/ofeefo/emrb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ofeefo/emrb
+  source_code_uri: https://github.com/ofeefo/emrb
+  changelog_uri: https://github.com/ofeefo/emrb
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.18
+signing_key:
+specification_version: 4
+summary: Easy prometheus instrumentation for Ruby applications
+test_files: []