kennel 1.16.1 → 1.16.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d67a0d2b5d6d6b4d4862d7a5b99710e6ec4e775c281b11dff4495400a6f2cb4b
-  data.tar.gz: cb1835599773e4a9eb78b00469f5964b4f1490b6dcb583e8fe30c39d39f5ce42
+  metadata.gz: 617e550ae31d28ef32f0e46948246f78156fddde356a0c42bd6dfcacf63eac8d
+  data.tar.gz: d7e3b335b847c8bfe3d9a1cf2a4d967160539137ebe64704a5d71c7b5ac2ccda
 SHA512:
-  metadata.gz: 935b9f68937e7fe8b26174c78ed2a5bcc9bbe282917c0da212d44a160dffc3dbfd4ca34ec6c25ae8a86dcdfd9e774b1712bb24895eaa8d2ce2f1cd364a8cbcc9
-  data.tar.gz: 1b6e28c77a09bcc7dc5af9409e85437b64212411ef029f8eaf7f60e41c24d7fedef797f3f0685c214cb16da868e63f44c4caab968e87d5ec3754d033a29531bc
+  metadata.gz: 723d7464968287acb6157a59f3cebc30322c17c92dfad47a9e1a49c63a4c5ab3a490b1a13bc179591c30c424b57ac28410526c493bc80ca34b5084ec8f3b65ba
+  data.tar.gz: 62cf68ab5ef460ece823a3ac014542692afabb8980c84f584af1b5de73230508039ab634bfcfa480f1608b6a7b9039734de5ef98b337e82a596540d82092d3b5

data/lib/kennel/version.rb

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

data/template/Readme.md

@@ -0,0 +1,188 @@
+# Kennel
+
+![](github/cage.jpg?raw=true)
+
+Keep datadog monitors/dashboards/etc in version control, avoid chaotic management via UI.
+
+ - Documented, reusable, automated, and searchable configuration
+ - Changes are PR reviewed and auditable
+ - Good defaults like no-data / re-notify are preselected
+ - Reliable cleanup with automated deletion
+
+![](github/screen.png?raw=true)
+
+## Structure
+
+ - `projects/` monitors/dashboards/etc scoped by project
+ - `teams/` team definitions
+ - `parts/` monitors/dashes/etc that are used by multiple projects
+ - `generated/` projects as json, to show current state and proposed changes in PRs
+
+## Workflows
+
+### Setup
+ - clone the repo
+ - `gem install bundler && bundle install`
+ - go to [Datadog API Settings](https://app.datadoghq.com/account/settings#api)
+ - find or create your personal "Application Key" and add it to `.env` as `DATADOG_APP_KEY=` (will be on the last page if new)
+ - copy any `API Key` and add it to `.env` as `DATADOG_API_KEY`
+
+### Adding a team
+
+```ruby
+# teams/my_team.rb
+module Teams
+  class MyTeam < Kennel::Models::Team
+    defaults(
+      slack: -> { "my-alerts" },
+      email: -> { "my-team@exmaple.com" }
+    )
+  end
+end
+```
+
+### Adding a new monitor
+ - use [datadog monitor UI](https://app.datadoghq.com/monitors#create/metric) to create a monitor
+ - get the `id` from the url, click "Export Monitor" on the monitors edit tab to get the `query` and `type`
+ - see below
+
+### Updating an existing monitor
+ - find or create a project in `projects/`
+ - add a monitor to `parts: [` list
+  ```Ruby
+  # projects/my_project.rb
+  class MyProject < Kennel::Models::Project
+    defaults(
+      team: -> { Teams::MyTeam.new }, # use existing team or create new one in teams/
+      parts: -> {
+        [
+          Kennel::Models::Monitor.new(
+            self,
+            id: -> { 123456 }, # id from datadog url
+            type: -> { "query alert" },
+            kennel_id: -> { "load-too-high" }, # make up a unique name
+            name: -> { "Foobar Load too high" }, # nice descriptive name that will show up in alerts and emails
+            message: -> {
+              # Explain what behavior to expect and how to fix the cause. Use #{super()} to add team notifications.
+              <<~TEXT
+                Foobar will be slow and that could cause Barfoo to go down.
+                Add capacity or debug why it is suddenly slow.
+                #{super()}
+              TEXT
+            },
+            query: -> { "avg(last_5m):avg:system.load.5{hostgroup:api} by {pod} > #{critical}" }, # replace actual value with #{critical} to keep them in sync
+            critical: -> { 20 }
+          )
+        ]
+      }
+    )
+  end
+  ```
+ - `bundle exec rake plan` update to existing should be shown (not Create / Delete)
+ - alternatively: `bundle exec rake generate` to only update the generated `json` files
+ - review changes then `git commit`
+ - make a PR ... get reviewed ... merge
+ - datadog is updated by travis
+
+### Adding a new dashboard
+ - go to [datadog dashboard UI](https://app.datadoghq.com/dash/list) and click on _New Dashboard_ to create a dashboard
+ - get the `id` from the url
+ - see below
+
+### Updating an existing dashboard
+ - find or create a project in `projects/`
+ - add a dashboard to `parts: [` list
+  ```Ruby
+  class MyProject < Kennel::Models::Project
+    defaults(
+      team: -> { Teams::MyTeam.new }, # use existing team or create new one in teams/
+      parts: -> {
+        [
+          Kennel::Models::Dash.new(
+            self,
+            id: -> { 123457 }, # id from datadog url
+            title: -> { "My Dashboard" },
+            description: -> { "Overview of foobar" },
+            template_variables: -> { ["environment"] }, # see https://docs.datadoghq.com/api/?lang=ruby#timeboards
+            kennel_id: -> { "overview-dashboard" }, # make up a unique name
+            definitions: -> {
+              [ # An array or arrays, each one is a graph in the dashboard, alternatively a hash for finer control
+                [
+                  # title, viz, type, query, edit an existing graph and see the json definition
+                  "Graph name", "timeseries", "area", "sum:mystats.foobar{$environment}"
+                ],
+                [
+                  # queries can be an Array as well, this will generate multiple requests
+                  # for a single graph
+                  "Graph name", "timeseries", "area", ["sum:mystats.foobar{$environment}", "sum:mystats.success{$environment}"],
+                  # add events too ...
+                  events: [{q: "tags:foobar,deploy", tags_execution: "and"}]
+                ]
+              ]
+            }
+          )
+        ]
+      }
+    )
+  end
+ ```
+
+### Adding a new screenboard
+ - similar to `dash.rb`
+ - add to `parts:` list
+  ```Ruby
+  Kennel::Models::Screen.new(
+    self,
+    board_title: -> { "test-board" },
+    kennel_id: -> { "test-screen" },
+    widgets: -> {
+      [
+        {text: "Hello World", height: 6, width: 24, x: 0, y: 0, type: "free_text"},
+        {title_text: "CPU", height: 12, width: 36, timeframe: "1mo", x: 0, y: 6, type: "timeseries", tile_def: {viz: "timeseries", requests: [{q: "avg:system.cpu.user{*}", type: "line"}]}}
+      ]
+    }
+  )
+ ```
+
+### Skipping validations
+
+Some validations might be too strict for your usecase or just wrong, please open an issue and
+to unblock use the `validate: -> { false }` option.
+
+### Debugging locally
+
+ - make sure to be on update `master` to not undo other changes
+ - run `PROJECT=foo bundle exec rake kennel:update_datadog` to test changes for a single project
+
+### Listing umuted alerts
+
+Run `rake kennel:alerts TAG=service:my-service` to see all un-muted alerts for a given datadog monitor tag.
+
+## Examples
+
+### Reusable monitors/dashes/etc
+
+Add to `parts/<folder>`.
+
+```Ruby
+module Monitors
+  class LoadTooHigh < Kennel::Models::Monitor
+    defaults(
+      name: -> { "#{project.name} load too high" },
+      message: -> { "Shut it down!" },
+      query: -> { "avg(last_5m):avg:system.load.5{hostgroup:#{project.kennel_id}} by {pod} > #{critical}" }
+    )
+  end
+end
+```
+
+Reuse it in multiple projects.
+
+```Ruby
+class Database < Kennel::Models::Project
+  defaults(
+    team: -> { Kennel::Models::Team.new(slack: -> { 'foo' }, kennel_id: -> { 'foo' }) },
+    parts: -> { [Monitors::LoadTooHigh.new(self, critical: -> { 13 })] }
+  )
+end
+```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kennel
 version: !ruby/object:Gem::Version
-  version: 1.16.1
+  version: 1.16.2
 platform: ruby
 authors:
 - Michael Grosser
@@ -64,6 +64,7 @@ files:
 - lib/kennel/unmuted_alerts.rb
 - lib/kennel/utils.rb
 - lib/kennel/version.rb
+- template/Readme.md
 homepage: https://github.com/grosser/kennel
 licenses:
 - MIT