dogtrainer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b195d6ba08f5c8305b7bed4f4aaac84f24e678e
+  data.tar.gz: 75d793bc0c14824a1c52b8155684a9cb5ab9b3e1
+SHA512:
+  metadata.gz: 1ded76cc831e7c7d291db142fc5233362ce5d42afb05e05c448422eba521d122541c64d797fd6920175bc5ef54711e1fc5f7207d6b5825473a7f150026f1d9af
+  data.tar.gz: d42b5f8d2e501e06f7d40eb297316d85cd295c80a8a89098aff268484d5d6a12e85374123200bf40760575c2a1439a33b3147c62a51a721c4c2aa21dc1a387d3

data/.gitignore

@@ -0,0 +1,37 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/results/
+/vendor/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rubocop.yml

@@ -0,0 +1,27 @@
+#Lint/UselessAssignment:
+#  Exclude:
+#    - 'lib/dogtrainer/api.rb'
+#    - 'spec/unit/api_spec.rb'
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Style/AccessorMethodName:
+  Exclude:
+    - 'lib/dogtrainer/api.rb'
+
+Style/PreferredHashMethods:
+  Exclude:
+    - 'lib/dogtrainer/api.rb'

data/ChangeLog.md

@@ -0,0 +1,3 @@
+Version 0.0.1
+
+  - initial release

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/Guardfile

@@ -0,0 +1,19 @@
+guard :bundler do
+  watch('dogtrainer.gemspec')
+end
+
+guard :rubocop do
+  watch(/.+\.rb$/)
+  watch(%r{(?:.+\/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch('spec/spec_helper.rb') { 'spec' }
+  watch(%r{^spec/.+_spec\.rb})
+  watch(%r{^spec/(.+)/.+_spec\.rb})
+  watch(%r{^lib\/dogtrainer/(.+)\.rb$}) { |m| "spec/unit/#{m[1]}_spec.rb" }
+end
+
+guard 'yard', port: '8808' do
+  watch(/README\.md/)
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Manheim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# dogtrainer
+
+Build of master branch: [![CircleCI](https://circleci.com/gh/manheim/dogtrainer.svg?style=svg)](https://circleci.com/gh/manheim/dogtrainer)
+
+Documentation: [http://www.rubydoc.info/gems/dogtrainer/](http://www.rubydoc.info/gems/dogtrainer/)
+
+Wrapper around DataDog dogapi gem to simplify creation and management of Monitors and Boards.
+
+This class provides methods to manage (upsert / ensure the existence and configuration of) DataDog
+Monitors and TimeBoards/ScreenBoards.
+
+## Installation
+
+To use the helper class, add ``dogtrainer`` as a runtime dependency for your project.
+
+Using the best-practice of declaring all of your dependencies in your ``gemspec``:
+
+``Gemfile``:
+
+```
+source 'https://rubygems.org'
+gemspec
+```
+
+And add in your ``.gemspec``:
+
+```
+gem.add_runtime_dependency 'dogtrainer'
+```
+
+## Usage
+
+To use the DataDog helper, require the module and create an instance of the class,
+passing it the required configuration information.
+
+```ruby
+require 'dogtrainer'
+
+dog = DogTrainer::API.new(api_key, app_key, notify_to)
+```
+
+or
+
+```ruby
+require 'dogtrainer'
+
+dog = DogTrainer::API.new(api_key, app_key, notify_to, 'string describing where to update monitors or boards')
+```
+
+* __api_key__ is your DataDog API Key, which you can find at https://app.datadoghq.com/account/settings#api
+* __app_key__ is an application-specific key, which should be generated separately for every app or
+  service that uses this class. These can be generated and seen at https://app.datadoghq.com/account/settings#api
+* __notify_to__ is the string specifying DataDog monitor recipients in "@" form. If you are only managing Timeboards or
+  Screenboards (not Monitors), this can be ``nil``.
+* __repo_path__ is a string that will be included in all Monitor notification messages and TimeBoard/ScreenBoard descriptions,
+  telling users where to find the code that created the DataDog resource. This is intended to alert users to code-managed
+  items that shouldn't be manually changed. If this parameter is not specified, it will be obtained from the first usable
+  and present value of: the ``GIT_URL`` environment variable, the ``CIRCLE_REPOSITORY_URL`` or the first remote URL found
+  by running ``git config --local -l`` in the directory that contains the code calling this constructor.
+
+### Usage Examples
+
+These examples all rely on the ``require`` and class instantiation above.
+
+#### Monitors
+
+Event alert on sparse data (lack of data should not trigger an alert):
+
+```ruby
+# alert if more than 130 EC2 RunInstances API call Events in the last hour;
+# do not alert if there is no data.
+id = dog.upsert_monitor(
+  "AWS Suspicious Activity - EC2 RunInstances in the past hour",
+  "events('sources:cloudtrail priority:all tags:runinstances').rollup('count').last('1h') > 130",
+  130,
+  '<=',
+  alert_no_data: false,
+  mon_type: 'event alert'
+)
+puts "RunInstances monitor id: #{id}"
+```
+
+Metric alert, ignoring sparse data:
+
+```ruby
+# alert if aws.ec2.host_ok metric is > 2000 in the last hour, ignoring sparse data
+id = dog.upsert_monitor(
+  "AWS Suspicious Activity - Average Running (OK) EC2 Instances in the past hour",
+  "avg(last_1h):sum:aws.ec2.host_ok{*} > 2000",
+  2000,
+  '<=',
+  alert_no_data: false,
+  mon_type: 'metric alert'
+)
+puts "aws.ec2.host_ok monitor id: #{id}"
+```
+
+Metric alert, also alerting on missing data:
+
+```ruby
+# alert if 'MY_ASG_NAME' ASG in service instances < 2
+dog.upsert_monitor(
+  "ASG In-Service Instances",
+  "avg(last_5m):sum:aws.autoscaling.group_in_service_instances{autoscaling_group:MY_ASG_NAME} < 2",
+  2,
+  '>='
+)
+```
+
+#### Boards
+
+Create a TimeBoard with a handful of graphs about the "MY_ELB_NAME" ELB,
+"MY_ASG_NAME" ASG and instances tagged with a Name of "MY_INSTANCE":
+
+```ruby
+asg_name = "MY_ASG_NAME"
+elb_name = "MY_ELB_NAME"
+instance_name = "MY_INSTANCE"
+
+# generate graph definitions
+graphs = [
+  dog.graphdef(
+    "ASG In-Service Instances",
+    [
+      "sum:aws.autoscaling.group_in_service_instances{autoscaling_group:#{asg_name}}",
+      "sum:aws.autoscaling.group_desired_capacity{autoscaling_group:#{asg_name}}"
+    ]
+  ),
+  dog.graphdef(
+    "ELB Healthy Hosts Sum",
+    "sum:aws.elb.healthy_host_count_deduped{host:#{elb_name}}",
+    {'Desired' => 2}  # this is a Marker, a static line on the graph at y=2
+  ),
+  dog.graphdef(
+    "ELB Latency",
+    [
+      "avg:aws.elb.latency{host:#{elb_name}}",
+      "max:aws.elb.latency{host:#{elb_name}}"
+    ]
+  ),
+  # Instance CPU Utilization from DataDog/EC2 integration
+  dog.graphdef(
+    "Instance EC2 CPU Utilization",
+    "avg:aws.ec2.cpuutilization{name:#{instance_name}}"
+  ),
+  # Instance Free Memory from DataDog Agent on instance
+  dog.graphdef(
+    "Instance Free Memory",
+    "avg:system.mem.free{name:#{instance_name}}"
+  ),
+]
+
+# upsert the TimeBoard
+dog.upsert_timeboard("My Account-Unique Board Name", graphs)
+```
+
+## Development
+
+1. ``bundle install --path vendor``
+2. ``bundle exec rake pre_commit`` to ensure spec tests are passing and style is valid before making your changes
+3. make your changes, and write spec tests for them. You can run ``bundle exec guard`` to continually run spec tests and rubocop when files change.
+4. ``bundle exec rake pre_commit`` to confirm your tests pass and your style is valid. You should confirm 100% coverage. If you wish, you can run ``bundle exec guard`` to dynamically run rspec, rubocop and YARD when relevant files change.
+5. Update ``ChangeLog.md`` for your changes.
+6. Run ``bundle exec rake yard:serve`` to generate documentation for your Gem and serve it live at [http://localhost:8808](http://localhost:8808), and ensure it looks correct.
+7. Open a pull request for your changes.
+8. When shipped, merge the PR. CircleCI will test.
+9. Deployment is done locally, with ``bundle exec rake release``.
+
+When running inside CircleCI, rspec will place reports and artifacts under the right locations for CircleCI to archive them. When running outside of CircleCI, coverage reports will be written to ``coverage/`` and test reports (HTML and JUnit XML) will be written to ``results/``.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'bundler'
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rake/clean'
+require 'yard'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+CLOBBER.include 'pkg'
+
+desc 'Run RuboCop on the lib directory'
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.fail_on_error = true
+end
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ['--require', 'spec_helper']
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+namespace :yard do
+  YARD::Rake::YardocTask.new do |t|
+    t.name = 'generate'
+    t.files   = ['lib/**/*.rb'] # optional
+    t.options = ['--private', '--protected'] # optional
+    t.stats_options = ['--list-undoc'] # optional
+  end
+
+  desc 'serve YARD documentation on port 8808 (restart to regenerate)'
+  task serve: [:generate] do
+    puts 'Running YARD server on port 8808'
+    puts 'Use Ctrl+C to exit server.'
+    YARD::CLI::Server.run
+  end
+end
+
+desc 'Run specs and rubocop before pushing'
+task pre_commit: [:spec, :rubocop]
+
+desc 'Display the list of available rake tasks'
+task :help do
+  system('rake -T')
+end
+
+task default: [:help]

data/circle.yml

@@ -0,0 +1,22 @@
+
+dependencies:
+  cache_directories:
+    - "~/.rvm/gems"
+  pre:
+    - sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install git
+  override:
+    - 'bundle install'
+    - 'rvm 2.0.0-p598 exec bundle install'
+    - 'rvm 2.1.8 exec bundle install'
+    - 'rvm 2.2.5 exec bundle install'
+    - 'rvm 2.3.1 exec bundle install'
+
+test:
+  override:
+    - 'bundle exec rake spec'
+    - 'bundle exec rake rubocop'
+    - 'rvm 2.0.0-p598 exec bundle exec rake spec'
+    - 'rvm 2.1.8 exec bundle exec rake spec'
+    - 'rvm 2.2.5 exec bundle exec rake spec'
+    - 'rvm 2.3.1 exec bundle exec rake spec'
+    - 'bundle exec rake yard:generate'

data/dogtrainer.gemspec

@@ -0,0 +1,59 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/dogtrainer/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors     = ['jantman']
+  gem.email       = ['jason@jasonantman.com']
+  gem.summary     = 'Wrapper around DataDog dogapi gem to simplify creation ' \
+    'and management of Monitors and Boards'
+  gem.description = [
+    'Provides a slightly opinionated wrapper class around DataDog\'s dogapi to',
+    ' simplify the creation and updating of Monitors, TimeBoards and',
+    'ScreenBoards.'
+  ].join(' ')
+  gem.homepage    = 'http://github.com/Manheim/dogtrainer'
+  gem.license     = 'MIT'
+
+  gem.add_runtime_dependency 'dogapi'
+  gem.add_runtime_dependency 'log4r', '>= 1.0'
+
+  # awful, but these are to allow use with ruby 2.1.x
+  gem.add_development_dependency 'ruby_dep', '1.3.1'
+  gem.add_development_dependency 'listen', '3.0.7'
+
+  # guard-yard uses Pry which needs readline. If we're in RVM, we'll need this:
+  gem.add_development_dependency 'rb-readline', '~> 0.5'
+
+  gem.add_development_dependency 'bundler'
+  gem.add_development_dependency 'cri', '~> 2'
+  gem.add_development_dependency 'diplomat', '~> 0.15'
+  gem.add_development_dependency 'faraday', '~> 0.9'
+  gem.add_development_dependency 'ghpages_deploy', '~> 1.3'
+  gem.add_development_dependency 'git', '~> 1.2', '>= 1.2.9.1'
+  gem.add_development_dependency 'guard', '~> 2.13'
+  gem.add_development_dependency 'guard-bundler', '~> 2.1'
+  gem.add_development_dependency 'guard-rspec', '~> 4.6.4'
+  gem.add_development_dependency 'guard-rubocop', '~> 1.2'
+  gem.add_development_dependency 'guard-yard', '~> 2.1'
+  gem.add_development_dependency 'json', '~> 1.8.3'
+  gem.add_development_dependency 'rake', '~> 10'
+  gem.add_development_dependency 'retries', '~> 0.0.5'
+  gem.add_development_dependency 'rspec', '~> 3'
+  gem.add_development_dependency 'rspec_junit_formatter', '~> 0.2'
+  gem.add_development_dependency 'rubocop', '~> 0.37'
+  gem.add_development_dependency 'simplecov', '~> 0.11'
+  gem.add_development_dependency 'simplecov-console'
+  gem.add_development_dependency 'yard', '~> 0.8'
+
+  # ensure gem will only push to our Artifactory
+  # this requires rubygems >= 2.2.0
+  gem.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  gem.files         = `git ls-files`.split($ORS)
+                                    .reject { |f| f =~ %r{^samples\/} }
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = 'dogtrainer'
+  gem.require_paths = ['lib']
+  gem.version       = DogTrainer::VERSION
+end

data/lib/dogtrainer.rb

@@ -0,0 +1,6 @@
+# define top level of module in the right file
+module DogTrainer
+end
+
+gem_libs_dir = "#{File.dirname File.absolute_path(__FILE__)}/dogtrainer"
+Dir.glob("#{gem_libs_dir}/*.rb") { |file| require file }

data/lib/dogtrainer/api.rb

@@ -0,0 +1,437 @@
+require 'dogapi'
+require 'dogapi/v1'
+require 'dogtrainer/logging'
+
+module DogTrainer
+  # Helper methods to upsert/ensure existence and configuration of DataDog
+  # Monitors, TimeBoards and ScreenBoards.
+  class API
+    include DogTrainer::Logging
+
+    # Initialize class; set instance configuration.
+    #
+    # @param api_key [String] DataDog API Key
+    # @param app_key [String] DataDog Application Key
+    # @param notify_to [String] DataDog notification recpipent string for
+    #   monitors. This is generally one or more @-prefixed DataDog users or
+    #   notification recipients. It can be set to nil if you are only managing
+    #   screenboards and timeboards. For further information, see:
+    #   http://docs.datadoghq.com/monitoring/#notifications
+    # @param repo_path [String] Git or HTTP URL to the repository containing
+    #   code that calls this class. Will be added to notification messages so
+    #   that humans know where to make changes to monitors. If nil, the return
+    #   value of #get_repo_path
+    def initialize(api_key, app_key, notify_to, repo_path = nil)
+      logger.debug 'initializing DataDog API client'
+      @dog = Dogapi::Client.new(api_key, app_key)
+      @monitors = nil
+      @timeboards = nil
+      @screenboards = nil
+      @notify_to = notify_to
+      if repo_path.nil?
+        @repo_path = get_repo_path
+        logger.debug "using repo_path: #{@repo_path}"
+      else
+        @repo_path = repo_path
+      end
+    end
+
+    # Return a human-usable string identifying where to make changes to the
+    # resources created by this class. Returns the first of:
+    #
+    # 1. ``GIT_URL`` environment variable, if set and not empty
+    # 2. ``CIRCLE_REPOSITORY_URL`` environment variable, if set and not empty
+    # 3. If the code calling this class is part of a git repository on disk and
+    #    ``git`` is present on the system and in PATH, the URL of the first
+    #    remote for the repository.
+    #
+    # If none of these are found, an error will be raised.
+    def get_repo_path
+      %w(GIT_URL CIRCLE_REPOSITORY_URL).each do |vname|
+        return ENV[vname] if ENV.has_key?(vname) && !ENV[vname].empty?
+      end
+      # try to find git repository
+      # get the path to the calling code;
+      #   caller[0] is #initialize, caller[1] is what instantiated the class
+      path, = caller[1].partition(':')
+      repo_path = get_git_url_for_directory(File.dirname(path))
+      if repo_path.nil?
+        raise 'Unable to determine source code path; please ' \
+        'specify repo_path option to DogTrainer::API'
+      end
+      repo_path
+    end
+
+    # Given the path to a directory on disk that may be a git repository,
+    # return the URL to its first remote, or nil otherwise.
+    #
+    # @param dir_path [String] Path to possible git repository
+    def get_git_url_for_directory(dir_path)
+      logger.debug "trying to find git remote for: #{dir_path}"
+      conf = nil
+      Dir.chdir(dir_path) do
+        begin
+          conf = `git config --local -l`
+        rescue
+          conf = nil
+        end
+      end
+      return nil if conf.nil?
+      conf.split("\n").each do |line|
+        return Regexp.last_match(1) if line =~ /^remote\.[^\.]+\.url=(.+)/
+      end
+      nil
+    end
+
+    #########################################
+    # BEGIN monitor-related shared methods. #
+    #########################################
+
+    # Given the name of a metric we're monitoring and the comparison method,
+    # generate alert messages for the monitor.
+    #
+    # This method is intended for internal use by the class, but can be
+    # overridden if the implementation is not desired.
+    #
+    # @param metric_desc [String] description/name of the metric being
+    #   monitored.
+    # @param comparison [String] comparison operator or description for metric
+    #   vs threshold; i.e. ">=", "<=", "=", "<", etc.
+    def generate_messages(metric_desc, comparison)
+      message = [
+        "{{#is_alert}}'#{metric_desc}' should be #{comparison} {{threshold}}, ",
+        "but is {{value}}.{{/is_alert}}\n",
+        "{{#is_recovery}}'#{metric_desc}' recovered  (current value {{value}} ",
+        "is #{comparison} threshold of {{threshold}}).{{/is_recovery}}\n",
+        '(monitor and threshold configuration for this alert is managed by ',
+        "#{@repo_path}) #{@notify_to}"
+      ].join('')
+      escalation = "'#{metric_desc}' is still in error state (current value " \
+        "{{value}} is #{comparison} threshold of {{threshold}})"
+      [message, escalation]
+    end
+
+    # Return a hash of parameters for a monitor with the specified
+    # configuration. For further information, see:
+    # http://docs.datadoghq.com/api/#monitors
+    #
+    # @param name [String] name for the monitor; must be unique per DataDog
+    #   account
+    # @param message [String] alert/notification message for the monitor
+    # @param query [String] query for the monitor to evaluate
+    # @param threshold [Float] evaluation threshold for the monitor
+    # @param [Hash] options
+    # @option options [String] :escalation_message optional escalation message
+    #   for escalation notifications. Defaults to nil.
+    # @option options [Boolean] :alert_no_data whether or not to alert on lack
+    #   of data. Defaults to true.
+    # @option options [String] :mon_type type of monitor as defined in DataDog
+    #   API docs. Defaults to 'metric alert'.
+    def params_for_monitor(
+      name,
+      message,
+      query,
+      threshold,
+      options = {
+        escalation_message: nil,
+        alert_no_data: true,
+        mon_type: 'metric alert'
+      }
+    )
+      options[:alert_no_data] = true unless options.key?(:alert_no_data)
+      options[:mon_type] = 'metric alert' unless options.key?(:mon_type)
+      monitor_data = {
+        'name' => name,
+        'type' => options[:mon_type],
+        'query' => query,
+        'message' => message,
+        'tags' => [],
+        'options' => {
+          'notify_audit' => false,
+          'locked' => false,
+          'timeout_h' => 0,
+          'silenced' => {},
+          'thresholds' => { 'critical' => threshold },
+          'require_full_window' => false,
+          'notify_no_data' => options[:alert_no_data],
+          'renotify_interval' => 60,
+          'no_data_timeframe' => 20
+        }
+      }
+      monitor_data['options']['escalation_message'] = \
+        options[:escalation_message] unless options[:escalation_message].nil?
+      monitor_data
+    end
+
+    # Create or update a monitor in DataDog with the given name and data/params.
+    # This method handles either creating the monitor if one with the same name
+    # doesn't already exist in the specified DataDog account, or else updating
+    # an existing monitor with the same name if one exists but the parameters
+    # differ.
+    #
+    # For further information on parameters and options, see:
+    # http://docs.datadoghq.com/api/#monitors
+    #
+    # This method calls #generate_messages to build the notification messages
+    # and #params_for_monitor to generate the parameters.
+    #
+    # @param mon_name [String] name for the monitor; must be unique per DataDog
+    #   account
+    # @param query [String] query for the monitor to evaluate
+    # @param threshold [Float] evaluation threshold for the monitor
+    # @param comparator [String] comparison operator for metric vs threshold,
+    #   describing the inverse of the query. I.e. if the query is checking for
+    #   "< 100", then the comparator would be ">=".
+    # @param [Hash] options
+    # @option options [Boolean] :alert_no_data whether or not to alert on lack
+    #   of data. Defaults to true.
+    # @option options [String] :mon_type type of monitor as defined in DataDog
+    #   API docs. Defaults to 'metric alert'.
+    def upsert_monitor(
+      mon_name,
+      query,
+      threshold,
+      comparator,
+      options = { alert_no_data: true, mon_type: 'metric alert' }
+    )
+      options[:alert_no_data] = true unless options.key?(:alert_no_data)
+      options[:mon_type] = 'metric alert' unless options.key?(:mon_type)
+      message, escalation = generate_messages(mon_name, comparator)
+      mon_params = params_for_monitor(mon_name, message, query, threshold,
+                                      escalation_message: escalation,
+                                      alert_no_data: options[:alert_no_data],
+                                      mon_type: options[:mon_type])
+      logger.info "Upserting monitor: #{mon_name}"
+      monitor = get_existing_monitor_by_name(mon_name)
+      return create_monitor(mon_name, mon_params) if monitor.nil?
+      logger.debug "\tfound existing monitor id=#{monitor['id']}"
+      do_update = false
+      mon_params.each do |k, _v|
+        unless monitor.include?(k)
+          logger.debug "\tneeds update based on missing key: #{k}"
+          do_update = true
+          break
+        end
+        next unless monitor[k] != mon_params[k]
+        logger.debug "\tneeds update based on difference in key #{k}; " \
+          "current='#{monitor[k]}' desired='#{mon_params[k]}'"
+        do_update = true
+        break
+      end
+      unless do_update
+        logger.debug "\tmonitor is correct in DataDog."
+        return monitor['id']
+      end
+      res = @dog.update_monitor(monitor['id'], mon_params['query'], mon_params)
+      if res[0] == '200'
+        logger.info "\tMonitor #{monitor['id']} updated successfully"
+        return monitor['id']
+      else
+        logger.error "\tError updating monitor #{monitor['id']}: #{res}"
+      end
+    end
+
+    # Create a monitor that doesn't already exist; return its id
+    #
+    # @param mon_name [String] mane of the monitor to create
+    # @param mon_params [Hash] params to pass to the DataDog API call. Must
+    #   include "type" and "query" keys.
+    def create_monitor(_mon_name, mon_params)
+      res = @dog.monitor(mon_params['type'], mon_params['query'], mon_params)
+      if res[0] == '200'
+        logger.info "\tMonitor #{res[1]['id']} created successfully"
+        return res[1]['id']
+      else
+        logger.error "\tError creating monitor: #{res}"
+      end
+    end
+
+    # Get all monitors from DataDog; return the one named ``mon_name`` or nil
+    #
+    # This caches all monitors from DataDog in an instance variable.
+    #
+    # @param mon_name [String] name of the monitor to return
+    def get_existing_monitor_by_name(mon_name)
+      if @monitors.nil?
+        @monitors = @dog.get_all_monitors(group_states: 'all')
+        logger.info "Found #{@monitors[1].length} existing monitors in DataDog"
+        if @monitors[1].empty?
+          logger.error 'ERROR: Docker API call returned no existing monitors.' \
+            ' Something is wrong.'
+          exit 1
+        end
+      end
+      @monitors[1].each do |mon|
+        return mon if mon['name'] == mon_name
+      end
+      nil
+    end
+
+    ###########################################
+    # BEGIN dashboard-related shared methods. #
+    ###########################################
+
+    # Create a graph definition (graphdef) to use with Boards APIs. For further
+    # information, see: http://docs.datadoghq.com/graphingjson/
+    #
+    # @param title [String] title of the graph
+    # @param queries [Array or String] a single string graph query, or an
+    #   Array of graph query strings.
+    # @param markers [Hash] a hash of markers to set on the graph, in
+    #   name => value format.
+    def graphdef(title, queries, markers = {})
+      queries = [queries] unless queries.is_a?(Array)
+      d = {
+        'definition' => {
+          'viz' => 'timeseries',
+          'requests' => []
+        },
+        'title' => title
+      }
+      queries.each do |q|
+        d['definition']['requests'] << {
+          'q' => q,
+          'conditional_formats' => [],
+          'type' => 'line'
+        }
+      end
+      unless markers.empty?
+        d['definition']['markers'] = []
+        markers.each do |name, val|
+          d['definition']['markers'] << {
+            'type' => 'error dashed',
+            'val' => val.to_s,
+            'value' => "y = #{val}",
+            'label' => "#{name}==#{val}"
+          }
+        end
+      end
+      d
+    end
+
+    # Create or update a timeboard in DataDog with the given name and
+    # data/params. For further information, see:
+    # http://docs.datadoghq.com/api/#timeboards
+    #
+    # @param dash_name [String] Account-unique dashboard name
+    # @param graphs [Array] Array of graphdefs to add to dashboard
+    def upsert_timeboard(dash_name, graphs)
+      logger.info "Upserting timeboard: #{dash_name}"
+      desc = "created by DogTrainer RubyGem via #{@repo_path}"
+      dash = get_existing_timeboard_by_name(dash_name)
+      if dash.nil?
+        d = @dog.create_dashboard(dash_name, desc, graphs)
+        logger.info "Created timeboard #{d[1]['dash']['id']}"
+        return
+      end
+      logger.debug "\tfound existing timeboard id=#{dash['dash']['id']}"
+      needs_update = false
+      if dash['dash']['description'] != desc
+        logger.debug "\tneeds update of description"
+        needs_update = true
+      end
+      if dash['dash']['title'] != dash_name
+        logger.debug "\tneeds update of title"
+        needs_update = true
+      end
+      if dash['dash']['graphs'] != graphs
+        logger.debug "\tneeds update of graphs"
+        needs_update = true
+      end
+
+      if needs_update
+        logger.info "\tUpdating timeboard #{dash['dash']['id']}"
+        @dog.update_dashboard(
+          dash['dash']['id'], dash_name, desc, graphs
+        )
+        logger.info "\tTimeboard updated."
+      else
+        logger.info "\tTimeboard is up-to-date"
+      end
+    end
+
+    # Create or update a screenboard in DataDog with the given name and
+    # data/params. For further information, see:
+    # http://docs.datadoghq.com/api/screenboards/ and
+    # http://docs.datadoghq.com/api/?lang=ruby#screenboards
+    #
+    # @param dash_name [String] Account-unique dashboard name
+    # @param widgets [Array] Array of Hash widget definitions to pass to
+    #   the DataDog API. For further information, see:
+    #   http://docs.datadoghq.com/api/screenboards/
+    def upsert_screenboard(dash_name, widgets)
+      logger.info "Upserting screenboard: #{dash_name}"
+      desc = "created by DogTrainer RubyGem via #{@repo_path}"
+      dash = get_existing_screenboard_by_name(dash_name)
+      if dash.nil?
+        d = @dog.create_screenboard(board_title: dash_name,
+                                    description: desc,
+                                    widgets: widgets)
+        logger.info "Created screenboard #{d[1]['id']}"
+        return
+      end
+      logger.debug "\tfound existing screenboard id=#{dash['id']}"
+      needs_update = false
+      if dash['description'] != desc
+        logger.debug "\tneeds update of description"
+        needs_update = true
+      end
+      if dash['board_title'] != dash_name
+        logger.debug "\tneeds update of title"
+        needs_update = true
+      end
+      if dash['widgets'] != widgets
+        logger.debug "\tneeds update of widgets"
+        needs_update = true
+      end
+
+      if needs_update
+        logger.info "\tUpdating screenboard #{dash['id']}"
+        @dog.update_screenboard(dash['id'], board_title: dash_name,
+                                            description: desc,
+                                            widgets: widgets)
+        logger.info "\tScreenboard updated."
+      else
+        logger.info "\tScreenboard is up-to-date"
+      end
+    end
+
+    # get all timeboards from DataDog; return the one named ``dash_name`` or nil
+    # returns the timeboard definition hash from the DataDog API
+    def get_existing_timeboard_by_name(dash_name)
+      if @timeboards.nil?
+        @timeboards = @dog.get_dashboards
+        puts "Found #{@timeboards[1]['dashes'].length} existing timeboards " \
+          'in DataDog'
+        if @timeboards[1]['dashes'].empty?
+          puts 'ERROR: Docker API call returned no existing timeboards. ' \
+            'Something is wrong.'
+          exit 1
+        end
+      end
+      @timeboards[1]['dashes'].each do |dash|
+        return @dog.get_dashboard(dash['id'])[1] if dash['title'] == dash_name
+      end
+      nil
+    end
+
+    # get all screenboards from DataDog; return the one named ``dash_name`` or
+    # nil returns the screenboard definition hash from the DataDog API
+    def get_existing_screenboard_by_name(dash_name)
+      if @screenboards.nil?
+        @screenboards = @dog.get_all_screenboards
+        puts "Found #{@screenboards[1]['screenboards'].length} existing " \
+          'screenboards in DataDog'
+        if @screenboards[1]['screenboards'].empty?
+          puts 'ERROR: Docker API call returned no existing screenboards. ' \
+            'Something is wrong.'
+          exit 1
+        end
+      end
+      @screenboards[1]['screenboards'].each do |dash|
+        return @dog.get_screenboard(dash['id'])[1] if dash['title'] == dash_name
+      end
+      nil
+    end
+  end
+end