callback: Add argument_labels feature

This new configuration option will label playbooks automatically
based on CLI arguments picked up by the callback.

For example, when "--check" is used, it would label the playbook with
the label "check:True" or "check:True" when it isn't used.

Related: https://github.com/ansible-community/ara/issues/148
Related: https://github.com/ansible-community/ara/issues/119
Change-Id: Ifd475875bf83a21ab35c9cf0ac0410520b98d804

ara/plugins/callback/ara_default.py

@@ -106,6 +106,23 @@ options:
     ini:
       - section: ara
         key: api_timeout
+  argument_labels:
+    description: |
+        A list of CLI arguments that, if set, will be automatically applied to playbooks as labels.
+        Note that CLI arguments are not always named the same as how they are represented by Ansible.
+        For example, --limit is "subset", --user is "remote_user" but --check is "check".
+    type: list
+    default:
+      - remote_user
+      - check
+      - tags
+      - skip_tags
+      - subset
+    env:
+      - name: ARA_ARGUMENT_LABELS
+    ini:
+      - section: ara
+        key: argument_labels
   default_labels:
     description: A list of default labels that will be applied to playbooks
     type: list
@@ -173,6 +190,7 @@ class CallbackModule(CallbackBase):
     def set_options(self, task_keys=None, var_options=None, direct=None):
         super(CallbackModule, self).set_options(task_keys=task_keys, var_options=var_options, direct=direct)
 
+        self.argument_labels = self.get_option("argument_labels")
         self.default_labels = self.get_option("default_labels")
         self.ignored_facts = self.get_option("ignored_facts")
         self.ignored_arguments = self.get_option("ignored_arguments")
@@ -212,6 +230,23 @@ class CallbackModule(CallbackBase):
                 self.log.debug("Ignoring argument: %s" % argument)
                 cli_options[argument] = "Not saved by ARA as configured by 'ignored_arguments'"
 
+        # Retrieve and format CLI options for argument labels
+        argument_labels = []
+        for label in self.argument_labels:
+            if label in cli_options:
+                # Some arguments are lists or tuples
+                if isinstance(cli_options[label], tuple) or isinstance(cli_options[label], list):
+                    # Only label these if they're not empty
+                    if cli_options[label]:
+                        argument_labels.append("%s:%s" % (label, ",".join(cli_options[label])))
+                # Some arguments are booleans
+                elif isinstance(cli_options[label], bool):
+                    argument_labels.append("%s:%s" % (label, cli_options[label]))
+                # The rest can be printed as-is if there is something set
+                elif cli_options[label]:
+                    argument_labels.append("%s:%s" % (label, cli_options[label]))
+        self.argument_labels = argument_labels
+
         # Create the playbook
         self.playbook = self.client.post(
             "/api/v1/playbooks",
@@ -237,7 +272,7 @@ class CallbackModule(CallbackBase):
         if "ara_playbook_name" in play_vars:
             self._set_playbook_name(name=play_vars["ara_playbook_name"])
 
-        labels = self.default_labels
+        labels = self.default_labels + self.argument_labels
         if "ara_playbook_labels" in play_vars:
             # ara_playbook_labels can be supplied as a list inside a playbook
             # but it might also be specified as a comma separated string when

doc/source/ansible-plugins-and-use-cases.rst

@@ -29,6 +29,7 @@ For example, a customized callback plugin configuration might look like this in
     api_username = user
     api_password = password
     api_timeout = 15
+    argument_labels = check,tags,subset
     default_labels = prod,deploy
     ignored_facts = ansible_env,ansible_all_ipv4_addresses
     ignored_arguments = extra_vars,vault_password_files
@@ -42,6 +43,7 @@ or as environment variables:
     export ARA_API_USERNAME=user
     export ARA_API_PASSWORD=password
     export ARA_API_TIMEOUT=15
+    export ARA_ARGUMENT_LABELS=check,tags,subset
     export ARA_DEFAULT_LABELS=prod,deploy
     export ARA_IGNORED_FACTS=ansible_env,ansible_all_ipv4_addresses
     export ARA_IGNORED_ARGUMENTS=extra_vars,vault_password_files
@@ -112,6 +114,33 @@ or through the environment variable ``ARA_DEFAULT_LABELS``:
 
     export ARA_DEFAULT_LABELS=deploy,prod
 
+CLI argument labels
+~~~~~~~~~~~~~~~~~~~
+
+CLI argument labels will automatically apply labels to playbooks when specified CLI arguments are used.
+
+For example, if ``--check`` is used and set up as an argument label, the playbook will be tagged with
+``check:True`` if ``--check`` was used or ``check:False`` if it wasn't.
+
+.. note::
+   Some CLI arguments are not always named the same as how they are represented by Ansible.
+   For example, ``--limit`` is "subset", ``--user`` is "remote_user" but ``--check`` is "check".
+
+Argument labels can be configured through an ``ansible.cfg`` file:
+
+.. code-block:: ini
+
+    [defaults]
+    # ...
+    [ara]
+    argument_labels = check,subset,tags
+
+or through the environment variable ``ARA_ARGUMENT_LABELS``:
+
+.. code-block:: bash
+
+    export ARA_DEFAULT_LABELS=check,subset,tags
+
 ara_api: free-form API queries
 ------------------------------