maxpage 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ee92dec537b5ae2ee89664e27910d5733907481a42a96cd2bdf5e6173ac4ee1
+  data.tar.gz: b90b61f8366d572789c5c3cc875308e8e66145cd412bc2e47a4c44184f208fc2
+SHA512:
+  metadata.gz: 5f56e14e148f434df90bbb27e5cbb68cef5dbcbe9a5188ff0bd7e7b4b033bc2ef7181bf02f1b69ed67a2e3ed21d47a8775bf239514facd6f7fe7373adad3ce29
+  data.tar.gz: 527356a2d0b834136fea9b60d0d03476428792debd02c9e5231ac0eb01b974ae6cd40368529242d38fc7f7a6c034f646075ea744054c0a8d2c7cdda499b551a7

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Lucas Castro
+
+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,254 @@
+# 🐶 Max, your app's best friend!
+
+__Max Page__ sniffs metrics in your app to check if is everything right.
+
+![ "MaxPage Example (code and generated page)"](./docs/print.png?raw=true)
+
+In other words, it's a [Ruby on Rails](https://github.com/rails/rails) engine to create "status pages" for your project.
+
+__Max__ is similiar to what [GitHub](https://www.githubstatus.com/), [Heroku](https://status.heroku.com/), [Atlassian](https://status.atlassian.com/) and others do to keep their users noticed about the operational status. However, __Max__ it's much more about the apps's data than its infrastructure. If you would like something to keep a history of incidents, subscriptions, and integrations with external, try specific tools like [StatusPage](https://www.atlassian.com/software/statuspage).
+
+__Max get together your app's metrics, in a single page.__
+
+For metrics, I mean some numbers and verifications that help us to understand if the app is running fine as a whole. They are not necessarily infrastructure checks.
+
+Examples of metrics:
+
+1. Check health of internal and external services;
+2. Number of users registered last 24h;
+3. Number of clients that are using the key features;
+4. Size of internal queue processing services;
+5. Nodes we are consuming in the Kubernetes cluster.
+
+## Installation
+
+Install the `maxpage` gem in your Rails app by using `bundle`:
+
+```bash
+$ bundle add maxpage
+```
+
+After that, add the configuration file `config/initializers/maxpage.rb` to start creating your metrics, like the following code:
+
+```ruby
+MaxPage.setup do
+  metric 'Users registered last 24h' do
+    User.where("created_at > ?", 24.hours.ago).count
+  end
+end
+```
+
+Mount the route for the status page in `config/routes.rb`:
+
+```ruby
+  mount MaxPage::Engine => "/status"
+```
+
+In that case, we are going to accces the page using the `/status` path: [http://localhost:3000/status](http://localhost:3000/status).
+
+You can use __Max__ exclusively to monitor other apps and services. In that case consider to use only `/` instead `/status` to mount the `MaxPage` engine, as your Rails application would not need other routes.
+
+## Usage
+
+To set up `MaxPage` all we need is to create an initializer file to define metrics.
+
+Before do it, let's establish some concepts:
+* A `metric` is anything you want to monitor;
+* A `metric` has a `name` and a `block` of code;
+* The `block`'s result will be presented in the page;
+* The `block`'s result can be verified to produce an __warning__ or __success__ message;
+
+Let's to an example!
+
+```ruby
+MaxPage.setup do
+  metric 'Users registered last 24h' do
+    User.where("created_at > ?", 24.hours.ago).count
+  end
+end
+```
+
+In the above code we have a metric named "User registered last 24h", with a block code that count in the database the users registed last 24h, using `ActiveRecord`.
+
+__⚠️ Important:__ As our configuration is under `config/initializers` folder we __MUST__ restart the Rails server to see the changes. Soon we're going to move the setup code to the `app` directory and eliminate the need of restarting. Work in progress.
+
+### The option `verify`
+
+Let's say that usually I have 30 new users per day in my app.
+
+I would like to know when this number is less than 20, what means something wrong is happening.
+
+So, we are going to add the `verify` option to check this metric status:
+
+```ruby
+MaxPage.setup do
+  metric 'Users registered >= 20 ', verify: { min: 20 } do
+    User.where("created_at > ?", 24.hours.ago).count
+  end
+end
+```
+
+Alternatively, we could use `verify: true`:
+
+```ruby
+MaxPage.setup do
+  metric 'Users registered last 24h is more than 20', verify: true do
+    User.where("created_at > ?", 24.hours.ago).count > 20
+  end
+end
+```
+
+Observe that when we use `verify: true`, it's expected the metric returns `true`. The page shows
+a check icon (✅) if this condition is satisfied, otherwise, it shows a warning icon (⚠️).
+
+At mostly, when I am checking numbers, I prefer to use verify with `min` or `max`.
+
+### Warning and success messages
+
+On top of the page, Max print a message accordling the verifications.
+
+If all the metrics have their verify satisfied, the `success message` is printed.
+Otherwise, we see the `warning message`.
+
+Remember that the `verify` is not a required option, therefore if it is not defined we consider the metric is always __Okay__ to the overall verification.
+
+We can change these messages. In the following code I translated them to Portuguese:
+
+```ruby
+StatusPage.setup do
+  success_message 'Tudo certo!'
+  warning_message 'Ops, tem algo de errado.'
+
+  metric 'Usuários cadastrados nas últimas 24 horas', verify: { min: 20 } do
+    User.where("created_at > ?", 24.hours.ago).count
+  end
+end
+```
+
+### Groups of metrics
+
+It's possible to create group of metrics just to organize them.
+
+We can do it as the following code:
+
+```ruby
+MaxPage.setup do
+  group 'Application data' do
+    metric 'User registered last 24h' do
+      # ...
+    end
+
+    # ...
+  end
+
+  group 'Internal services status' do
+    metric 'ElasticSearch is up' do
+      # ...
+    end
+
+    metric 'Redis is up' do
+      # ...
+    end
+  end
+end
+```
+
+### Authentications and Authorizations
+
+Sometimes our page presents sensible data that could't be published to everyone.
+
+Thinking of this, we can use the `before_action` option to  define authentication and authorization rules.
+
+Example:
+
+```ruby
+MaxPage.setup do
+  before_action do
+    authenticate_user!
+  end
+
+  # ... 
+end
+```
+
+The `before_action` block will be evaluated in `before_action` callback, using the controller scope.
+This is why you can use methods like `authenticate_<resource_name>!` from [Devise](https://github.com/heartcombo/devise) and `authorize` from [Pundit](https://github.com/varvet/pundit).
+
+## Examples
+
+### Health status
+
+Here we are checking the standard library `Net::HTTP` the request a URI:
+
+```ruby
+  metric 'Health check using Net::HTTP', verify: true do
+    # Rescue errors returning false 
+    result = Net::HTTP.get(URI('https://example.com/health/check')) rescue false
+
+    # Double bang to return true because result is String if the request succeeded.
+    !!result
+  end
+```
+
+Now, some examples using [HTTParty](https://github.com/jnunemaker/httparty) to check the HTTP status.
+
+```ruby
+  require 'httparty'
+
+  metric 'Health check', verify: true do
+    HTTParty.get('https://example.com').success?
+  end
+
+  # Will warn once https://example.com/health/check will return the 404 status.
+  metric 'Health check status code', verify: 200 do
+    HTTParty.get('https://example.com/health/check').code
+  end
+```
+
+### Database records
+
+```ruby
+  metric 'PostgreSQL records count', description: "Heroku's Hobby Dev plan limits to 10,000", verify: { max: 10_000 } do
+    ActiveRecord::Base.connection.execute(%{
+      select sum(c.reltuples) as rows
+      from pg_class c
+      join pg_namespace n on n.oid = c.relnamespace
+      where c.relkind = 'r'
+      and n.nspname not in ('information_schema','pg_catalog');
+    }).first['rows']
+  end
+```
+
+### Delayed::Job
+
+```ruby
+  group "Delayed Job" do
+    metric 'Failures', verify: { max: 0 } do
+      Delayed::Job.where.not(failed_at: nil).count
+    end
+
+    metric 'Size of the queue "mailer"' do
+      Delayed::Job.where(queue: 'mailer').count
+    end
+  end
+```
+
+### Bugsnag errors
+
+```ruby
+  require 'httparty'
+
+  metric 'Open errors on Bugsnag', verify: { max: 0 } do
+    project_id = '<PROJECT-ID>'
+    auth_token = '<AUTH-TOKEN>'
+    response = HTTParty.get "https://api.bugsnag.com/projects/#{project_id}?auth_token=#{auth_token}"
+    response['open_error_count']
+  end
+```
+
+## Contributing
+
+Contributions are welcome! Feel free to open an issue and pull request on [GitHub](https://github.com/lucasmncastro/maxpage).
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/maxpage_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/maxpage .css

data/app/controllers/max_page/application_controller.rb

@@ -0,0 +1,4 @@
+module MaxPage
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/max_page/metrics_controller.rb

@@ -0,0 +1,30 @@
+module MaxPage
+  class MetricsController < ApplicationController
+    layout 'max_page/application'
+
+    before_action :before_index
+
+    def index
+      @title = MaxPage.config.title
+      @metrics = MaxPage.config.metrics
+      @metrics.each &:run
+      @alright = @metrics.map(&:ok?).all? true
+      if @alright
+        @message = MaxPage.config.success_message
+      else
+        @message = MaxPage.config.warning_message
+      end
+      @metrics_without_group = @metrics.reject(&:group)
+      @groups = MaxPage.config.groups
+    end
+
+    protected
+
+    def before_index
+      block = MaxPage.config.before_action
+      if block
+        instance_eval(&block)
+      end
+    end
+  end
+end

data/app/helpers/max_page/application_helper.rb

@@ -0,0 +1,4 @@
+module MaxPage
+  module ApplicationHelper
+  end
+end

data/app/helpers/max_page/metrics_helper.rb

@@ -0,0 +1,4 @@
+module MaxPage
+  module MetricsHelper
+  end
+end

data/app/jobs/max_page/application_job.rb

@@ -0,0 +1,4 @@
+module MaxPage
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/max_page/application_mailer.rb

@@ -0,0 +1,6 @@
+module MaxPage
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/max_page/application_record.rb

@@ -0,0 +1,5 @@
+module MaxPage
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/max_page/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= @title %></title>
+
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.8.1/font/bootstrap-icons.css">
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/max_page/metrics/_metric.html.erb

@@ -0,0 +1,23 @@
+<li class="list-group-item">
+  <div class="d-flex justify-content-between align-items-center">
+    <span class="w-100"><%= metric.name %></span>
+
+    <% if metric.verify == true %>
+      <% if metric.verify? %>
+        <% if metric.ok? %>
+          <i class="bi bi-check-circle-fill text-success"></i>
+        <% else %>
+          <i class="bi bi-exclamation-triangle-fill text-warning"></i>
+        <% end %>
+      <% end %>
+    <% else %>
+      <span class="badge text-black <%= (metric.ok? ? 'text-white bg-success' : 'text-white bg-warning') if metric.verify? %>">
+        <%= metric.value %>
+      </span>
+    <% end %>
+  </div>
+
+  <% if metric.description %>
+    <small class="text-muted"><%= metric.description %></small>
+  <% end %>
+</li>

data/app/views/max_page/metrics/index.html.erb

@@ -0,0 +1,48 @@
+<% if @metrics.blank? %>
+  <div class="bg-dark shadow-lg">
+    <div class="container pt-4 pb-3 text-white">
+      <h1>
+        Almost there!
+      </h1>
+    </div>
+  </div>
+  <div class="container mt-4">
+    You need to set up the metrics. Go to the <a href="https://github.com/lucasmncastro/maxpage" target="blank">README</a> to more informations.
+  </div>
+<% else %>
+  <div class="<%= @alright ? 'bg-success' : 'bg-warning' %> shadow-lg">
+    <div class="container pt-4 pb-3 text-white">
+      <h1>
+        <%= @message %>
+      </h1>
+    </div>
+  </div>
+  
+  <div class="container mt-4">
+    <% if @metrics_without_group.any? %>
+      <div class="card card-default mb-3">
+        <ul class="list-group list-group-flush">
+          <% @metrics_without_group.each do |metric| %>
+            <%= render 'metric', metric: metric %>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
+    <% @groups.each do |group| %>
+      <div class="card card-default mb-3">
+        <div class="card-header">
+          <%= group.name %>
+        </div>
+        <ul class="list-group list-group-flush">
+          <% group.metrics.each do |metric| %>
+            <%= render 'metric', metric: metric %>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
+  </div>
+<% end %>
+
+<style>
+  body { background: #f6f8fa; }
+</style>

data/config/routes.rb

@@ -0,0 +1,4 @@
+MaxPage::Engine.routes.draw do
+  get 'metrics/index', as: :metrics_index
+  root 'metrics#index'
+end

data/lib/max_page/configuration.rb

@@ -0,0 +1,68 @@
+module MaxPage
+  class Configuration
+    attr_reader :metrics, :groups
+
+    def initialize
+      @groups = []
+      @metrics = []
+      @success_message = "It's all right!"
+      @warning_message = "Something is wrong!"
+    end
+
+    # Same method to set and get the title.
+    def title(title=nil)
+      return @title if title.nil?
+
+      @title = title
+    end
+
+    # Same method to set and get the before_action block.
+    def before_action(&block)
+      return @before_action if block.nil?
+
+      @before_action ||= block
+    end
+
+    # Same method to set and get the title.
+    def success_message(message=nil)
+      return @success_message if message.nil?
+
+      @success_message = message
+    end
+
+    # Same method to set and get the title.
+    def warning_message(message=nil)
+      return @warning_message if message.nil?
+
+      @warning_message = message
+    end
+
+    # Add a metric.
+    def metric(name, description: nil, verify: nil, &block)
+      metric = Metric.new
+      metric.name = name
+      metric.description = description
+      metric.verify = verify
+      metric.block = block
+
+      if @current_group
+        metric.group = @current_group
+        @current_group.metrics << metric
+      end
+
+      @metrics << metric
+    end
+
+    def group(name=nil, &block)
+      group = Group.new
+      group.name = name
+      group.metrics = []
+
+      @current_group = group
+      instance_eval(&block)
+      @current_group = nil
+
+      @groups << group
+    end
+  end
+end

data/lib/max_page/engine.rb

@@ -0,0 +1,5 @@
+module MaxPage
+  class Engine < ::Rails::Engine
+    isolate_namespace MaxPage
+  end
+end

data/lib/max_page/group.rb

@@ -0,0 +1,5 @@
+module MaxPage
+  class Group
+    attr_accessor :name, :metrics
+  end
+end

data/lib/max_page/metric.rb

@@ -0,0 +1,43 @@
+module MaxPage
+  class Metric
+    attr_accessor :name, :description, :verify, :group, :block
+    attr_reader :value
+
+    def run
+      @value = block.call
+    end
+
+    def verify?
+      !!verify
+    end
+
+    def verify=(rules)
+      if rules.is_a? Hash
+        invalid_options = rules.keys - [:min, :max]
+        raise "Invalid rule: #{invalid_options.join(', ')}" if invalid_options.any?
+      end
+
+      @verify = rules
+    end
+
+    def ok?
+      return true if not verify?
+
+      run if not value
+
+      if verify.is_a? Hash
+        validations = verify.map do |rule_name, rule_value|
+          case rule_name
+          when :min then value.to_i >= rule_value
+          when :max then value.to_i <= rule_value
+          else
+            raise "Invalid rule: #{rule_name}"
+          end
+        end
+        validations.all? true
+      else
+        value == verify
+      end
+    end
+  end
+end

data/lib/max_page/version.rb

@@ -0,0 +1,3 @@
+module MaxPage
+  VERSION = "0.1.0"
+end

data/lib/maxpage.rb

@@ -0,0 +1,18 @@
+require "max_page/version"
+require "max_page/engine"
+require "max_page/configuration"
+require "max_page/metric"
+require "max_page/group"
+
+module MaxPage
+  class << self
+    def setup(&block)
+      @config = Configuration.new
+      config.instance_eval &block
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

data/lib/tasks/maxpage_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :maxpage do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: maxpage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucas Castro
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Max is a Ruby on Rails engine that provides a DLS to sniff and tell you
+  if everything is running well.
+email:
+- castro.lucas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/maxpage_manifest.js
+- app/controllers/max_page/application_controller.rb
+- app/controllers/max_page/metrics_controller.rb
+- app/helpers/max_page/application_helper.rb
+- app/helpers/max_page/metrics_helper.rb
+- app/jobs/max_page/application_job.rb
+- app/mailers/max_page/application_mailer.rb
+- app/models/max_page/application_record.rb
+- app/views/layouts/max_page/application.html.erb
+- app/views/max_page/metrics/_metric.html.erb
+- app/views/max_page/metrics/index.html.erb
+- config/routes.rb
+- lib/max_page/configuration.rb
+- lib/max_page/engine.rb
+- lib/max_page/group.rb
+- lib/max_page/metric.rb
+- lib/max_page/version.rb
+- lib/maxpage.rb
+- lib/tasks/maxpage_tasks.rake
+homepage: https://github.com/lucasmncastro/maxpage
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lucasmncastro/maxpage
+  source_code_uri: https://github.com/lucasmncastro/maxpage
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key: 
+specification_version: 4
+summary: Simplest way to create a usage and status page for your Rails app.
+test_files: []