kennel 2.2.1 → 2.22.0

data/lib/kennel/syncer.rb

@@ -13,14 +13,13 @@ module Kennel
 
     attr_reader :plan
 
-    def initialize(api, expected, actual, filter:, strict_imports: true)
+    def initialize(api, expected:, actual:, filter:, strict_imports: true)
       @api = api
       @strict_imports = strict_imports
       @filter = filter
 
       @resolver = Resolver.new(expected: expected, filter: filter)
       @plan = Plan.new(*calculate_changes(expected: expected, actual: actual))
-      validate_changes
     end
 
     def print_plan
@@ -94,7 +93,8 @@ module Kennel
         convert_replace_into_update!(matching, unmatched_actual, unmatched_expected)
 
         validate_expected_id_not_missing unmatched_expected
-        fill_details! matching # need details to diff later
+        uncached = fill_details! matching # need details to diff later
+        Kennel.out.puts "Uncached dashboard gets to fill details: #{uncached}" if ENV["SHOW_UNCACHED_FILL_DETAILS"]
 
         # update matching if needed
         updates = matching.map do |e, a|
@@ -126,21 +126,19 @@ module Kennel
     # if there is a new item that has the same name or title as an "to be deleted" item,
     # update it instead to avoid old urls from becoming invalid
     # - careful with unmatched_actual being huge since it has all api resources
-    # - don't do it when a monitor type is changing since that would block the update
-    # - when using a filter and updating the kennel_id of an existing item, old and new must be in the filter
+    # - don't do it when update is not allowed
+    # - when using a filter and updating the kennel_id of an existing item, old and new must be in the filter (PROJECT= works, but not TRACKING_ID)
     def convert_replace_into_update!(matching, unmatched_actual, unmatched_expected)
       unmatched_expected.reject! do |e|
-        e_field, e_value = Kennel::Models::Record::TITLE_FIELDS.detect do |field|
-          next unless (value = e.as_json[field])
-          break [field, value]
-        end
-        raise unless e_field #  uncovered: should never happen ...
-        e_monitor_type = e.as_json[:type]
-
+        # find actual by title
+        e_field, e_value = title_field_and_value(e)
         actual = unmatched_actual.detect do |a|
-          a[:klass].api_resource == e.class.api_resource && a[e_field] == e_value && a[:type] == e_monitor_type
+          a[:klass].api_resource == e.class.api_resource &&
+            a[e_field] == e_value
         end
-        next false unless actual # keep in unmatched
+
+        # keep unmatched if we could not find or can't update
+        next false if !actual || e.allowed_update_error(actual)
 
         # add as update and remove from unmatched
         unmatched_actual.delete(actual)
@@ -150,10 +148,18 @@ module Kennel
       end
     end
 
-    # fill details of things we need to compare
-    def fill_details!(details_needed)
-      details_needed = details_needed.map { |e, a| a if e && e.class.api_resource == "dashboard" }.compact
-      @api.fill_details! "dashboard", details_needed
+    def title_field_and_value(e)
+      Kennel::Models::Record::TITLE_FIELDS.detect do |field|
+        next unless (value = e.as_json[field])
+        return [field, value]
+      end
+      raise # uncovered: should never happen ...
+    end
+
+    # fill details of things we need to compare, so diff works even though we cannot mass-fetch definitions
+    def fill_details!(matching)
+      dashboards = matching.filter_map { |e, a| a if e && e.class.api_resource == "dashboard" }
+      @api.fill_details! "dashboard", dashboards
     end
 
     def validate_expected_id_not_missing(expected)
@@ -169,20 +175,12 @@ module Kennel
       end
     end
 
-    # We've already validated the desired objects ('generated') in isolation.
-    # Now that we have made the plan, we can perform some more validation.
-    def validate_changes
-      @plan.updates.each do |item|
-        item.expected.validate_update!(item.diff)
-      end
-    end
-
     def filter_actual!(actual)
       return unless filter.filtering? # minor optimization
 
       actual.select! do |a|
         tracking_id = a.fetch(:tracking_id)
-        tracking_id.nil? || filter.matches_tracking_id?(tracking_id)
+        tracking_id.nil? || filter.filters_tracking_id?(tracking_id)
       end
     end
   end

data/lib/kennel/tasks/dump.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+namespace :kennel do
+  desc "Dump ALL of datadog config as raw json ... useful for grep/search [TYPE=slo|monitor|dashboard]"
+  task dump: :environment do
+    resources =
+      if (type = ENV["TYPE"])
+        [type]
+      else
+        Kennel::Models::Record.api_resource_map.keys
+      end
+    api = Kennel::Api.new
+    list = nil
+    first = true
+
+    Kennel.out.puts "["
+    resources.each do |resource|
+      Kennel::Progress.progress("Downloading #{resource}") do
+        list = api.list(resource)
+        api.fill_details!(resource, list) if resource == "dashboard"
+      end
+      list.each do |r|
+        r[:api_resource] = resource
+        if first
+          first = false
+        else
+          Kennel.out.puts ","
+        end
+        Kennel.out.print JSON.pretty_generate(r)
+      end
+    end
+    Kennel.out.puts "\n]"
+  end
+
+  desc "Find items from dump by pattern DUMP= PATTERN= [URLS=true]"
+  task dump_grep: :environment do
+    file = ENV.fetch("DUMP")
+    pattern = Regexp.new ENV.fetch("PATTERN")
+    items = File.read(file)[2..-2].gsub("},\n{", "}--SPLIT--{").split("--SPLIT--")
+    models = Kennel::Models::Record.api_resource_map
+    found = items.grep(pattern)
+    exit 1 if found.empty?
+    found.each do |resource|
+      if ENV["URLS"]
+        parsed = JSON.parse(resource)
+        url = models[parsed.fetch("api_resource")].url(parsed.fetch("id"))
+        title = parsed["title"] || parsed["name"]
+        Kennel.out.puts "#{url} # #{title}"
+      else
+        Kennel.out.puts resource
+      end
+    end
+  end
+end

data/lib/kennel/tasks/import.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+namespace :kennel do
+  desc "Convert existing resources to copy-pasteable definitions to import existing resources (call with URL= or call with RESOURCE= and ID=)"
+  task import: :environment do
+    if (id = ENV["ID"]) && (resource = ENV["RESOURCE"])
+      id = Integer(id) if id =~ /^\d+$/
+    elsif (url = ENV["URL"])
+      resource, id = Kennel::Models::Record.parse_any_url(url) || Kennel::Tasks.abort("Unable to parse url")
+    else
+      possible_resources = Kennel::Models::Record.subclasses.map(&:api_resource)
+      Kennel::Tasks.abort("Call with URL= or call with RESOURCE=#{possible_resources.join(" or ")} and ID=")
+    end
+
+    Kennel.out.puts Kennel::Importer.new(Kennel::Api.new).import(resource, id)
+  end
+end

data/lib/kennel/tasks/nodata.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+namespace :kennel do
+  desc "show monitors with no data by TAG, for example TAG=team:foo [THRESHOLD_DAYS=7] [FORMAT=json]"
+  task nodata: :environment do
+    tag = ENV["TAG"] || Kennel::Tasks.abort("Call with TAG=foo:bar")
+    monitors = Kennel::Api.new.list("monitor", monitor_tags: tag, group_states: "no data")
+    monitors.select! { |m| m[:overall_state] == "No Data" }
+    monitors.reject! { |m| m[:tags].include? "nodata:ignore" }
+    if monitors.any?
+      Kennel.err.puts <<~TEXT
+        To ignore monitors with expected nodata, tag it with "nodata:ignore"
+
+      TEXT
+    end
+
+    now = Time.now
+    monitors.each do |m|
+      m[:days_in_no_data] =
+        if m[:overall_state_modified]
+          since = Date.parse(m[:overall_state_modified]).to_time
+          ((now - since) / (24 * 60 * 60)).to_i
+        else
+          999
+        end
+    end
+
+    if (threshold = ENV["THRESHOLD_DAYS"])
+      monitors.select! { |m| m[:days_in_no_data] > Integer(threshold) }
+    end
+
+    monitors.each { |m| m[:url] = Kennel::Utils.path_to_url("/monitors/#{m[:id]}") }
+
+    if ENV["FORMAT"] == "json"
+      report = monitors.map do |m|
+        match = m[:message].to_s.match(/-- #{Regexp.escape(Kennel::Models::Record::MARKER_TEXT)} (\S+:\S+) in (\S+), /) || []
+        m.slice(:url, :name, :tags, :days_in_no_data).merge(
+          kennel_tracking_id: match[1],
+          kennel_source: match[2]
+        )
+      end
+
+      Kennel.out.puts JSON.pretty_generate(report)
+    else
+      monitors.each do |m|
+        Kennel.out.puts m[:name]
+        Kennel.out.puts Kennel::Utils.path_to_url("/monitors/#{m[:id]}")
+        Kennel.out.puts "No data since #{m[:days_in_no_data]}d"
+        Kennel.out.puts
+      end
+    end
+  end
+end

data/lib/kennel/tasks/tracking_id.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+namespace :kennel do
+  desc "Resolve given id to kennel tracking-id RESOURCE= ID="
+  task tracking_id: "kennel:environment" do
+    resource = ENV.fetch("RESOURCE")
+    id = ENV.fetch("ID")
+    klass =
+      Kennel::Models::Record.subclasses.detect { |s| s.api_resource == resource } ||
+      raise("resource #{resource} not know")
+    object = Kennel::Api.new.show(resource, id)
+    Kennel.out.puts klass.parse_tracking_id(object)
+  end
+end

data/lib/kennel/tasks/validate_mentions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+namespace :kennel do
+  desc "Verify that all used monitor  mentions are valid"
+  task validate_mentions: :environment do
+    known = []
+
+    # @slack- @team- @webhook- @sns- user-emails
+    known += Kennel::Api.new.send(:request, :get, "/api/v2/notifications/handles?group_limit=99999")
+      .fetch(:data)
+      .flat_map { |d| d.dig(:attributes, :handles) }
+      .map { |v| v.fetch(:value) }
+
+    # group emails or other 1-off things we know are valid
+    manual = ENV["KNOWN"].to_s.split(",")
+    dupes = (manual & known)
+    Kennel::Tasks.abort "KNOWN=#{dupes.join(",")} values are already known and should be removed" if dupes.any?
+    known += manual
+
+    # @sns- handles are randomly invalid so we need to ignore them without checking if the ignore is needed
+    # https://help.datadoghq.com/hc/en-us/requests/2310423
+    known += ENV["KNOWN_RANDOM"].to_s.split(",")
+
+    bad = []
+    Dir["generated/**/*.json"].each do |f|
+      next unless (message = JSON.parse(File.read(f))["message"])
+      used = message
+        .scan(/(?:^|\s)(@[^\s{,'"]+)/)
+        .flatten(1)
+        .grep(/^@.*@|^@.*-/) # ignore @here etc handles ... datadog uses @foo@bar.com for emails and @foo-bar for integrations
+      (used - known).each { |v| bad << [f, v] }
+    end
+
+    if bad.any?
+      url = Kennel::Utils.path_to_url "/account/settings"
+      Kennel.err.puts "Invalid mentions found, either ignore them by adding to `KNOWN` env var or add them via #{url}"
+      bad.each { |f, v| Kennel.err.puts "Invalid mention #{v} in monitor message of #{f}" }
+      Kennel::Tasks.abort ENV["KNOWN_WARNING"]
+    end
+  end
+end

data/lib/kennel/tasks/validate_plan.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+module Kennel
+  module ValidatePlan
+    class MonitorValidator
+      COSMETIC_FIELDS = ["name", "message", "tags"].freeze
+
+      def initialize(item)
+        @item = item
+      end
+
+      def validate(api)
+        data = @item.expected.as_json
+
+        # ignore unresolved ids from yet to be created monitors
+        return nil if ["composite", "slo alert"].include?(data[:type]) && data[:query].include?("%")
+
+        api.send(:request, :post, "/api/v1/monitor/validate", body: data)
+        nil
+      rescue StandardError => e
+        "#{Kennel::Console.color(:yellow, "#{@item.api_resource} #{@item.tracking_id}:")}\n#{e.message}"
+      end
+    end
+
+    class DashboardValidator
+      COSMETIC_FIELDS = ["title", "description", "tags"].freeze
+
+      def initialize(item)
+        @item = item
+      end
+
+      # datadog does not offer a validation api for dashboards,
+      # so we insert an invalid widget at the end and see if that is the invalid widget it complains about
+      # this will break if they ever start from the back or return errors for everything that is invalid
+      #
+      # we do not need to worry about unresolved ids because:
+      # - alert_graph widgets allows kennel style ids
+      # - slo widgets allow kennel style ids
+      # - uptime widgets allow kennel style ids
+      def validate(api)
+        json = @item.expected.as_json
+        json = Marshal.load(Marshal.dump(json))
+
+        # add a semi-valid (does not fail immediately on missing definition) widget still blocks the request
+        placeholder = "invalid_metric_do_not_update"
+        json.fetch(:widgets) << {
+          definition: {
+            type: "timeseries", requests: [{
+              response_format: "timeseries",
+              queries: [{ data_source: "metrics", name: "restarts", query: placeholder }]
+            }]
+          },
+          layout: { x: 0, y: 0, height: 0, width: 0 } # needed for `layout_type: free` and valid for all
+        }
+
+        begin
+          if @item.class::TYPE == :update
+            api.update("dashboard", @item.actual.fetch(:id), json)
+          else
+            api.create("dashboard", json)
+          end
+          raise "Dashboard validation should have failed, live dashboard was update/created by accident"
+        rescue StandardError => e
+          # parse the JSON in the error message and see if there is anything except our error
+          raise "Unreadable error format: #{e.message}" unless (json = e.message[/^\{"errors":.*}$/m])
+          data =
+            begin
+              JSON.parse(json)
+            rescue JSON::ParserError
+              raise "Unreadable error format: #{json}"
+            end
+          raise "Unreadable error format: #{data}" unless (errors = data["errors"]) # uncovered
+          return if errors.size == 1 && errors.all? { |m| m.include?("unable to parse #{placeholder}") }
+          "#{@item.tracking_id}: #{e.message}"
+        end
+      end
+    end
+
+    VALIDATORS = {
+      "monitor" => MonitorValidator,
+      "dashboard" => DashboardValidator
+    }.freeze
+
+    def self.validate(plan)
+      changes = (plan.creates + plan.updates)
+
+      validators = changes.filter_map do |item|
+        next unless (validator = VALIDATORS[item.api_resource]&.new(item))
+
+        if item.class::TYPE == :update
+          # ignore if nothing can break
+          modified_fields = item.diff.map { |_, f, *| f }
+          next nil if modified_fields.all? { |f| validator.class::COSMETIC_FIELDS.include?(f) }
+        end
+
+        validator
+      end
+
+      api = Kennel::Api.new
+      errors = validators.filter_map { |v| v.validate(api) }
+      return if errors.empty?
+
+      abort "#{Kennel::Console.color(:red, "#{errors.size} validation(s) failed:")}\n#{errors.join("\n")}"
+    end
+  end
+end
+
+namespace :kennel do
+  desc "Validate planned changes against the Datadog API [PROJECT=]"
+  task "validate_plan" => "kennel:environment" do
+    kennel = Kennel::Tasks.kennel
+    kennel.preload
+    Kennel::ValidatePlan.validate(kennel.plan)
+  end
+end

data/lib/kennel/tasks.rb

@@ -5,6 +5,8 @@ require "kennel/unmuted_alerts"
 require "kennel/importer"
 require "json"
 
+Dir.children("#{__dir__}/tasks").each { |f| require_relative "tasks/#{File.basename(f, ".rb")}" }
+
 module Kennel
   module Tasks
     class << self
@@ -25,6 +27,7 @@ module Kennel
           source = ".env"
 
           # warn when users have things like DATADOG_TOKEN already set and it will not be loaded from .env
+          # (KENNEL_SILENCE_UPDATED_ENV is intentionally not documented - users see it when needed)
           unless ENV["KENNEL_SILENCE_UPDATED_ENV"]
             updated = Dotenv.parse(source).select { |k, v| ENV[k] && ENV[k] != v }
             warn "Environment variables #{updated.keys.join(", ")} need to be unset to be sourced from #{source}" if updated.any?
@@ -48,7 +51,11 @@ module Kennel
 
       def on_default_branch?
         branch = (ENV["TRAVIS_BRANCH"] || ENV["GITHUB_REF"]).to_s.sub(/^refs\/heads\//, "")
-        (branch == (ENV["DEFAULT_BRANCH"] || "master"))
+        if (default = ENV["DEFAULT_BRANCH"])
+          branch == default
+        else
+          ["main", "master"].include?(branch)
+        end
       end
 
       def git_push?
@@ -66,38 +73,7 @@ namespace :kennel do
     Kennel::Tasks.abort "Error during diffing" unless $CHILD_STATUS.success?
   end
 
-  # ideally do this on every run, but it's slow (~1.5s) and brittle (might not find all + might find false-positives)
-  # https://help.datadoghq.com/hc/en-us/requests/254114 for automatic validation
-  desc "Verify that all used monitor  mentions are valid"
-  task validate_mentions: :environment do
-    known = Kennel::Api.new
-      .send(:request, :get, "/monitor/notifications")
-      .fetch(:handles)
-      .values
-      .flatten(1)
-      .map { |v| v.fetch(:value) }
-
-    known += ENV["KNOWN"].to_s.split(",")
-
-    bad = []
-    Dir["generated/**/*.json"].each do |f|
-      next unless (message = JSON.parse(File.read(f))["message"])
-      used = message
-        .scan(/(?:^|\s)(@[^\s{,'"]+)/)
-        .flatten(1)
-        .grep(/^@.*@|^@.*-/) # ignore @here etc handles ... datadog uses @foo@bar.com for emails and @foo-bar for integrations
-      (used - known).each { |v| bad << [f, v] }
-    end
-
-    if bad.any?
-      url = Kennel::Utils.path_to_url "/account/settings"
-      Kennel.err.puts "Invalid mentions found, either ignore them by adding to `KNOWN` env var or add them via #{url}"
-      bad.each { |f, v| Kennel.err.puts "Invalid mention #{v} in monitor message of #{f}" }
-      Kennel::Tasks.abort ENV["KNOWN_WARNING"]
-    end
-  end
-
-  desc "generate local definitions"
+  desc "store definitions in generated/"
   task generate: :environment do
     Kennel::Tasks.kennel.generate
   end
@@ -129,132 +105,6 @@ namespace :kennel do
     Kennel::UnmutedAlerts.print(Kennel::Api.new, tag)
   end
 
-  desc "show monitors with no data by TAG, for example TAG=team:foo [THRESHOLD_DAYS=7] [FORMAT=json]"
-  task nodata: :environment do
-    tag = ENV["TAG"] || Kennel::Tasks.abort("Call with TAG=foo:bar")
-    monitors = Kennel::Api.new.list("monitor", monitor_tags: tag, group_states: "no data")
-    monitors.select! { |m| m[:overall_state] == "No Data" }
-    monitors.reject! { |m| m[:tags].include? "nodata:ignore" }
-    if monitors.any?
-      Kennel.err.puts <<~TEXT
-        To ignore monitors with expected nodata, tag it with "nodata:ignore"
-
-      TEXT
-    end
-
-    now = Time.now
-    monitors.each do |m|
-      m[:days_in_no_data] =
-        if m[:overall_state_modified]
-          since = Date.parse(m[:overall_state_modified]).to_time
-          ((now - since) / (24 * 60 * 60)).to_i
-        else
-          999
-        end
-    end
-
-    if (threshold = ENV["THRESHOLD_DAYS"])
-      monitors.select! { |m| m[:days_in_no_data] > Integer(threshold) }
-    end
-
-    monitors.each { |m| m[:url] = Kennel::Utils.path_to_url("/monitors/#{m[:id]}") }
-
-    if ENV["FORMAT"] == "json"
-      report = monitors.map do |m|
-        match = m[:message].to_s.match(/-- #{Regexp.escape(Kennel::Models::Record::MARKER_TEXT)} (\S+:\S+) in (\S+), /) || []
-        m.slice(:url, :name, :tags, :days_in_no_data).merge(
-          kennel_tracking_id: match[1],
-          kennel_source: match[2]
-        )
-      end
-
-      Kennel.out.puts JSON.pretty_generate(report)
-    else
-      monitors.each do |m|
-        Kennel.out.puts m[:name]
-        Kennel.out.puts Kennel::Utils.path_to_url("/monitors/#{m[:id]}")
-        Kennel.out.puts "No data since #{m[:days_in_no_data]}d"
-        Kennel.out.puts
-      end
-    end
-  end
-
-  desc "Convert existing resources to copy-pasteable definitions to import existing resources (call with URL= or call with RESOURCE= and ID=)"
-  task import: :environment do
-    if (id = ENV["ID"]) && (resource = ENV["RESOURCE"])
-      id = Integer(id) if id =~ /^\d+$/ # dashboards can have alphanumeric ids
-    elsif (url = ENV["URL"])
-      resource, id = Kennel::Models::Record.parse_any_url(url) || Kennel::Tasks.abort("Unable to parse url")
-    else
-      possible_resources = Kennel::Models::Record.subclasses.map(&:api_resource)
-      Kennel::Tasks.abort("Call with URL= or call with RESOURCE=#{possible_resources.join(" or ")} and ID=")
-    end
-
-    Kennel.out.puts Kennel::Importer.new(Kennel::Api.new).import(resource, id)
-  end
-
-  desc "Dump ALL of datadog config as raw json ... useful for grep/search [TYPE=slo|monitor|dashboard]"
-  task dump: :environment do
-    resources =
-      if (type = ENV["TYPE"])
-        [type]
-      else
-        Kennel::Models::Record.api_resource_map.keys
-      end
-    api = Kennel::Api.new
-    list = nil
-    first = true
-
-    Kennel.out.puts "["
-    resources.each do |resource|
-      Kennel::Progress.progress("Downloading #{resource}") do
-        list = api.list(resource)
-        api.fill_details!(resource, list) if resource == "dashboard"
-      end
-      list.each do |r|
-        r[:api_resource] = resource
-        if first
-          first = false
-        else
-          Kennel.out.puts ","
-        end
-        Kennel.out.print JSON.pretty_generate(r)
-      end
-    end
-    Kennel.out.puts "\n]"
-  end
-
-  desc "Find items from dump by pattern DUMP= PATTERN= [URLS=true]"
-  task dump_grep: :environment do
-    file = ENV.fetch("DUMP")
-    pattern = Regexp.new ENV.fetch("PATTERN")
-    items = File.read(file)[2..-2].gsub("},\n{", "}--SPLIT--{").split("--SPLIT--")
-    models = Kennel::Models::Record.api_resource_map
-    found = items.grep(pattern)
-    exit 1 if found.empty?
-    found.each do |resource|
-      if ENV["URLS"]
-        parsed = JSON.parse(resource)
-        url = models[parsed.fetch("api_resource")].url(parsed.fetch("id"))
-        title = parsed["title"] || parsed["name"]
-        Kennel.out.puts "#{url} # #{title}"
-      else
-        Kennel.out.puts resource
-      end
-    end
-  end
-
-  desc "Resolve given id to kennel tracking-id RESOURCE= ID="
-  task tracking_id: "kennel:environment" do
-    resource = ENV.fetch("RESOURCE")
-    id = ENV.fetch("ID")
-    klass =
-      Kennel::Models::Record.subclasses.detect { |s| s.api_resource == resource } ||
-      raise("resource #{resource} not know")
-    object = Kennel::Api.new.show(resource, id)
-    Kennel.out.puts klass.parse_tracking_id(object)
-  end
-
   task :environment do
     Kennel::Tasks.load_environment
   end

data/lib/kennel/utils.rb

@@ -24,13 +24,14 @@ module Kennel
         workers = Array.new(threads).map do
           Thread.new do
             loop do
-              item, i = work.pop
+              item, i = work.shift
               break unless i
               done[i] =
                 begin
                   yield item
                 rescue Exception => e # rubocop:disable Lint/RescueException
-                  work.clear
+                  work.clear # prevent new work
+                  (workers - [Thread.current]).each(&:kill) # stop ongoing work
                   e
                 end
             end

data/lib/kennel/version.rb

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

data/lib/kennel.rb

@@ -56,7 +56,7 @@ module Kennel
   self.err = $stderr
 
   class Engine
-    attr_accessor :strict_imports
+    attr_accessor :strict_imports # TODO: rename to :enforce_expected_ids_exist
 
     def initialize
       @strict_imports = true
@@ -69,7 +69,9 @@ module Kennel
 
     def generate
       parts = generated
-      PartsSerializer.new(filter: filter).write(parts) if ENV["STORE"] != "false" # quicker when debugging
+      if ENV["STORE"] != "false" # quicker when debugging
+        PartsSerializer.new(filter: filter).write(parts)
+      end
       parts
     end
 
@@ -93,7 +95,9 @@ module Kennel
       @syncer ||= begin
         preload
         Syncer.new(
-          api, generated, definitions,
+          api,
+          expected: generated,
+          actual: definitions,
           filter: filter,
           strict_imports: strict_imports
         )
@@ -107,8 +111,7 @@ module Kennel
     def generated(**kwargs)
       @generated ||= begin
         projects = Progress.progress "Loading projects", **kwargs do
-          projects = ProjectsProvider.new(filter: filter).projects
-          filter.filter_projects projects
+          ProjectsProvider.new(filter: filter).projects
         end
 
         parts = Progress.progress "Finding parts", **kwargs do
@@ -129,7 +132,7 @@ module Kennel
       end
     end
 
-    # performance: this takes ~100ms on large codebases, tried rewriting with Set or Hash but it was slower
+    # performance: this takes ~100ms on large codebases, tried rewriting with Set or Hash, but it was slower
     def validate_unique_tracking_ids(parts)
       bad = parts.group_by(&:tracking_id).select { |_, same| same.size > 1 }
       return if bad.empty?
@@ -143,7 +146,10 @@ module Kennel
     def definitions(**kwargs)
       @definitions ||= Progress.progress("Downloading definitions", **kwargs) do
         Utils.parallel(Models::Record.subclasses) do |klass|
-          api.list(klass.api_resource, with_downtimes: false) # lookup monitors without adding unnecessary downtime information
+          # lookup monitors without adding unnecessary downtime information
+          params = (klass.api_resource == "monitor" ? { with_downtimes: false } : {})
+
+          api.list(klass.api_resource, params)
         end.flatten(1)
       end
     end