kennel 1.113.3 → 1.115.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1820e573733a40ccb56114ecc6c94f8d7732feb10d556f3bf1107c9d21fab7f0
-  data.tar.gz: ed5230938e75e643c71b719f6ec4e3e317e9e94d9fb1a2848bbbe881eea56f4e
+  metadata.gz: 76e2802df7ab2a6583e3529643deb08c382367dea7f90a7253314959d29a5bec
+  data.tar.gz: 4249c23ca2892cc48ce72dbd9e24fc03f38883d6eaed9b509ef75c78cb31afeb
 SHA512:
-  metadata.gz: beb8e6d2a60fd3c8ebe26cdd14ca70d89b9a107ee0a831cea52601464b7c13afe058f25eaee76add474e728f404d4c56216eea24e5ce4c5a5b58897da1e43af0
-  data.tar.gz: 8000438dd34c1e22334283f2e3892379cc08fadeb6085d74ecd41a3b32fdc0aacb28b9a2019d6bdad7a48bcea94084200f69d8c814054fe928aedf16b06b7ea2
+  metadata.gz: 8bd1740361932ba4e6dfe4d7aff4ad7cbcdc96796020428902fc6551b9768c6ccc434a279c214a638aa119e012267fd8dfe00e9107052c570789a1e563075505
+  data.tar.gz: 266aacb034b8933640c3e95a0319afd5fdc923c857d85a5b039e4e14a2bb47dc1096e8849a1d3060171fed2984d847934465ed845a1e45d27caa465c5ca9fcf4

data/Readme.md

@@ -72,6 +72,95 @@ end
  - `parts/` monitors/dashboards/etc that are used by multiple projects
  - `generated/` projects as json, to show current state and proposed changes in PRs
 
+## About the models
+
+Kennel provides several classes which act as models for different purposes:
+
+* `Kennel::Models::Dashboard`, `Kennel::Models::Monitor`, `Kennel::Models::Slo`, `Kennel::Models::SyntheticTest`;
+  these models represent the various Datadog objects
+* `Kennel::Models::Project`; a container for a collection of Datadog objects
+* `Kennel::Models::Team`; provides defaults and values (e.g. tags, mentions) for the other models.
+
+After loading all the `*.rb` files under `projects/`, Kennel's starting point
+is to find all the subclasses of `Kennel::Models::Project`, and for each one,
+create an instance of that subclass (via `.new`) and then call `#parts` on that
+instance. `parts` should return a collection of the Datadog-objects (Dashboard / Monitor / etc).
+
+### Model Settings
+
+Each of the models defines various settings; for example, a Monitor has `name`, `message`,
+`type`, `query`, `tags`, and many more.
+
+When defining a subclass of a model, one can use `defaults` to provide default values for
+those settings:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  defaults(
+    name: "Error rate",
+    type: "query alert",
+    critical: 5.0,
+    query: -> {
+      "some datadog metric expression > #{critical}"
+    },
+    # ...
+  )
+end
+```
+
+This is equivalent to defining instance methods of those names, which return those values:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  def name
+    "Error rate"
+  end
+
+  def type
+    "query alert"
+  end
+
+  def critical
+    5.0
+  end
+
+  def query
+    "some datadog metric expression > #{critical}"
+  end
+end
+```
+
+except that `defaults` will complain if you try to use a setting name which doesn't
+exist. Note also that you can use either plain values (`critical: 5.0`), or procs
+(`query: -> { ... }`). Using a plain value is equivalent to using a proc which returns
+that same value; use whichever suits you best.
+
+When you _instantiate_ a model class, you can pass settings in the constructor, after
+the project:
+
+```Ruby
+project = Kennel::Models::Project.new
+my_monitor = MyMonitor.new(
+  project,
+  critical: 10.0,
+  message: -> {
+    <<~MESSAGE
+      Something bad is happening and you should be worried.
+
+      #{super()}
+    MESSAGE
+  },
+)
+```
+
+This works just like `defaults` (it checks the setting names, and it accepts
+either plain values or procs), but it applies just to this instance of the class,
+rather than to the class as a whole (i.e. it defines singleton methods, rather
+than instance methods).
+
+Most of the examples in this Readme use the proc syntax (`critical: -> { 5.0 }`) but
+for simple constants you may prefer to use the plain syntax (`critical: 5.0`).
+
 ## Workflows
 <!-- ONLY IN template/Readme.md
 
@@ -226,6 +315,8 @@ module ProjectA
       ...
 ```
 
+On the command line, use the projects `kennel_id` (and if none is set then snake_case of the class name) to refer to the project. For example here`PROJECT=project_a` but if it were `Foo::ProjectA` then `foo_project_a`.
+
 ### Skipping validations
 Some validations might be too strict for your usecase or just wrong, please [open an issue](https://github.com/grosser/kennel/issues) and
 to unblock use the `validate: -> { false }` option.
@@ -246,7 +337,7 @@ so they can be created in a single update and can be re-created if any of them i
 
 ### Debugging changes locally
  - rebase on updated `master` to not undo other changes
- - figure out project name by converting the class name to snake-case
+ - figure out project name by converting the class name to snake_case
  - run `PROJECT=foo bundle exec rake kennel:update_datadog` to test changes for a single project (monitors: remove mentions while debugging to avoid alert spam)
    - use `PROJECT=foo,bar,...` for multiple projects
 

data/lib/kennel/models/project.rb

@@ -11,18 +11,29 @@ module Kennel
       def self.file_location
         @file_location ||= begin
           method_in_file = instance_methods(false).first
+          return if method_in_file.nil?
+
           instance_method(method_in_file).source_location.first.sub("#{Bundler.root}/", "")
         end
       end
 
       def validated_parts
         all = parts
+        unless all.is_a?(Array) && all.all? { |part| part.is_a?(Record) }
+          invalid! "#parts must return an array of Records"
+        end
+
         validate_parts(all)
         all
       end
 
       private
 
+      # let users know which project/resource failed when something happens during diffing where the backtrace is hidden
+      def invalid!(message)
+        raise ValidationError, "#{kennel_id} #{message}"
+      end
+
       # hook for users to add custom validations via `prepend`
       def validate_parts(parts)
       end

data/lib/kennel/settings_as_methods.rb

@@ -3,6 +3,20 @@ module Kennel
   module SettingsAsMethods
     SETTING_OVERRIDABLE_METHODS = [].freeze
 
+    AS_PROCS = ->(options) do
+      # Fragile; depends on the fact that in both locations where AS_PROCS is
+      # used, we're 2 frames away from the user code.
+      file, line, = caller(2..2).first.split(":", 3)
+
+      options.transform_values do |v|
+        if v.class == Proc
+          v
+        else
+          eval "-> { v }", nil, file, line.to_i
+        end
+      end
+    end
+
     def self.included(base)
       base.extend ClassMethods
       base.instance_variable_set(:@settings, [])
@@ -31,7 +45,7 @@ module Kennel
       end
 
       def defaults(options)
-        options.each do |name, block|
+        AS_PROCS.call(options).each do |name, block|
           validate_setting_exist name
           define_method name, &block
         end
@@ -58,12 +72,7 @@ module Kennel
         raise ArgumentError, "Expected #{self.class.name}.new options to be a Hash, got a #{options.class}"
       end
 
-      options.each do |k, v|
-        next if v.class == Proc
-        raise ArgumentError, "Expected #{self.class.name}.new option :#{k} to be Proc, for example `#{k}: -> { 12 }`"
-      end
-
-      options.each do |name, block|
+      AS_PROCS.call(options).each do |name, block|
         self.class.send :validate_setting_exist, name
         define_singleton_method name, &block
       end

data/lib/kennel/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Kennel
-  VERSION = "1.113.3"
+  VERSION = "1.115.0"
 end

data/template/Readme.md

@@ -56,6 +56,95 @@ end
  - `parts/` monitors/dashboards/etc that are used by multiple projects
  - `generated/` projects as json, to show current state and proposed changes in PRs
 
+## About the models
+
+Kennel provides several classes which act as models for different purposes:
+
+* `Kennel::Models::Dashboard`, `Kennel::Models::Monitor`, `Kennel::Models::Slo`, `Kennel::Models::SyntheticTest`;
+  these models represent the various Datadog objects
+* `Kennel::Models::Project`; a container for a collection of Datadog objects
+* `Kennel::Models::Team`; provides defaults and values (e.g. tags, mentions) for the other models.
+
+After loading all the `*.rb` files under `projects/`, Kennel's starting point
+is to find all the subclasses of `Kennel::Models::Project`, and for each one,
+create an instance of that subclass (via `.new`) and then call `#parts` on that
+instance. `parts` should return a collection of the Datadog-objects (Dashboard / Monitor / etc).
+
+### Model Settings
+
+Each of the models defines various settings; for example, a Monitor has `name`, `message`,
+`type`, `query`, `tags`, and many more.
+
+When defining a subclass of a model, one can use `defaults` to provide default values for
+those settings:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  defaults(
+    name: "Error rate",
+    type: "query alert",
+    critical: 5.0,
+    query: -> {
+      "some datadog metric expression > #{critical}"
+    },
+    # ...
+  )
+end
+```
+
+This is equivalent to defining instance methods of those names, which return those values:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  def name
+    "Error rate"
+  end
+
+  def type
+    "query alert"
+  end
+
+  def critical
+    5.0
+  end
+
+  def query
+    "some datadog metric expression > #{critical}"
+  end
+end
+```
+
+except that `defaults` will complain if you try to use a setting name which doesn't
+exist. Note also that you can use either plain values (`critical: 5.0`), or procs
+(`query: -> { ... }`). Using a plain value is equivalent to using a proc which returns
+that same value; use whichever suits you best.
+
+When you _instantiate_ a model class, you can pass settings in the constructor, after
+the project:
+
+```Ruby
+project = Kennel::Models::Project.new
+my_monitor = MyMonitor.new(
+  project,
+  critical: 10.0,
+  message: -> {
+    <<~MESSAGE
+      Something bad is happening and you should be worried.
+
+      #{super()}
+    MESSAGE
+  },
+)
+```
+
+This works just like `defaults` (it checks the setting names, and it accepts
+either plain values or procs), but it applies just to this instance of the class,
+rather than to the class as a whole (i.e. it defines singleton methods, rather
+than instance methods).
+
+Most of the examples in this Readme use the proc syntax (`critical: -> { 5.0 }`) but
+for simple constants you may prefer to use the plain syntax (`critical: 5.0`).
+
 ## Workflows
 
 ### Setup
@@ -208,6 +297,8 @@ module ProjectA
       ...
 ```
 
+On the command line, use the projects `kennel_id` (and if none is set then snake_case of the class name) to refer to the project. For example here`PROJECT=project_a` but if it were `Foo::ProjectA` then `foo_project_a`.
+
 ### Skipping validations
 Some validations might be too strict for your usecase or just wrong, please [open an issue](https://github.com/grosser/kennel/issues) and
 to unblock use the `validate: -> { false }` option.
@@ -228,7 +319,7 @@ so they can be created in a single update and can be re-created if any of them i
 
 ### Debugging changes locally
  - rebase on updated `master` to not undo other changes
- - figure out project name by converting the class name to snake-case
+ - figure out project name by converting the class name to snake_case
  - run `PROJECT=foo bundle exec rake kennel:update_datadog` to test changes for a single project (monitors: remove mentions while debugging to avoid alert spam)
    - use `PROJECT=foo,bar,...` for multiple projects
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kennel
 version: !ruby/object:Gem::Version
-  version: 1.113.3
+  version: 1.115.0
 platform: ruby
 authors:
 - Michael Grosser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-27 00:00:00.000000000 Z
+date: 2022-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday