kennel 2.2.1 → 2.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9945e9a42b446b95f53152f08d74765e4f7c228a4a4e9d3f5770eb6006338a0
-  data.tar.gz: 3cc6fd5ff0cece1763b9a4e798ac9da97df80c6b27b613caf45abe7f9ef4a1eb
+  metadata.gz: b931b9c2d75d6e0d69967e3088795e72d8a5f3f558ff1dd1b6de03efde7aabf8
+  data.tar.gz: '081dde24122f351f92c7dc8f16e7877ec3dcd1f7226bd1e4fc126abd3044798d'
 SHA512:
-  metadata.gz: c43fb32a753b1e59aca9728195612568ec2a11d7d83e7a74daad064bbc5ec2d9f29951d0e0ff66e290d25e357b5a3e2d310cbac0b335ebccb1da7cbb5752a225
-  data.tar.gz: 61f079c7c9a0d8c746c529badc5e2d67fe4c3e8c19e2025ab95516be2667f4b1788d288d3e8420b929dc2fa85a98cd5c6f23b9395c3a066785194f44a02cb0a9
+  metadata.gz: ffd01589e499c34d72dd477f5e3e00369582c42cacbf7eae19493e791b84ecbac42c48c5bf34e3d8c8a6245f555d29f62e3cb879cc2e24892b555766f9b5ffcc
+  data.tar.gz: 7a95114123013fd90a64993f86f217b5f4379e0d3dc6b19d876d2ac42f404b4907ef35b2396c811c4291838ca8183073523090bb2d89882dbbffa6972b40bb38

data/Readme.md

@@ -206,6 +206,7 @@ end
   class MyProject < Kennel::Models::Project
     defaults(
       team: -> { Teams::MyTeam.new }, # use existing team or create new one in teams/
+      # kennel_id: -> { "my_project" } # Custom kennel_id (default is snake_cased class name)
       parts: -> {
         [
           Kennel::Models::Monitor.new(
@@ -249,6 +250,7 @@ Remove the code that created the resource. The next update will delete it (see a
  - go to [datadog dashboard UI](https://app.datadoghq.com/dashboard/lists) and click on _New Dashboard_ to find a dashboard
  - run `URL='https://app.datadoghq.com/dashboard/bet-foo-bar' bundle exec rake kennel:import` and copy the output
  - find or create a project in `projects/`
+ - tags: only `team:` tags are submitted to datadog since nothing else is supported
  - add a dashboard to `parts: [` list, for example:
   ```Ruby
   class MyProject < Kennel::Models::Project
@@ -264,8 +266,9 @@ Remove the code that created the resource. The next update will delete it (see a
             template_variables: -> { ["environment"] }, # see https://docs.datadoghq.com/api/?lang=ruby#timeboards
             kennel_id: -> { "overview-dashboard" }, # make up a unique name
             layout_type: -> { "ordered" },
+            widgets: -> { "... raw widget definitions, most flexible ..." },
             definitions: -> {
-              [ # An array or arrays, each one is a graph in the dashboard, alternatively a hash for finer control
+              [ # each element is a graph in the dashboard, alternatively a hash for complete control just like in `widgets`
                 [
                   # title, viz, type, query, edit an existing graph and see the json definition
                   "Graph name", "timeseries", "area", "sum:mystats.foobar{$environment}"
@@ -274,7 +277,7 @@ Remove the code that created the resource. The next update will delete it (see a
                   # 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 ...
+                  # add events too ... (also supports `:markers` and `:precision`)
                   events: [{q: "tags:foobar,deploy", tags_execution: "and"}]
                 ]
               ]
@@ -286,6 +289,55 @@ Remove the code that created the resource. The next update will delete it (see a
   end
  ```
 
+### Adding a new synthetic test
+ - go to [datadog synthetic tests UI](https://app.datadoghq.com/synthetics/tests) and click on _New_ to create a test
+ - see below
+
+### Updating an existing synthetic test
+ - go to [datadog synthetic tests UI](https://app.datadoghq.com/synthetics/tests) to find a test
+ - run `URL='https://app.datadoghq.com/synthetics/details/abc-def-ghi' bundle exec rake kennel:import` and copy the output
+ - find or create a project in `projects/`
+ - add a synthetic test to `parts: [` list, for example:
+  ```Ruby
+  class MyProject < Kennel::Models::Project
+    defaults(
+      team: -> { Teams::MyTeam.new },
+      parts: -> {
+        [
+          Kennel::Models::SyntheticTest.new(
+            self,
+            id: -> { "abc-def-ghi" }, # id from datadog url, not needed when creating a new test
+            kennel_id: -> { "my-api-test" },
+            name: -> { "My API Test" },
+            type: -> { "api" },
+            subtype: -> { "http" },
+            locations: -> { :all }, # use all locations, or specify: ["aws:us-east-1", "aws:eu-west-1"]
+            message: -> {
+              <<~TEXT
+                API check failed!
+                #{super()}
+              TEXT
+            },
+            options: -> {
+              {
+                tick_every: 60,
+                min_failure_duration: 0,
+                min_location_failed: 1
+              }
+            },
+            config: -> {
+              {
+                assertions: [{ type: "statusCode", operator: "is", target: 200 }],
+                request: { method: "GET", url: "https://example.com/health" }
+              }
+            }
+          )
+        ]
+      }
+    )
+  end
+  ```
+
 ### Updating existing resources with id
 Setting `id` makes kennel take over a manually created datadog resource.
 When manually creating to import, it is best to remove the `id` and delete the manually created resource.
@@ -327,10 +379,11 @@ module ProjectA
 - Use `TRACKING_ID=<project-kennel_id>:<resource-kennel_id>` for single resource:
 
   Use the project kennel_id and the resources kennel_id, for example `class ProjectA` and `FooAlert` would give `project_a:foo_alert`.
+  Alternatively use the path of the generated file `TRACKING_ID=generated/project_a/foo_alert.json`
 
 ### 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.
+to unblock use `ignored_errors: [:name_of_the_error]`.
 
 ### Linking resources with kennel_id
 Link resources with their kennel_id in the format `project kennel_id` + `:` + `resource kennel_id`,
@@ -339,7 +392,7 @@ so they can be created in a single update and can be re-created if any of them i
 
 |Resource|Type|Syntax|
 |---|---|---|
-|Dashboard|uptime|`monitor: {id: "foo:bar"}`|
+|Dashboard|uptime|`monitor_ids: ["foo:bar", "foo:baz"]`|
 |Dashboard|alert_graph|`alert_id: "foo:bar"`|
 |Dashboard|slo|`slo_id: "foo:bar"`|
 |Dashboard|timeseries|`queries: [{ data_source: "slo", slo_id: "foo:bar" }]`|
@@ -388,6 +441,12 @@ Run `rake kennel:alerts TAG=service:my-service` to see all un-muted alerts for a
 ### Validating mentions work
 `rake kennel:validate_mentions` should run as part of CI
 
+Use `KNOWN=foo@bar.com,baz@bar.com` to exempt mentions that are not returned by the API.
+Use `KNOWN_RANDOM=@sns-foo,@sns-bar` to ignore for example SNS handles that are randomly invalid in the API.
+
+### Validating planned changes
+`rake kennel:validate_plan` validates planned monitor and dashboard changes against the Datadog API.
+
 ### Grepping through all of datadog
 ```Bash
 rake kennel:dump > tmp/dump
@@ -405,6 +464,9 @@ https://foo.datadog.com/monitor/123
 ### Find all monitors with No-Data
 `rake kennel:nodata TAG=team:foo`
 
+- `FORMAT=json` to output as JSON with tracking IDs
+- `THRESHOLD_DAYS=N` to filter to monitors with N+ days in no-data
+
 ### Finding the tracking id of a resource
 
 When trying to link resources together, this avoids having to go through datadog UI.
@@ -421,6 +483,15 @@ rake kennel:tracking_id ID=123 RESOURCE=monitor
 - Setting `FORCE_GET_CACHE=true` will cache all get requests, which makes benchmarking improvements more reliable.
 - Setting `STORE=false` will make `rake plan` not update the files on disk and save a bit of time
 
+### Other Environment Variables
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KENNEL_MARKER_TEXT` | Custom marker text to namespace multiple Kennel instances in the same Datadog account. Each instance will only manage resources with its marker. | `Managed by kennel` |
+| `KENNEL_API_CACHE_FILE` | Path to the API cache file for dashboard details. | `tmp/cache/details` |
+| `KENNEL_NO_GENERATE` | When set, skip generating files during `plan` or `update_datadog`. Useful when generated files are already up to date. | - |
+| `NO_IGNORED_ERRORS` | When set, show all validation errors including ones suppressed via `ignored_errors`. | - |
+| `SHOW_UNCACHED_FILL_DETAILS` | When set, print the number of uncached dashboard `show` requests made to fill details during diffing. | - |
+
 ### Integration testing
 ```Bash
 rake play

data/lib/kennel/api.rb

@@ -5,8 +5,6 @@ module Kennel
   class Api
     CACHE_FILE = ENV.fetch("KENNEL_API_CACHE_FILE", "tmp/cache/details")
 
-    RateLimitParams = Data.define(:limit, :period, :remaining, :reset, :name)
-
     def self.with_tracking(api_resource, reply)
       klass = Models::Record.api_resource_map[api_resource]
       return reply unless klass # do not blow up on unknown models
@@ -21,11 +19,12 @@ module Kennel
       @app_key = app_key || ENV.fetch("DATADOG_APP_KEY")
       @api_key = api_key || ENV.fetch("DATADOG_API_KEY")
       url = Utils.path_to_url("")
-      @client = Faraday.new(url: url) { |c| c.adapter :net_http_persistent }
+      @client = Faraday.new(url: url)
     end
 
-    def show(api_resource, id, params = {})
-      response = request :get, "/api/v1/#{api_resource}/#{id}", params: params
+    def show(api_resource, id, params = {}, ignore_404: false)
+      response = request :get, "/api/v1/#{api_resource}/#{id}", params: params, ignore_404: ignore_404
+      return if response.nil? # 404 that was ignored
       response = response.fetch(:data) if api_resource == "slo"
       response[:id] = response.delete(:public_id) if api_resource == "synthetics/tests"
       self.class.with_tracking(api_resource, response)
@@ -56,6 +55,8 @@ module Kennel
     end
 
     def update(api_resource, id, attributes)
+      restore_widget_ids(id, attributes) if api_resource == "dashboard"
+
       response = request :put, "/api/v1/#{api_resource}/#{id}", body: attributes
       response[:id] = response.delete(:public_id) if api_resource == "synthetics/tests"
       self.class.with_tracking(api_resource, response)
@@ -73,14 +74,47 @@ module Kennel
       end
     end
 
+    # fill the resource with the full response from the `show` if `list` does not return it
     def fill_details!(api_resource, list)
       details_cache do |cache|
-        Utils.parallel(list) { |a| fill_detail!(api_resource, a, cache) }
+        results = Utils.parallel(list) { |a| fill_detail!(api_resource, a, cache) }
+
+        # drop resources that were not found (race condition between listing and showing)
+        list.select!.with_index { |_, i| results[i][1] }
+
+        results.count { |uncached, _| uncached }
       end
     end
 
     private
 
+    # keep widget ids stable so stored dashboard urls that point at a widget do not break on every update
+    # widget ids are dropped when diffing since they change on every update, but that also changes them in datadog
+    # and breaks stored urls that point at a specific widget, so restore the previous ids by matching widget titles
+    def restore_widget_ids(id, attributes)
+      return unless (widgets = attributes[:widgets])
+      return unless (current = show("dashboard", id, {}, ignore_404: true))
+
+      ids = {}
+      each_widget_with_key(current[:widgets]) { |key, widget| ids[key] = widget[:id] }
+      each_widget_with_key(widgets) do |key, widget|
+        next unless (id = ids[key])
+        widget[:id] ||= id # do not set nil, that breaks updates
+      end
+    end
+
+    # yield each widget with a key built from its (optional) group title and its own title
+    def each_widget_with_key(widgets, prefix: nil, &block)
+      widgets.each do |widget|
+        title = widget.dig(:definition, :title)
+        key = [prefix, title].compact.join("-")
+        yield key, widget
+        if (nested = widget.dig(:definition, :widgets))
+          each_widget_with_key(nested, prefix: title, &block)
+        end
+      end
+    end
+
     def with_pagination(enabled, params)
       return yield params unless enabled
       raise ArgumentError if params[:limit] || params[:offset]
@@ -97,10 +131,16 @@ module Kennel
     end
 
     # Make diff work even though we cannot mass-fetch definitions
+    # @return [uncached, found]
     def fill_detail!(api_resource, a, cache)
+      uncached = false
       args = [api_resource, a.fetch(:id)]
-      full = cache.fetch(args, a.fetch(:modified_at)) { show(*args) }
-      a.merge!(full)
+      full = cache.fetch(args, a.fetch(:modified_at)) do
+        uncached = true
+        show(*args, ignore_404: true)
+      end
+      a.merge!(full) if full
+      [uncached, !!full]
     end
 
     def details_cache(&block)
@@ -108,44 +148,23 @@ module Kennel
       cache.open(&block)
     end
 
-    def request(method, path, body: nil, params: {}, ignore_404: false)
+    def request(method, path, body: nil, params: {}, ignore_404: false, tries: 5)
       path = "#{path}?#{Faraday::FlatParamsEncoder.encode(params)}" if params.any?
-      with_cache ENV["FORCE_GET_CACHE"] && method == :get, path do
-        response = nil
-        tries = 2
-
-        tries.times do |i|
-          response = Utils.retry Faraday::ConnectionFailed, Faraday::TimeoutError, times: 2 do
-            @client.send(method, path) do |request|
-              request.body = JSON.generate(body) if body
-              request.headers["Content-type"] = "application/json"
-              request.headers["DD-API-KEY"] = @api_key
-              request.headers["DD-APPLICATION-KEY"] = @app_key
-            end
-          end
-
-          rate_limit = RateLimitParams.new(
-            limit: response.headers["x-ratelimit-limit"],
-            period: response.headers["x-ratelimit-period"],
-            remaining: response.headers["x-ratelimit-remaining"],
-            reset: response.headers["x-ratelimit-reset"],
-            name: response.headers["x-ratelimit-name"]
-          )
-
-          if response.status == 429
-            message = "Datadog rate limit #{rate_limit.name.inspect} hit"
-            message += " (#{rate_limit.limit} requests per #{rate_limit.period} seconds)"
-            message += "; sleeping #{rate_limit.reset} seconds before trying again"
-            Kennel.err.puts message
-            sleep rate_limit.reset.to_f
-            redo
+      cached = (ENV["FORCE_GET_CACHE"] && method == :get)
+
+      with_cache cached, path do
+        response = request_with_retries(path, tries) do
+          @client.send(method, path) do |request|
+            request.body = JSON.generate(body) if body
+            request.headers["Content-type"] = "application/json"
+            request.headers["DD-API-KEY"] = @api_key
+            request.headers["DD-APPLICATION-KEY"] = @app_key
           end
-
-          break if i == tries - 1 || method != :get || response.status < 500
-          Kennel.err.puts "Retrying on server error #{response.status} for #{path}"
         end
 
-        if !response.success? && (response.status != 404 || !ignore_404)
+        next if response.status == 404 && ignore_404
+
+        unless response.success?
           message = "Error #{response.status} during #{method.upcase} #{path}\n"
           message << "request:\n#{JSON.pretty_generate(body)}\nresponse:\n" if body
           message << response.body.encode(message.encoding, invalid: :replace, undef: :replace)
@@ -160,6 +179,48 @@ module Kennel
       end
     end
 
+    # retry on rate-limits and server errors, giving up after `tries` attempts
+    def request_with_retries(path, tries, &block)
+      raise ArgumentError, "tries must be > 0" if tries < 1
+      response = nil
+      tries.times do |i|
+        response = Utils.retry Faraday::ConnectionFailed, Faraday::TimeoutError, times: 2, &block
+
+        # we do not count 429s into the "tries", tries are only for real errors
+        # so this could loop forever if datadog consistently 429s
+        if response.status == 429
+          sleep_until_rate_limit_resets(response)
+          redo
+        end
+
+        last_try = (i == tries - 1)
+        break if last_try || response.status < 500
+        Kennel.err.puts "Retrying on server error #{response.status} for #{path}"
+        sleep retry_backoff_time(i)
+      end
+      response
+    end
+
+    def sleep_until_rate_limit_resets(response)
+      limit = response.headers["x-ratelimit-limit"]
+      period = response.headers["x-ratelimit-period"]
+      reset = response.headers["x-ratelimit-reset"]
+      name = response.headers["x-ratelimit-name"]
+
+      message = "Datadog rate limit #{name.inspect} hit"
+      message += " (#{limit} requests per #{period} seconds)"
+      message += "; sleeping #{reset} seconds before trying again"
+
+      Kennel.err.puts message
+      sleep reset.to_f
+    end
+
+    # 0:0.1s - 4:2s
+    def retry_backoff_time(attempt)
+      base = 2**attempt
+      0.1 * base * (0.5 + (rand / 2.0))
+    end
+
     # allow caching all requests to speedup/benchmark logic that includes repeated requests
     def with_cache(enabled, key)
       return yield unless enabled

data/lib/kennel/filter.rb

@@ -2,6 +2,7 @@
 
 module Kennel
   class Filter
+    ID_SEPARATOR = ":"
     attr_reader :project_filter
 
     def initialize
@@ -22,23 +23,18 @@ module Kennel
       !project_filter.nil?
     end
 
-    def matches_project_id?(project_id)
+    def filters_project_id?(project_id)
       !filtering? || project_filter.include?(project_id)
     end
 
-    def matches_tracking_id?(tracking_id)
+    def filters_tracking_id?(tracking_id)
       return true unless filtering?
       return tracking_id_filter.include?(tracking_id) if tracking_id_filter
 
-      project_id = tracking_id.split(":").first
+      project_id = tracking_id.split(ID_SEPARATOR, 2).first
       project_filter.include?(project_id)
     end
 
-    def tracking_id_for_path(tracking_id)
-      return tracking_id unless tracking_id.end_with?(".json")
-      tracking_id.sub("generated/", "").sub(".json", "").sub("/", ":")
-    end
-
     private
 
     attr_reader :tracking_id_filter
@@ -46,7 +42,7 @@ module Kennel
     # needs to be called after read_tracking_id_filter_from_env
     def read_project_filter_from_env
       project_names = ENV["PROJECT"]&.split(",")&.sort&.uniq
-      tracking_project_names = tracking_id_filter&.map { |id| id.split(":", 2).first }&.sort&.uniq
+      tracking_project_names = tracking_id_filter&.map { |id| id.split(ID_SEPARATOR, 2).first }&.sort&.uniq
       if project_names && tracking_project_names && project_names != tracking_project_names
         # avoid everything being filtered out
         raise "do not set a different PROJECT= when using TRACKING_ID="
@@ -57,8 +53,8 @@ module Kennel
     def read_tracking_id_filter_from_env
       return unless (tracking_id = ENV["TRACKING_ID"])
       tracking_id.split(",").map do |id|
-        # allow users to paste the generated/ path of an objects to update it without manually converting
-        tracking_id_for_path(id)
+        # allow using the generated/ path from `git diff` to update objects without manually converting
+        id.include?(ID_SEPARATOR) ? id : PartsSerializer.tracking_id_for_path(id)
       end.sort.uniq
     end
 

data/lib/kennel/importer.rb

@@ -21,6 +21,12 @@ module Kennel
       data = @api.show(model.api_resource, id)
 
       id = data.fetch(:id) # keep native value
+      if resource == "slo"
+        # only set primary if needed to reduce clutter
+        if data[:thresholds] && data[:thresholds].min_by { |t| t[:timeframe].to_i }[:timeframe] != data[:timeframe]
+          data[:primary] = data[:timeframe]
+        end
+      end
       model.normalize({}, data) # removes id
       data[:id] = id
 
@@ -80,7 +86,14 @@ module Kennel
         end
       when "synthetics/tests"
         data[:locations] = :all if data[:locations].sort == Kennel::Models::SyntheticTest::LOCATIONS.sort
-      else
+      when "slo"
+        # sli_specification it is only used by datadog if the user switched to "Bad Events"
+        # otherwise user would be trying to set sli_specification but the slo does not change since query is used
+        if data.key?(:query) && data.key?(:sli_specification)
+          delete = (data.dig(:sli_specification, :count, :bad_events_formula) ? :query : :sli_specification)
+          data.delete delete
+        end
+      else # uncovered
         # noop
       end
 

data/lib/kennel/models/dashboard.rb

@@ -208,9 +208,10 @@ module Kennel
         end
       end
 
-      def validate_update!(diffs)
-        _, path, from, to = diffs.find { |diff| diff[1] == "layout_type" }
-        invalid_update!(path, from, to) if path
+      def allowed_update_error(actual)
+        actual_type = actual[:layout_type]
+        return if actual_type == layout_type
+        "cannot update layout_type from #{actual_type} to #{layout_type}"
       end
 
       private