Uploaded image for project: 'Puppet'
  1. Puppet
  2. PUP-4475

Add explain-ability to the lookup and data provider APIs

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Normal
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: PUP 4.3.0
    • Component/s: None
    • Labels:
      None
    • Template:
    • Epic Link:
    • Story Points:
      4
    • Sprint:
      Language 2015-09-02, Language 2015-09-16, Language 2015-09-30
    • Release Notes:
      New Feature
    • Release Notes Summary:
      As part of the 'data in modules' feature - the lookup command line tool can now explain how a looked up value was resolved by using the option --explain.

      Description

      In order to enable explaining how a particular looked up key gets its value (or no value (not found) the API of a DataProvider should accept an additional argument - an ÉxplanationAcceptor.

      By default a NullExplanationAcceptor is used.

      This acceptor should be passed throughout the calls:

      • Puppet::Pops::Lookup.lookup
      • Puppet::Pops::DataProviders.lookup_in_modules
      • Puppet::Pops::DataProviders.lookup_in_environment
      • ...EnvironmentDataProvider.lookup
      • ...ModuleDataProvider.lookup

      The acceptor should be based on an API that requires very little overhead when a NullExplainerAcceptor is used - i.e. avoiding formatting messages to add to the explainer.

      • LookupExplainerAcceptor.accept(&block) where the block is called by an acceptor that actually produces explanations seems like an adequate solution. The acceptor should pass itself as an argument to the block.
      • The block should call back to method(s) on the acceptor to log an explanation
      • Since lookup calls can nest (interpolation, delegation, merge) - the explainers also nest
      • An explainer has an outcome of: found, not_found (and its content describes how it arrived at that outcome) - if found it also has the value/result.
      • The resulting explainer tree should be serializeable as JSON (most likely presentation format).

      The puppet lookup function cannot easily support explain - it would need to return a generic data structure instead of the value - therefore this functionality is only available to command line utilities (or possible a a function added in the future with a signature similar to lookup but that returns the data structure).

      As an example (pseudo explanation):

      looking up key foo
      global
        data_provider: hiera 2.0
        result: not_found
        explanation:
          no value found
          hiera 2.0 cannot provide more details
      environment
        data_provider: hiera 3.0
        result: not_found
        explanation:
          searched_paths:
            { given path: "unexpanded path"
            expanded_path: "expanded path"
            result: not_found
            explanation:
              file_does_not exist
            },
            { given path: "unexpanded"
              expanded path: "expanded"
              result: not_found
              explanation:
                file_exists
                file does not have key
             },
           { end of paths }
      module:
        namespace: "mymodule"
        data_provider:  function
        result: found
        value: heureka
        explanation: 
          function returned a hash with the key present
      

      (The above is only an illustration)

      The first implementation should focus on the major branch points/results. New tickets should be added for more advanced/detailed explanations.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                henrik.lindberg Henrik Lindberg
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Zendesk Support