bolt 0.20.6 → 0.20.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ecd8364f409304d8286adae0544a3f2b34038403
-  data.tar.gz: e13c9abe1b098794394947baec4da9d349a922fe
+  metadata.gz: d1a5c8ec4cf105ece549f43ed95bcaed30df97d8
+  data.tar.gz: 0b28cbab7855f68ef4ab9c797bf596e3313becf7
 SHA512:
-  metadata.gz: d98430251616d064eb98830532ce8c7de35c4f60b7b55768b9d82a9fbbb9c183363888da3e98d2d915df9637ff488893a495f6a5fe0a6254ed329ecfa2077908
-  data.tar.gz: 99827f1b25b5b83849c9900551168f3377b2f3b99da600c32f9284173247988c6fbf550ac737f81875d32ea78cf2885d2b9395879e314f6d64d4eb53ae2ff835
+  metadata.gz: 467977c61d4c83051978526cba46de367c0626dd4b3a11cb7030faeebd914b8094a66552537a4637c4fdbce2346c571f319a38be69fa29b8d3dadaed14fe14bb
+  data.tar.gz: 00834ae333d3d0cb4cd3e5b67c22f53811fe6c4c2d89de1a20e72bd749db697140511045a405f3f0e2320aa8338c238dff7c4bf3fb3adf9c3401048a8ae7f539

data/bolt-modules/boltlib/lib/puppet/functions/add_facts.rb

@@ -2,12 +2,17 @@
 
 require 'bolt/error'
 
-# Deep merges a hash of facts with the existing facts has on a target.
-
+# Deep merges a hash of facts with the existing facts on a target.
 Puppet::Functions.create_function(:add_facts) do
+  # @param target A target.
+  # @param facts A hash of fact names to values that my include structured facts.
+  # @return The target's new facts.
+  # @example Adding facts to a target
+  #   add_facts($target, { 'os' => { 'family' => 'windows', 'name' => 'windows' } })
   dispatch :add_facts do
     param 'Target', :target
     param 'Hash', :facts
+    return_type 'Hash[String, Data]'
   end
 
   def add_facts(target, facts)
@@ -25,6 +30,9 @@ Puppet::Functions.create_function(:add_facts) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('add_facts')
+
     inventory.add_facts(target, facts)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/facts.rb

@@ -3,8 +3,11 @@
 require 'bolt/error'
 
 # Returns the facts hash for a target.
-# This functions takes one parameter, the target to get facts for
 Puppet::Functions.create_function(:facts) do
+  # @param target A target.
+  # @return The target's facts.
+  # @example Getting facts
+  #   facts($target)
   dispatch :facts do
     param 'Target', :target
     return_type 'Hash[String, Data]'
@@ -25,6 +28,9 @@ Puppet::Functions.create_function(:facts) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('facts')
+
     inventory.facts(target)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/fail_plan.rb

@@ -7,6 +7,14 @@ require 'bolt/error'
 # Plan authors should call this function when their plan is not successful. The
 # error may then be caught by another plans run_plan function or in bolt itself
 Puppet::Functions.create_function(:fail_plan) do
+  # Fail a plan, generating an exception from the parameters.
+  # @param msg An error message.
+  # @param kind An easily matchable error kind.
+  # @param details Machine-parseable details about the error.
+  # @param issue_code Unused.
+  # @return Raises an exception.
+  # @example Raise an exception
+  #   fail_plan('We goofed up', 'task-unexpected-result', { 'result' => 'null' })
   dispatch :from_args do
     param 'String[1]', :msg
     optional_param 'String[1]', :kind
@@ -14,11 +22,19 @@ Puppet::Functions.create_function(:fail_plan) do
     optional_param 'String[1]', :issue_code
   end
 
+  # Fail a plan, generating an exception from an existing Error object.
+  # @param error An error object.
+  # @return Raises an exception.
+  # @example Raise an exception
+  #   fail_plan(Error('We goofed up', 'task-unexpected-result', { 'result' => 'null' }))
   dispatch :from_error do
     param 'Error', :error
   end
 
   def from_args(msg, kind = nil, details = nil, issue_code = nil)
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('fail_plan')
+
     raise Bolt::PlanFailure.new(msg, kind || 'bolt/plan-failure', details, issue_code)
   end
 

data/bolt-modules/boltlib/lib/puppet/functions/file_upload.rb

@@ -3,13 +3,19 @@
 require 'bolt/error'
 
 # Uploads the given file or directory to the given set of targets and returns the result from each upload.
-#
-# * This function does nothing if the list of targets is empty.
-# * It is possible to run on the target 'localhost'
-# * A target is a String with a targets's hostname or a Target.
-# * The returned value contains information about the result per target.
-#
+# This function does nothing if the list of targets is empty.
 Puppet::Functions.create_function(:file_upload, Puppet::Functions::InternalFunction) do
+  # Upload a file.
+  # @param source A source path, either an absolute path or a modulename/filename selector for a file in
+  #               <moduleroot>/files.
+  # @param destination An absolute path on the target(s).
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options Additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Upload a local file to Linux targets and change owner to 'root'
+  #   file_upload('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, '_run_as' => 'root')
+  # @example Upload a module file to a Windows target
+  #   file_upload('postgres/default.conf', 'C:/ProgramData/postgres/default.conf', $target)
   dispatch :file_upload do
     scope_param
     param 'String[1]', :source
@@ -19,6 +25,16 @@ Puppet::Functions.create_function(:file_upload, Puppet::Functions::InternalFunct
     return_type 'ResultSet'
   end
 
+  # Upload a file, logging the provided description.
+  # @param source A source path, either an absolute path or a modulename/filename selector for a file in
+  #               <moduleroot>/files.
+  # @param destination An absolute path on the target(s).
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options Additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Upload a file
+  #   file_upload('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, 'Uploading payload to unpack')
   dispatch :file_upload_with_description do
     scope_param
     param 'String[1]', :source
@@ -51,6 +67,8 @@ Puppet::Functions.create_function(:file_upload, Puppet::Functions::InternalFunct
       )
     end
 
+    executor.report_function_call('file_upload')
+
     found = Puppet::Parser::Files.find_file(source, scope.compiler.environment)
     unless found && Puppet::FileSystem.exist?(found)
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(

data/bolt-modules/boltlib/lib/puppet/functions/get_targets.rb

@@ -3,20 +3,19 @@
 require 'bolt/error'
 
 # Parses common ways of referring to targets and returns an array of Targets.
-#
-# Accepts input consisting of
-# - a group
-# - a target URI
-# - an array of groups and/or target URIs
-# - a string that consists of a comma-separated list of groups and/or target URIs
-#
-# Examples of the above would be
-# - 'group1'
-# - 'host1,group1,winrm://host2:54321'
-# - ['host1', 'group1', 'winrm://host2:54321']
-#
-# Returns an array of unique Targets resolved from any target URIs and groups.
 Puppet::Functions.create_function(:get_targets) do
+  # @param names A pattern or array of patterns identifying a set of targets.
+  # @return A list of unique Targets resolved from any target URIs and groups.
+  # @example Resolve a group
+  #   get_targets('group1')
+  # @example Resolve a target URI
+  #   get_targets('winrm://host2:54321')
+  # @example Resolve array of groups and/or target URIs
+  #   get_targets(['host1', 'group1', 'winrm://host2:54321'])
+  # @example Resolve string consisting of a comma-separated list of groups and/or target URIs
+  #   get_targets('host1,group1,winrm://host2:54321')
+  # @example Run on localhost
+  #   get_targets('localhost')
   dispatch :get_targets do
     param 'Boltlib::TargetSpec', :names
     return_type 'Array[Target]'
@@ -37,6 +36,9 @@ Puppet::Functions.create_function(:get_targets) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('get_targets')
+
     inventory.get_targets(names)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/puppetdb_fact.rb

@@ -2,14 +2,15 @@
 
 require 'bolt/error'
 
-# Returns a hash of certname to facts objects for each matched Target.  This
-# functions accepts an array of certnames and returns a hash of target
-# certnames and their corresponding facts hash.
+# Collects facts based on a list of certnames.
 #
 # * If a node is not found in PuppetDB, it's included in the returned hash with empty facts hash.
 # * Otherwise the node is included in the hash with a value that is a hash of it's facts.
-#
 Puppet::Functions.create_function(:puppetdb_fact) do
+  # @param certnames Array of certnames.
+  # @return A hash of certname to facts hash for each matched Target.
+  # @example Get facts for nodes
+  #   puppetdb_fact(['app.example.com', 'db.example.com'])
   dispatch :puppetdb_fact do
     param 'Array[String]', :certnames
     return_type 'Hash[String, Data]'
@@ -29,6 +30,9 @@ Puppet::Functions.create_function(:puppetdb_fact) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('puppetdb_fact')
+
     puppetdb_client.facts_for_node(certnames)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/puppetdb_query.rb

@@ -2,15 +2,17 @@
 
 require 'bolt/error'
 
-#
-# Makes a query to puppetdb using the bolts puppetdb client.
-#
+# Makes a query to puppetdb using Bolt's PuppetDB client.
 Puppet::Functions.create_function(:puppetdb_query) do
-  # This type could be more specific ASTQuery = Array[Variant[String, ASTQuery]]
+  # @param query A PQL query.
+  # @return Results of the PuppetDB query.
+  # @example Request certnames for all nodes
+  #   puppetdb_query('nodes[certname] {}')
   dispatch :make_query do
     param 'Variant[String, Array[Data]]', :query
     return_type 'Array[Data]'
   end
+  # The query type could be more specific ASTQuery = Array[Variant[String, ASTQuery]]
 
   def make_query(query)
     puppetdb_client = Puppet.lookup(:bolt_pdb_client) { nil }
@@ -20,6 +22,9 @@ Puppet::Functions.create_function(:puppetdb_query) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('puppetdb_query')
+
     puppetdb_client.make_query(query)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/run_command.rb

@@ -3,13 +3,15 @@
 require 'bolt/error'
 
 # Runs a command on the given set of targets and returns the result from each command execution.
-#
-# * This function does nothing if the list of targets is empty.
-# * It is possible to run on the target 'localhost'
-# * A target is a String with a targets's hostname or a Target.
-# * The returned value contains information about the result per target.
-#
+# This function does nothing if the list of targets is empty.
 Puppet::Functions.create_function(:run_command) do
+  # Run a command.
+  # @param command A command to run on target.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options Additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Run a command on targets
+  #   run_command('hostname', $targets, '_catch_errors' => true)
   dispatch :run_command do
     param 'String[1]', :command
     param 'Boltlib::TargetSpec', :targets
@@ -17,6 +19,14 @@ Puppet::Functions.create_function(:run_command) do
     return_type 'ResultSet'
   end
 
+  # Run a command, logging the provided description.
+  # @param command A command to run on target.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options Additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Run a command on targets
+  #   run_command('hostname', $targets, '_catch_errors' => true)
   dispatch :run_command_with_description do
     param 'String[1]', :command
     param 'Boltlib::TargetSpec', :targets
@@ -47,6 +57,8 @@ Puppet::Functions.create_function(:run_command) do
       )
     end
 
+    executor.report_function_call('run_command')
+
     # Ensure that given targets are all Target instances
     targets = inventory.get_targets(targets)
 

data/bolt-modules/boltlib/lib/puppet/functions/run_plan.rb

@@ -2,17 +2,13 @@
 
 require 'bolt/error'
 
-# Runs the `plan` referenced by its name passing giving arguments to it given as a hash of name to value mappings.
-# A plan is autoloaded from under <root>/plans if not already defined.
-#
-# @example defining and running a plan
-#   plan myplan($x) {
-#     # do things with tasks
-#     notice "plan done with param x = ${x}"
-#   }
-#   run_plan('myplan', { x => 'testing' })
-#
+# Runs the `plan` referenced by its name. A plan is autoloaded from <moduleroot>/plans.
 Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction) do
+  # @param plan_name The plan to run.
+  # @param named_args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as'.
+  # @return [PlanResult] The result of running the plan. Undef if plan does not explicitly return results.
+  # @example Run a plan
+  #   run_plan('canary', 'command' => 'false', 'nodes' => $targets, '_catch_errors' => true)
   dispatch :run_plan do
     scope_param
     param 'String', :plan_name
@@ -33,6 +29,12 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
       )
     end
 
+    # Bolt calls this function internally to trigger plans from the CLI. We
+    # don't want to count those invocations.
+    unless named_args['_bolt_api_call']
+      executor.report_function_call('run_plan')
+    end
+
     params = named_args.reject { |k, _| k.start_with?('_') }
 
     loaders = closure_scope.compiler.loaders

data/bolt-modules/boltlib/lib/puppet/functions/run_script.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 # Uploads the given script to the given set of targets and returns the result of having each target execute the script.
-#
-# * This function does nothing if the list of targets is empty.
-# * It is possible to run on the target 'localhost'
-# * A target is a String with a targets's hostname or a Target.
-# * The returned value contains information about the result per target.
-#
+# This function does nothing if the list of targets is empty.
 Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFunction) do
+  # Run a script.
+  # @param script Path to a script to run on target. May be an absolute path or a modulename/filename selector for a
+  #               file in <moduleroot>/files.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options Specify an array of arguments to the 'arguments' key to be passed to the script.
+  #                Additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Run a local script on Linux targets as 'root'
+  #   run_script('/var/tmp/myscript', $targets, '_run_as' => 'root')
+  # @example Run a module-provided script with arguments
+  #   file_upload('iis/setup.ps1', $target, 'arguments' => ['/u', 'Administrator'])
   dispatch :run_script do
     scope_param
     param 'String[1]', :script
@@ -16,6 +22,16 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     return_type 'ResultSet'
   end
 
+  # Run a script, logging the provided description.
+  # @param script Path to a script to run on target. May be an absolute path or a modulename/filename selector for a
+  #               file in <moduleroot>/files.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options Specify an array of arguments to the 'arguments' key to be passed to the script.
+  #                Additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Run a script
+  #   file_upload('/var/tmp/myscript', $targets, 'Downloading my application')
   dispatch :run_script_with_description do
     scope_param
     param 'String[1]', :script
@@ -47,6 +63,8 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
       )
     end
 
+    executor.report_function_call('run_script')
+
     found = Puppet::Parser::Files.find_file(script, scope.compiler.environment)
     unless found && Puppet::FileSystem.exist?(found)
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(

data/bolt-modules/boltlib/lib/puppet/functions/run_task.rb

@@ -3,36 +3,52 @@
 require 'bolt/error'
 
 # Runs a given instance of a `Task` on the given set of targets and returns the result from each.
-#
-# * This function does nothing if the list of targets is empty.
-# * It is possible to run on the target 'localhost'
-# * A target is a String with a targets's hostname or a Target.
-# * The returned value contains information about the result per target.
-#
+# This function does nothing if the list of targets is empty.
 Puppet::Functions.create_function(:run_task) do
-  dispatch :run_task_with_description do
+  # Run a task.
+  # @param task_name The task to run.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param task_args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Run a task as root
+  #   run_task('facts', $targets, '_run_as' => 'root')
+  dispatch :run_task do
     param 'String[1]', :task_name
     param 'Boltlib::TargetSpec', :targets
-    param 'String', :description
     optional_param 'Hash[String[1], Any]', :task_args
     return_type 'ResultSet'
   end
 
-  dispatch :run_task do
+  # Run a task, logging the provided description.
+  # @param task_name The task to run.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param task_args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as'.
+  # @return A list of results, one entry per target.
+  # @example Run a task
+  #   run_task('facts', $targets, 'Gather OS facts')
+  dispatch :run_task_with_description do
     param 'String[1]', :task_name
     param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
     optional_param 'Hash[String[1], Any]', :task_args
     return_type 'ResultSet'
   end
 
-  # this is used from 'bolt task run'
+  # Run a task, calling the block as each node starts and finishes execution. This is used from 'bolt task run'
+  # @param task_name The task to run.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param task_args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as'.
+  # @param block A block that's invoked as actions are started and finished on each node.
+  # @return A list of results, one entry per target.
   dispatch :run_task_raw do
     param 'String[1]', :task_name
     param 'Boltlib::TargetSpec', :targets
     param 'Optional[String]', :description
     optional_param 'Hash[String[1], Any]', :task_args
-    # return_type 'ResultSet'
-    block_param
+    block_param 'Callable[Struct[{type => Enum[node_start, node_result], target => Target}], 1, 1]', :block
+    return_type 'ResultSet'
   end
 
   def run_task(task_name, targets, task_args = nil)
@@ -64,6 +80,12 @@ Puppet::Functions.create_function(:run_task) do
       )
     end
 
+    # Bolt calls this function internally to trigger tasks from the CLI. We
+    # don't want to count those invocations.
+    unless task_args['_bolt_api_call']
+      executor.report_function_call('run_task')
+    end
+
     # Ensure that given targets are all Target instances
     targets = inventory.get_targets(targets)
 

data/bolt-modules/boltlib/lib/puppet/functions/set_feature.rb

@@ -2,9 +2,18 @@
 
 require 'bolt/error'
 
-# Sets a particular feature to present on a target.
-
+# Sets a particular feature to present on a target. Features are used to determine what implementation
+# of a task should be run. Currently supported features are
+# - powershell
+# - shell
+# - puppet-agent
 Puppet::Functions.create_function(:set_feature) do
+  # @param target The Target object to add features to. See {get_targets}.
+  # @param feature The string identifying the feature.
+  # @param value Whether the feature is supported.
+  # @return [Undef]
+  # @example Add the puppet-agent feature to a target
+  #   set_feature($target, 'puppet-agent', true)
   dispatch :set_feature do
     param 'Target', :target
     param 'String', :feature
@@ -26,6 +35,9 @@ Puppet::Functions.create_function(:set_feature) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('set_feature')
+
     inventory.set_feature(target, feature, value)
 
     target

data/bolt-modules/boltlib/lib/puppet/functions/set_var.rb

@@ -3,14 +3,13 @@
 require 'bolt/error'
 
 # Sets a variable { key => value } for a target.
-#
-# This function takes 3 parameters:
-# * A Target object to set the variable for
-# * The key for the variable (String)
-# * The value of the variable (Data)
-#
-# Returns undef.
 Puppet::Functions.create_function(:set_var) do
+  # @param target The Target object to set the variable for. See {get_targets}.
+  # @param key The key for the variable.
+  # @param value The value of the variable.
+  # @return [Undef]
+  # @example Set a variable on a target
+  #   $target.set_var('ephemeral', true)
   dispatch :set_var do
     param 'Target', :target
     param 'String', :key
@@ -32,6 +31,9 @@ Puppet::Functions.create_function(:set_var) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('set_var')
+
     inventory.set_var(target, key, value)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/vars.rb

@@ -5,11 +5,13 @@ require 'bolt/error'
 # Returns a hash of the 'vars' (variables) assigned to a target through the
 # inventory file or `set_var` function.
 #
-# Accepts no parameters.
-#
 # Plan authors can call this function on a target to get the variable hash
 # for that target.
 Puppet::Functions.create_function(:vars) do
+  # @param target The Target object to get variables from. See {get_targets}.
+  # @return A hash of the 'vars' (variables) assigned to a target.
+  # @example Get vars for a target
+  #   $target.vars
   dispatch :vars do
     param 'Target', :target
     return_type 'Hash[String, Data]'
@@ -30,6 +32,9 @@ Puppet::Functions.create_function(:vars) do
       )
     end
 
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call('vars')
+
     inventory.vars(target)
   end
 end

data/bolt-modules/boltlib/lib/puppet/functions/without_default_logging.rb

@@ -1,12 +1,26 @@
 # frozen_string_literal: true
 
+# Define a block where default logging is suppressed. Messages for actions within this block
+# will be logged at `info` level instead of `notice`, so they will not be seen normally but
+# will still be present when `verbose` logging is requested.
 Puppet::Functions.create_function(:without_default_logging) do
+  # @param block The block where action logging is suppressed.
+  # @return [Undef]
+  # @example Suppress default logging for a series of functions
+  #   without_default_logging() || {
+  #     notice("Deploying on ${nodes}")
+  #     get_targets($nodes).each |$node| {
+  #       run_task(deploy, $node)
+  #     }
+  #   }
   dispatch :without_default_logging do
     block_param 'Callable[0, 0]', :block
   end
 
   def without_default_logging
     executor = Puppet.lookup(:bolt_executor) { nil }
+    executor.report_function_call('without_default_logging')
+
     old_log = executor.plan_logging
     executor.plan_logging = false
     begin

data/lib/bolt/analytics.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'bolt/util'
 require 'bolt/version'
 require 'httpclient'
 require 'json'
@@ -13,6 +14,12 @@ module Bolt
     APPLICATION_NAME = 'bolt'
     TRACKING_ID = 'UA-120367942-1'
     TRACKING_URL = 'https://google-analytics.com/collect'
+    CUSTOM_DIMENSIONS = {
+      operating_system: :cd1,
+      inventory_nodes: :cd2,
+      inventory_groups: :cd3,
+      target_nodes: :cd4
+    }.freeze
 
     def self.build_client
       logger = Logging.logger[self]
@@ -60,13 +67,17 @@ module Bolt
         @os = compute_os
       end
 
-      def screen_view(screen)
+      def screen_view(screen, **kwargs)
+        custom_dimensions = Bolt::Util.walk_keys(kwargs) do |k|
+          CUSTOM_DIMENSIONS[k] || raise("Unknown analytics key '#{k}'")
+        end
+
         screen_view_params = {
           # Type
           t: 'screenview',
           # Screen Name
           cd: screen
-        }
+        }.merge(custom_dimensions)
 
         submit(base_params.merge(screen_view_params))
       end
@@ -146,7 +157,7 @@ module Bolt
         @logger = Logging.logger[self]
       end
 
-      def screen_view(screen)
+      def screen_view(screen, **_kwargs)
         @logger.debug "Skipping submission of '#{screen}' screenview because analytics is disabled"
       end
 

data/lib/bolt/cli.rb

@@ -501,7 +501,11 @@ Available options are:
       if options[:action] == 'show' && options[:object]
         screen += '_object'
       end
-      @analytics.screen_view(screen)
+
+      @analytics.screen_view(screen,
+                             target_nodes: options.fetch(:targets, []).count,
+                             inventory_nodes: inventory.node_names.count,
+                             inventory_groups: inventory.group_names.count)
 
       if options[:mode] == 'plan' || options[:mode] == 'task'
         pal = Bolt::PAL.new(config)

data/lib/bolt/executor.rb

@@ -123,6 +123,10 @@ module Bolt
       @reported_transports.add(name)
     end
 
+    def report_function_call(function)
+      @analytics&.event('Plan', 'call_function', function)
+    end
+
     def with_node_logging(description, batch)
       @logger.info("#{description} on #{batch.map(&:uri)}")
       result = yield
@@ -170,6 +174,7 @@ module Bolt
       log_action(description, targets) do
         notify = proc { |event| @notifier.notify(callback, event) if callback }
         options = { '_run_as' => run_as }.merge(options) if run_as
+        arguments['_task'] = task.name
 
         results = batch_execute(targets) do |transport, batch|
           with_node_logging("Running task #{task.name} with '#{arguments}' via #{task.input_method}", batch) do

data/lib/bolt/inventory.rb

@@ -78,6 +78,14 @@ module Bolt
       @group_lookup = @groups.collect_groups
     end
 
+    def group_names
+      @group_lookup.keys
+    end
+
+    def node_names
+      @groups.node_names
+    end
+
     def get_targets(targets)
       targets = expand_targets(targets)
       targets = if targets.is_a? Array

data/lib/bolt/outputter/human.rb

@@ -112,7 +112,7 @@ module Bolt
         )
       end
 
-      # @param [Hash] A hash representing the task
+      # @param [Hash] task A hash representing the task
       def print_task_info(task)
         # Building lots of strings...
         pretty_params = +""
@@ -142,7 +142,7 @@ module Bolt
         @stream.puts(task_info)
       end
 
-      # @param [Hash] A hash representing the plan
+      # @param [Hash] plan A hash representing the plan
       def print_plan_info(plan)
         # Building lots of strings...
         pretty_params = +""
@@ -161,7 +161,7 @@ module Bolt
         @stream.puts(plan_info)
       end
 
-      # @param [Bolt::PlanResult] A PlanResult object
+      # @param [Bolt::PlanResult] plan_result A PlanResult object
       def print_plan_result(plan_result)
         if plan_result.value.nil?
           @stream.puts("Plan completed successfully with no result")

data/lib/bolt/pal.rb

@@ -240,13 +240,14 @@ module Bolt
 
     def run_task(task_name, targets, params, executor, inventory, description = nil, &eventblock)
       in_task_compiler(executor, inventory) do |compiler|
+        params = params.merge('_bolt_api_call' => true)
         compiler.call_function('run_task', task_name, targets, description, params, &eventblock)
       end
     end
 
     def run_plan(plan_name, params, executor = nil, inventory = nil, pdb_client = nil)
       in_plan_compiler(executor, inventory, pdb_client) do |compiler|
-        r = compiler.call_function('run_plan', plan_name, params)
+        r = compiler.call_function('run_plan', plan_name, params.merge('_bolt_api_call' => true))
         Bolt::PlanResult.from_pcore(r, 'success')
       end
     rescue Bolt::Error => e

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '0.20.6'
+  VERSION = '0.20.7'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 0.20.6
+  version: 0.20.7
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-07 00:00:00.000000000 Z
+date: 2018-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -394,14 +394,6 @@ files:
 - modules/canary/lib/puppet/functions/canary/random_split.rb
 - modules/canary/lib/puppet/functions/canary/skip.rb
 - modules/canary/plans/init.pp
-- modules/facts/lib/puppet/functions/facts/group_by.rb
-- modules/facts/plans/info.pp
-- modules/facts/plans/init.pp
-- modules/facts/plans/retrieve.pp
-- modules/facts/tasks/bash.sh
-- modules/facts/tasks/init.json
-- modules/facts/tasks/powershell.ps1
-- modules/facts/tasks/ruby.rb
 - modules/puppetdb_fact/plans/init.pp
 - vendored/facter/lib/facter.rb
 - vendored/facter/lib/facter/Cfkey.rb

data/modules/facts/lib/puppet/functions/facts/group_by.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-# A simple wrapper of the ruby's group_by function.
-Puppet::Functions.create_function(:'facts::group_by') do
-  dispatch :native_group_by do
-    param 'Iterable', :collection
-    block_param
-    return_type 'Hash'
-  end
-
-  def native_group_by(collection, &block)
-    collection.group_by(&block)
-  end
-end

data/modules/facts/plans/info.pp

@@ -1,15 +0,0 @@
-# A plan that prints basic OS information for the specified nodes. It first
-# runs the facts::retrieve plan to retrieve facts from the nodes, then
-# compiles the desired OS information from the os fact value of each nodes.
-#
-# The $nodes parameter is a list of the nodes for which to print the OS
-# information.
-plan facts::info(TargetSpec $nodes) {
-  return run_plan(facts::retrieve, nodes => $nodes).reduce([]) |$info, $r| {
-    if ($r.ok) {
-      $info + "${r.target.name}: ${r[os][name]} ${r[os][release][full]} (${r[os][family]})"
-    } else {
-      $info # don't include any info for nodes which failed
-    }
-  }
-}

data/modules/facts/plans/init.pp

@@ -1,16 +0,0 @@
-# A plan that stores facts retrieved by the facts::retrieve plan
-# from the specified nodes into the inventory.
-#
-# The $nodes parameter is a list of nodes to retrieve the facts for.
-plan facts(TargetSpec $nodes) {
-  $result_set = run_plan(facts::retrieve, nodes => $nodes)
-
-  $result_set.each |$result| {
-    # Store facts for nodes from which they were succefully retrieved
-    if ($result.ok) {
-      add_facts($result.target, $result.value)
-    }
-  }
-
-  return $result_set
-}

data/modules/facts/plans/retrieve.pp

@@ -1,8 +0,0 @@
-# A plan that retrieves facts from the specified nodes by running
-# the 'facts' task on each.
-#
-# The $nodes parameter is a list of the nodes to retrieve the facts
-# from.
-plan facts::retrieve(TargetSpec $nodes) {
-  return run_task('facts', $nodes, '_catch_errors' => true)
-}

data/modules/facts/tasks/bash.sh

@@ -1,92 +0,0 @@
-#!/usr/bin/env bash
-
-# Delegate to facter if available
-command -v facter > /dev/null 2>&1 && exec facter -p --json
-
-minor () {
-    minor="${*#*.}"
-    [ "$minor" == "$*" ] || echo "${minor%%.*}"
-}
-
-# Determine the OS name
-if [ -f /etc/redhat-release ]; then
-    if egrep -iq centos /etc/redhat-release; then
-        name=CentOS
-    elif egrep -iq 'Fedora release' /etc/redhat-release; then
-        name=Fedora
-    fi
-    release=$(sed -r -e 's/^.* release ([0-9]+(\.[0-9]+)?).*$/\1/' \
-                  /etc/redhat-release)
-fi
-
-if [ -z "${name}" ]; then
-    LSB_RELEASE=$(command -v lsb_release)
-    if [ -n "$LSB_RELEASE" ]; then
-        if [ -z "$name" ]; then
-            name=$($LSB_RELEASE -i | sed -re 's/^.*:[ \t]*//')
-        fi
-        release=$($LSB_RELEASE -r | sed -re 's/^.*:[ \t]*//')
-    fi
-fi
-
-# if lsb not available try os-release
-if [ -z "${name}" ]; then
-    if [ -e /etc/os-release ]; then
-        name=$(grep "^NAME" /etc/os-release | cut -d'=' -f2 | sed "s/\"//g")
-        release=$(grep "^VERSION_ID" /etc/os-release | cut -d'=' -f2 | sed "s/\"//g")
-    elif [-e /usr/lib/os-release ]; then
-        name=$(grep "^NAME" /usr/lib/os-release | cut -d'=' -f2 | sed "s/\"//g")
-        release=$(grep "^VERSION_ID" /usr/lib/os-release | cut -d'=' -f2 | sed "s/\"//g")
-    fi
-    if [ -n "${name}" ]; then
-        if echo "${name}" | egrep -iq "(.*red)(.*hat)"; then
-            name="RedHat"
-        elif echo "${name}" | egrep -iq "debian"; then
-            name="Debian"
-        fi
-    fi
-fi
-
-if [ -z "${name}" ]; then
-    name=$(uname)
-    release=$(uname -r)
-fi
-
-case $name in
-    RedHat|Fedora|CentOS|Scientific|SLC|Ascendos|CloudLinux)
-        family=RedHat;;
-    HuaweiOS|LinuxMint|Ubuntu|Debian)
-        family=Debian;;
-    *)
-        family=$name;;
-esac
-
-# Print it all out
-if [ -z "$name" ]; then
-    cat <<JSON
-{
-  "_error": {
-    "kind": "facts/noname",
-    "msg": "Could not determine OS name"
-  }
-}
-JSON
-else
-    cat <<JSON
-{
-  "os": {
-    "name": "${name}",
-JSON
-    [ -n "$release" ] && cat <<JSON
-    "release": {
-      "full": "${release}",
-      "major": "${release%%.*}",
-      "minor": "`minor "${release}"`"
-    },
-JSON
-    cat <<JSON
-    "family": "${family}"
-  }
-}
-JSON
-fi

data/modules/facts/tasks/init.json

@@ -1,9 +0,0 @@
-{
-  "description": "Gather system facts",
-  "parameters": {},
-  "implementations": [
-    {"name": "ruby.rb", "requirements": ["puppet-agent"]},
-    {"name": "powershell.ps1", "requirements": ["powershell"]},
-    {"name": "bash.sh", "requirements": ["shell"]}
-  ]
-}

data/modules/facts/tasks/powershell.ps1

@@ -1,56 +0,0 @@
-#!powershell.exe
-
-# Delegate to facter if available
-if (Get-Command facter -ErrorAction SilentlyContinue) {
-    facter -p --json
-}
-else {
-    # The number 2 in the condition below is the value of
-    # the [System.PlatformID]::Win32NT constant. We don't
-    # use the constant here as it doesn't work on Windows
-    # Server Core.
-    if ([System.Environment]::OSVersion.Platform -gt 2) {
-        @'
-{
-  "_error": {
-    "kind": "facts/noname",
-    "msg": "Could not determine OS name"
-  }
-}
-'@
-    }
-    else {
-        $release = [System.Environment]::OSVersion.Version.ToString() -replace '\.[^.]*\z'
-        $version = $release -replace '\.[^.]*\z'
-
-        # This fails for regular users unless explicitly enabled
-        $os = Get-CimInstance Win32_OperatingSystem -ErrorAction SilentlyContinue
-        $consumerrel = $os.ProductType -eq '1'
-
-        $release = switch($version){
-            '10.0'{ if ($consumerrel) { '10' } else { '2016' } }
-            '6.3' { if ($consumerrel) { '8.1' } else { '2012 R2' } }
-            '6.2' { if ($consumerrel) { '8' } else { '2012' } }
-            '6.1' { if ($consumerrel) { '7' } else { '2008 R2' } }
-            '6.0' { if ($consumerrel) { 'Vista' } else { '2008' } }
-            '5.2' { 
-                if ($consumerrel) { 'XP' } else {
-                    if ($os.OtherTypeDescription -eq 'R2') { '2003 R2' } else { '2003' }
-                }
-            }
-        }
-
-        @"
-{
-  "os": {
-    "name": "windows",
-    "release": {
-      "full": "$release",
-      "major": "$release"
-    },
-    "family": "windows"
-  }
-}
-"@
-    }
-}

data/modules/facts/tasks/ruby.rb

@@ -1,18 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-def facter_executable
-  if ENV.key? 'Path'
-    ENV['Path'].split(';').each do |p|
-      if p =~ /Puppet\\bin\\?$/
-        return File.join(p, 'facter')
-      end
-    end
-    'C:\Program Files\Puppet Labs\Puppet\bin\facter'
-  else
-    '/opt/puppetlabs/puppet/bin/facter'
-  end
-end
-
-# Delegate to facter
-exec(facter_executable, '-p', '--json')