ncio 0.2.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f4228a74a79a10e47ffce674748ec755eae37ec
-  data.tar.gz: 5c80ffcca70d9ca50174b4f76cf72fed453e3794
+  metadata.gz: 6a605a5b8f5fe218bf929a616865beefdee6e498
+  data.tar.gz: 64f6c604eead3c2f171b4e257aefafd6557284fb
 SHA512:
-  metadata.gz: bc29b5864c421b08faf4609baa7560e2e5e8be82c6210522e82df39338ca7c5e2290ff53f4dd6ee9b34e3e79b4fd5bb1e21a7980f4bd3f347c0723d23727884d
-  data.tar.gz: b31ba443b49e416b5980e9a78996a0c9d8f53b7836c8d7b608f5e3d65b420929999acc34de959e7b92060e0255b05a274f45d389e6faf1ed9c973930ab1b4c80
+  metadata.gz: bda029e4149c95969a8ab4692a955f2d2fd16fbb53d649bbcc95371dc16acf9d7adbf9545308c466aa6a7d1f2566f9f0b1fb8b72cb65f7532cdd13fa28451ba7
+  data.tar.gz: 65f027f5b97bb2b57e5869340ce61b23d40030495b0e79b7d5094bc9682e819eac9572c0fd01c7c71a8088f95296a1858e277e20c9d37eb9051c74d217ca4743

data/README.md

@@ -84,6 +84,33 @@ white-list of certificates is located at
       backup > /var/tmp/backup.json
     I, [2016-06-28T19:28:48.236257 #3148]  INFO -- : Backup completed successfully!
 
+## Logging
+
+The status of backup and restore operations are logged to the syslog by default.
+The `daemon` facility is used to ensure messages are written to files on a wide
+variety of systems that log daemon messages by default.  A general exception
+handler will log a backtrace in JSON format to help log processors and
+notification systems like Splunk and Logstash.
+
+Here's an example of a failed restore triggering the catch all handler:
+
+    Jun 29 12:12:21 Jeff-McCune ncio[51474]: ERROR Restoring backup: {
+      "error": "RuntimeError",
+      "message": "Some random error",
+      "backtrace": [
+        "/Users/jeff/projects/puppet/ncio/lib/ncio/app.rb:94:in `restore_groups'",
+        "/Users/jeff/projects/puppet/ncio/lib/ncio/app.rb:59:in `run'",
+        "/Users/jeff/projects/puppet/ncio/exe/ncio:5:in `<top (required)>'"
+      ]
+    }
+
+Log to the console using the `--no-syslog` command line option.
+
+    ncio --no-syslog restore --file backup.json
+
+The tool can only log to either syslog or the console at this time.  Multiple
+log destinations are not currently supported.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/lib/ncio/app.rb

@@ -69,26 +69,42 @@ class App
   # Backup all groups in a manner suitable for the node classification hierarchy
   # import. See:
   # [NC Groups](https://docs.puppet.com/pe/2016.1/nc_groups.html#get-v1groups)
+  # rubocop:disable Metrics/AbcSize
   def backup_groups
-    debug "GET #{uri}/groups"
-    str = JSON.pretty_generate(api.groups)
-    debug "Write #{str.bytesize} bytes to #{file} ..."
+    warn "Starting Node Classification Backup using GET #{uri}/groups"
+    groups = api.groups
+    debug "Number of groups retrieved: #{groups.size}"
+    str = JSON.pretty_generate(groups)
+    debug "Write #{str.bytesize} bytes of JSON to #{file} ..."
     write_output(str, map_file_option(file))
-    info 'Backup completed successfully!'
+    warn 'Finished Node Classification Backup '\
+      "STATUS=OK BYTESIZE=#{str.bytesize} GROUPCOUNT=#{groups.size} "\
+      "OUTPUT=#{file}"
+  rescue Exception => e
+    fatal "ERROR Obtaining backup: #{format_error e}"
+    raise e
   end
+  # rubocop:enable Metrics/AbcSize
 
   ##
   # Restore all groups in a manner suitable for the node classification
   # hierarchy import. See: [NC Import
   # Hierarchy](https://docs.puppet.com/pe/2016.1/nc_import-hierarchy.html)
   def restore_groups
+    raise "Some random error"
+    warn 'Starting Node Classification Restore using '\
+      "POST #{uri}/import-hierarchy"
     api = self.api
     debug "Open #{file} for streaming ..."
     input_stream(map_file_option(file)) do |stream|
       debug "POST #{uri}/import-hierarchy"
       api.import_hierarchy(stream)
     end
-    info 'Successfully restored node classification groups!'
+    warn 'Finished Node Classification Restore '\
+      "STATUS=OK INPUT=#{file}"
+  rescue Exception => e
+    fatal "ERROR Restoring backup: #{format_error e}"
+    raise e
   end
 
   ##

data/lib/ncio/support.rb

@@ -1,3 +1,7 @@
+require 'logger'
+require 'syslog/logger'
+require 'json'
+
 module Ncio
   ##
   # Support module to mix into other classes, particularly the application and
@@ -8,10 +12,26 @@ module Ncio
     attr_reader :opts
 
     def self.reset_logging!(opts)
+      logger = opts[:syslog] ? syslog_logger : stream_logger(opts)
+      @log = logger
+    end
+
+    ##
+    # Return a new Syslog::Logger instance configured for syslog output
+    def self.syslog_logger
+      # Use the daemon facility, matching Puppet behavior.
+      Syslog::Logger.new('ncio', Syslog::LOG_DAEMON)
+    end
+
+    ##
+    # Return a new Logger instance configured for file output
+    def self.stream_logger(opts)
       out = map_file_option(opts[:logto])
       logger = Logger.new(out)
-      logger.level = opts[:debug] ? Logger::DEBUG : Logger::INFO
-      @log = logger
+      logger.level = Logger::WARN
+      logger.level = Logger::INFO if opts[:verbose]
+      logger.level = Logger::DEBUG if opts[:debug]
+      logger
     end
 
     ##
@@ -62,13 +82,37 @@ module Ncio
     end
 
     ##
-    # Log an info message
+    # Logs a message at the fatal (syslog err) log level
+    def fatal(msg)
+      log.fatal msg
+    end
+
+    ##
+    # Logs a message at the error (syslog warning) log level.
+    # i.e. May indicate that an error will occur if action is not taken.
+    # e.g. A non-root file system has only 2GB remaining.
+    def error(msg)
+      log.error msg
+    end
+
+    ##
+    # Logs a message at the warn (syslog notice) log level.
+    # e.g. Events that are unusual, but not error conditions.
+    def warn(msg)
+      log.warn msg
+    end
+
+    ##
+    # Logs a message at the info (syslog info) log level
+    # i.e. Normal operational messages that require no action.
+    # e.g. An application has started, paused or ended successfully.
     def info(msg)
       log.info msg
     end
 
     ##
-    # Log a debug message
+    # Logs a message at the debug (syslog debug) log level
+    # i.e.  Information useful to developers for debugging the application.
     def debug(msg)
       log.debug msg
     end
@@ -105,6 +149,16 @@ module Ncio
       end
     end
 
+    ##
+    # Format an exception for logging.  JSON is used to aid centralized log
+    # systems such as Logstash and Splunk
+    #
+    # @param [Exception] e the exception to format
+    def format_error(e)
+      data = { error: "#{e.class}", message: e.message, backtrace: e.backtrace }
+      JSON.pretty_generate(data)
+    end
+
     ##
     # Return the application version as a Semantic Version encoded string
     #

data/lib/ncio/support/option_parsing.rb

@@ -1,4 +1,6 @@
 require 'ncio/version'
+require 'socket'
+
 # rubocop:disable Metrics/ModuleLength
 module Ncio
   module Support
@@ -70,7 +72,9 @@ module Ncio
           log_msg = 'Log file to write to or keywords '\
             'STDOUT, STDERR {NCIO_LOGTO}'
           opt :logto, log_msg, default: env['NCIO_LOGTO'] || 'STDERR'
-          opt :debug
+          opt :syslog, 'Log to syslog', default: true, conflicts: :logto
+          opt :verbose, 'Set log level to INFO'
+          opt :debug, 'Set log level to DEBUG'
         end
       end
       # rubocop:enable Metrics/MethodLength, Metrics/AbcSize

data/lib/ncio/version.rb

@@ -1,3 +1,3 @@
 module Ncio
-  VERSION = '0.2.2'.freeze
+  VERSION = '1.0.0'.freeze
 end

data/ncio.gemspec

@@ -9,8 +9,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jeff McCune"]
   spec.email         = ["jeff@openinfrastructure.co"]
 
-  spec.summary       = %q{Puppet Node Classifier Import / Export}
-  spec.description   = %q{Puppet Node Classifier Import / Export}
+  spec.summary       = 'Puppet Node Classifier backup / restore / transform'
+  spec.description   = 'ncio is a small command line utility to backup, '\
+    'restore, and transform Puppet Enterprise Node Classification groups.'
   spec.homepage      = "https://www.openinfrastructure.co"
   spec.license       = "MIT"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ncio
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Jeff McCune
@@ -122,7 +122,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.11.2
-description: Puppet Node Classifier Import / Export
+description: ncio is a small command line utility to backup, restore, and transform
+  Puppet Enterprise Node Classification groups.
 email:
 - jeff@openinfrastructure.co
 executables:
@@ -176,6 +177,6 @@ rubyforge_project:
 rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
-summary: Puppet Node Classifier Import / Export
+summary: Puppet Node Classifier backup / restore / transform
 test_files: []
 has_rdoc: yard