redhatinsights/ansible-insights-client

Ansible-based client for Insights

ansible-insights-client's Issues

Alternative names for Specs, Mappers, Reducers

This is a proposed alternative set of re-namings for the things we have historically called Specs, Mappers, and Reducers.

This is prompted by the re-namings @jhjaggars defined near the end of https://github.com/RedHatInsights/ansible-insights-client/blob/master/clientarch.md . That document renames Mappers to Parsers, and Reducers to Combiners. I agree that we shouldn't go on calling them Mappers and Reducers, but I believe that renaming doesn't go far enough.

What we call stuff effects how we think about them, and how our consumers think about them. So far our consumers have only been us developers, and our rule developers who are to a large degree part of "us". As we begin to integrate with other Red Hat systems/tools/groups, and as we begin to integrate into the larger OSS ecosystem, we have to consider how the names we choose will be understood by those other outsider consumers.

A third prompting for this proposal, is that I'm attempting to write what I think we need to do for the "Rules/Reducers in Ansible-esque YAML" project, and trying to do it in terms of Falafel Rules (a Reducer that returns the result of make_response or None), Insights Rules (which combines Content to Falafel Rules), Reducers, and Mappers is harder than I think it needs to be. We don't have to adopt this proposal to do "Ansible-esque YAML", but it will be easier to describe in terms of this proposal than Parsers and Combiners.

Proposal Summary and Suppositions

Instead of Specs, Parsers, and Combiners, I'm proposing Facts, FactCollectors, and FactExtenders. FactCollectors are similar to Specs. FactExtenders are similar to Parsers and Combiners. The primary non-similarity is that FactCollectors and FactExtenders produce the same thing, Facts.

I think that with this proposal, the data that Insights collects, extends, and processes is close enough to "Ansible Facts" that we can call the data just "Facts" without creating confusion between what Ansible calls Facts, and what Insights calls Facts.

I think that the changes to our existing code implied by this proposal are not significantly out of line with our current code and plans. In particular, I think that having all three of Specs, Parsers/Mappers, and Reducers/Combiners produce a uniform thing, a Fact, is not a particularly large stretch from what we are doing now.

Proposal

Fact

A Fact is some data about a System. It can be represented as (serialized into) a Data Language object (like JSON), or represented as (deserialized into) a Programming Language object (like a Python object).

Facts have a documented names. For example, there is a "hostname" fact. There is a "cpuinfo" fact. And so on. The name of the fact is part of it's definition and it's serialization. The serialization of the "hostname" fact is not just the system's hostname, it is something like '{ "hostname" : "myhost.example.com" }'. Fact names tell you what kind of Fact it is. When represented as a Programming Language object, there is a one-to-one relationship between the names of Facts, and the classes that represent those Facts. For example, the "hostname" Fact is represented by an instance of the Hostname class.

Facts have a documented 'serialization'. For example, the value of the "hostname" fact, when serialized, is the hostname of the system represented as a string.

Facts represented as some Programming Language object can have additional properties or member functions to facilitate use of the Fact. This is facilitated by having a one-to-one relationship between Fact names and Fact classes.

All Facts are about a System. Most Facts are collected directly on a system. But some Facts are created by combining existing Facts together, or by combining existing Facts with external data, and need not be created on or known directly by the System in question. However they are initially created, they are all equally Facts: they all have documented names, they all have documented serializations/deserializations.

FactCollector

A FactCollector is an executable description (code) of how to collect a named Fact on a System. It is the definition of a named Fact for Facts collected directly on a System.

A Fact defined by a FactCollector is initially created by running the executable description (the collection code) on the System.

We currently call this a "Spec".

FactExtender

A Fact is an executable description (code) of how to create a new Fact from other Facts and/or data from other off system locations. It is the definition of a named Fact for Facts not collected directly on a System.

A Fact defined by a FactExtender is initially created by running the executable description giving as input the existing Facts it depends upon.

We currently call these "Mappers"/"Parsers" and "Reducers"/"Combiners".