mdash 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f04e567a5a7a3c4f5c350db0a238c0f1193b9a312b60069159c740a6c64a309b
-  data.tar.gz: 4e22e7a1d14be1045162856737f72e181ba86b7f7041e2241e59dc44c0d55c45
+  metadata.gz: 99e02fcb481a90b671b153894b496e402c72e5507ec3c5905de47290395e5161
+  data.tar.gz: 63a4ea369081f75e2515677df81f35261637da50195586dc9bdf4c0c39cd90e0
 SHA512:
-  metadata.gz: 9ea1ac9cbc669d1673cfc5cec7b3eebd935c08ea2ae8a7703d926cf7aefa9f867ed47bf6b195bd26c52508f1fdf1f940a161c27ce2f4443cd1603c5df568fd4c
-  data.tar.gz: cdbe84f79f38cf298fd22bd0ef792025dfe152c57eeb6daa649bf9911ad927e40898b36bc1de8855293188dac4f9ec7756907aad7822161c13ffb350c207e1bc
+  metadata.gz: 67a995b78d3f381fa6c54333ed805fc16ebd8ffa6ed9e3e39522a9bd552dde5f77e9f9985e5bfe9c96c1e15f2b5ae33b3ff149f059cd03d69e16d9e04e892567
+  data.tar.gz: 54fcde0b2ef3cb0fc2784e632efb9e66a9b409c456bf24a58284f73f4a5f6e156ec9f42ac7f27645c6354c424d10a9d00bcc838ea1ac7ab32ea9d067e35198d4

data/README.md

@@ -35,9 +35,301 @@ Mount the Mdash engine in your routes file
 mount Mdash::Engine => "/mdash"
 ```
 
+#### Configuration
+
+There are three main sections to be configured to properly setup Mdash in your Rails app.
+
+##### Site Name
+
+This is the name of your site that will be displayed in the Mdash dashboard when setting up widgets.
+
+```ruby
+config.site_name = "Your Site Name"
+```
+
+##### Secret
+
+This is the secret key that will be used to authenticate requests from Mdash to your app. 
+In the future we plan to support authing against Mdash and storing the secret on our service but for now direct connections are the only way 
+
+Requirements:
+- Must be a string
+- Must be at least 10 characters long but really use a longer one, please
+- Ideally store this in your Rails credentials file or a secret manager
+
+```ruby
+config.secret = "a-really-long-secret-key"
+```
+
+##### Exported Metrics
+
+This is where you define the metrics that you want to expose to Mdash.
+Mdash will have predefined templates for common metrics but you can also define your own custom metrics.
+
+A metric is defined by the following attributes:
+- `model` - The name of the model that the metric is based on
+- `metrics` - A hash of metrics that you want to expose
+  - `aggregation` - The type of aggregation to perform on the model
+  - `aggregation_field` - The field to aggregate on, defaults to `id`
+  - `period` - The period over which to aggregate the metric
+  - `periods` - The number of periods to aggregate over
+  - `modifier` - A modifier to apply to the aggregation
+
+Valid aggregations are:
+- `:count` - Count the number of records
+- `:sum` - Sum the values of a column
+- `:average` - Average the values of a column
+
+If you define an aggregation of sum or average you should also define the field to aggregate on with the `aggregation_field` attribute.
+- String
+- Default is `id`
+
+Valid period values are:
+- `nil` - No period, aggregate over all time
+- `:hour` - Aggregate over an hour
+- `:day` - Aggregate over a day
+- `:week` - Aggregate over a week
+- `:month` - Aggregate over a month
+- `:year` - Aggregate over a year
+
+If you define a period you can also define the number of periods to aggregate over with the `periods` attribute.
+- Integer > 1
+- Default is 1
+- If periods is set then we will return an object of values even if periods is 1
+
+If you define a modifier you can also define the modifier with the `modifier` attribute.
+- String
+- Default is nil
+- Must be a method that exists on the model 
+
+##### Example Config
+
+Here's a real world example from https://timewith.xyz
+
+```ruby
+Mdash.configure do |config|
+  config.site_name = "Timewith"
+  config.secret = Rails.application.credentials.dig(:mdash, :secret)
+
+  config.exported_metrics = {
+    users: {
+      model: "Account",
+      metrics: {
+        total: {
+          aggregation: :count,
+        },
+        recent_signups: {
+          aggregation: :count,
+          period: :week,
+        },
+        weekly_signups: {
+          aggregation: :count,
+          period: :week,
+          periods: 12,
+        }
+      }
+    },
+    profiles: {
+      model: "Profile",
+      metrics: {
+        total: {
+          aggregation: :count,
+        }
+      }
+    },
+    events: {
+      model: "Event",
+      metrics: {
+        total: {
+          aggregation: :count,
+        }
+      }
+    },
+    bookings: {
+      model: "Booking",
+      metrics: {
+        total: {
+          aggregation: :count,
+        },
+        recent: {
+          aggregation: :count,
+          period: :week,
+        },
+        weekly: {
+          aggregation: :count,
+          period: :week,
+          periods: 12,
+        },
+        cancelled_total: {
+          aggregation: :count,
+          modifier: "cancelled",
+        },
+        cancelled_recent: {
+          aggregation: :count,
+          period: :week,
+          modifier: "cancelled",
+        },
+      }
+    }
+  }
+end
+```
+
+## Consuming
+
+The simplest way to consume the metrics from Mdash is to use the Mdash App (coming soon).
+
+If you want to consume the metrics in your own app you can use the Mdash API.
+
+#### API
+
+The Mdash API is a simple RESTful API that allows you to fetch the metrics that you have defined in your Rails app.
+
+##### Authentication
+
+To authenticate with the Mdash API you need to include the secret key that you defined in your Rails app as a header "X-Mdash-Token"
+
+##### Announce
+
+The announce endpoint contains a list of all the valid metrics that you have defined in your Rails app.
+
+```http
+GET /mdash/announce
+```
+
+```json
+{
+  "site_name": "Timewith",
+  "metrics": [
+    {
+      "name": "users_total",
+      "model": "Account",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": null,
+      "periods": null,
+      "modifier": null
+    },
+    {
+      "name": "users_recent_signups",
+      "model": "Account",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": "week",
+      "periods": null,
+      "modifier": null
+    },
+    {
+      "name": "users_weekly_signups",
+      "model": "Account",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": "week",
+      "periods": 12,
+      "modifier": null
+    },
+    {
+      "name": "profiles_total",
+      "model": "Profile",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": null,
+      "periods": null,
+      "modifier": null
+    },
+    {
+      "name": "events_total",
+      "model": "Event",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": null,
+      "periods": null,
+      "modifier": null
+    },
+    {
+      "name": "bookings_total",
+      "model": "Booking",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": null,
+      "periods": null,
+      "modifier": null
+    },
+    {
+      "name": "bookings_recent",
+      "model": "Booking",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": "week",
+      "periods": null,
+      "modifier": null
+    },
+    {
+      "name": "bookings_weekly",
+      "model": "Booking",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": "week",
+      "periods": 12,
+      "modifier": null
+    },
+    {
+      "name": "bookings_cancelled_total",
+      "model": "Booking",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": null,
+      "periods": null,
+      "modifier": "cancelled"
+    },
+    {
+      "name": "bookings_cancelled_recent",
+      "model": "Booking",
+      "aggregation": "count",
+      "aggregation_field": "id",
+      "period": "week",
+      "periods": null,
+      "modifier": "cancelled"
+    }
+  ]
+}
+```
+
+##### Stats
+
+The stats endpoint allows you to fetch the values of the metrics that you have defined in your Rails app.
+Stats contains the rollup values for each metric.
+Last updated is the time that the stats were last updated (ie. if they're stale or cached)
+
+```http
+GET /mdash/stats
+```
+
+```json
+{
+  "stats": {
+    "users_total": 1,
+    "users_recent_signups": 0,
+    "users_weekly_signups": {
+      "2025-01-05": 1
+    },
+    "profiles_total": 2,
+    "events_total": 2,
+    "bookings_total": 4,
+    "bookings_recent": 0,
+    "bookings_weekly": {
+      "2025-01-05": 4
+    },
+    "bookings_cancelled_total": 0,
+    "bookings_cancelled_recent": 0
+  },
+  "last_updated": "2025-01-05T00:00:00Z"
+}
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/imothee/mdash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/imothee/policygen/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/imothee/mdash-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/imothee/policygen/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/app/controllers/mdash/announce_controller.rb

@@ -1,18 +1,22 @@
 module Mdash
   class AnnounceController < ApplicationController
     def index
-      available = Mdash.config.metrics.each_with_object({}) do |metric, hash|
-        hash[metric.id] = {
+      metrics = Mdash.config.metrics.map { |metric|
+        {
+          name: metric.id,
           model: metric.model,
           aggregation: metric.aggregation,
-          aggregation_column: metric.aggregation_column,
+          aggregation_field: metric.aggregation_field,
           period: metric.period,
           periods: metric.periods,
           modifier: metric.modifier
         }
-      end
+      }
 
-      render json: available.as_json
+      render json: {
+        site_name: Mdash.config.site_name,
+        metrics: metrics
+      }.as_json
     end
   end
 end

data/app/controllers/mdash/stats_controller.rb

@@ -1,8 +1,10 @@
 module Mdash
   class StatsController < ApplicationController
     def index
-      @stats = Mdash.stats
-      render json: @stats
+      render json: {
+        stats: Mdash.stats,
+        last_updated: Mdash.last_updated
+      }.as_json
     end
   end
 end

data/app/models/mdash/metric.rb

@@ -7,7 +7,7 @@ module Mdash
     # Valid periods
     PERIODS = %i[hour day week month year].freeze
 
-    attr_reader :id, :model, :aggregation, :aggregation_column, :period, :periods, :modifier
+    attr_reader :id, :model, :aggregation, :aggregation_field, :period, :periods, :modifier
 
     def self.all(configuration: nil)
       configuration ||= Mdash.config
@@ -20,11 +20,11 @@ module Mdash
       end
     end
 
-    def initialize(id:, model:, aggregation:, aggregation_column: :id, period: nil, periods: nil, modifier: nil)
+    def initialize(id:, model:, aggregation:, aggregation_field: :id, period: nil, periods: nil, modifier: nil)
       @id = id.to_sym
       @model = model.to_sym
       @aggregation = aggregation.to_sym
-      @aggregation_column = aggregation_column.to_sym
+      @aggregation_field = aggregation_field.to_sym
       @period = period&.to_sym
       @periods = periods
       @modifier = modifier
@@ -34,6 +34,8 @@ module Mdash
       return false unless AGGREGATIONS.include?(@aggregation)
       return false unless PERIODS.include?(@period) if @period.present?
 
+      return false if @periods.present? && !@periods.positive?
+
       true
     end
 
@@ -82,9 +84,9 @@ module Mdash
     def aggregation_query(query)
       case @aggregation
       when :sum
-        query.sum(@aggregation_column)
+        query.sum(@aggregation_field)
       when :avg
-        query.average(@aggregation_column)
+        query.average(@aggregation_field)
       when :count
         query.count
       end

data/lib/generators/mdash/templates/config/initializers/mdash.rb.tt

@@ -1,6 +1,10 @@
 # Use this setup block to configure all options available in Mdash
 Mdash.configure do |config|
+  config.site_name = "<%= Rails.application.class.module_parent.name %>"
   config.secret = "<%= SecureRandom.hex(32) %>"
 
+  # How long should we cache metrics for so we don't hit the database too often?
+  # config.cache_expiry = 5.minutes
+
   config.exported_metrics = {}
 end

data/lib/mdash/configuration.rb

@@ -1,19 +1,33 @@
 module Mdash
   class Configuration
+    attr_accessor :site_name
     attr_accessor :secret
+    attr_accessor :cache_expiry
     attr_accessor :exported_metrics
 
+    def initialize
+      @cache_expiry = 5.minutes
+    end
+
     def metrics
-      @metrics ||= exported_metrics.flat_map do |prefix, params|
-        model = params[:model]
-        params[:metrics].map do |k, metric_params|
-          metric = Metric.new(id: "#{prefix}_#{k}", model: model, **metric_params)
+      @metrics ||= exported_metrics.each_with_object([]) do |(prefix, params), arr|
+        # Check if the model exists, if not return
+        next Rails.logger.warn("Invalid model: #{params[:model]}") unless params[:model].to_s.classify.safe_constantize
+
+        params[:metrics].each do |k, metric_params|
+          id = "#{prefix}_#{k}".to_sym
+          # Check if the metric is a hash
+          next Rails.logger.warn("Metric is not a hash: #{id}") unless metric_params.is_a?(Hash)
+          # Check if metric id is unique
+          next Rails.logger.warn("Duplicate metric: #{id}") if arr.any? { |m| m.id == id }
+
+          # Create the metric
+          metric = Metric.new(id:, model: params[:model], **metric_params)
+
           # Check if the metric is valid
-          unless metric.valid?
-            Rails.logger.warn("Invalid metric: #{metric.id}")
-            return nil
-          end
-          metric
+          next Rails.logger.warn("Invalid metric: #{id}") unless metric.valid?
+
+          arr << metric
         end
       end
     end

data/lib/mdash/version.rb

@@ -1,3 +1,3 @@
 module Mdash
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/mdash.rb

@@ -18,15 +18,18 @@ module Mdash
     def stats
       # Check the last time stats were updated
       # If it's been more than 5 minutes, update the stats
-      if @last_updated.nil? || @last_updated < 5.minutes.ago
-        @stats = config.metrics.reduce({}) do |stats, metric|
+      if @last_updated.nil? || @last_updated < config.cache_expiry.ago
+        @stats = config.metrics.each_with_object({}) do |metric, stats|
           stats[metric.id] = metric.data
-          stats
         end
         @last_updated = Time.now
       end
       @stats
     end
+
+    def last_updated
+      @last_updated
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mdash
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tim Marks