Chapter 5. Downloading reports

During a scan, a collection of facts is gathered for each system that is contained in each source. A fact is a single piece of data about a system, such as the version of the operating system, the number of CPU cores, or a consumed entitlement for a Red Hat product.

Facts are processed to create a summarized set of data for each system, data that is known as a fingerprint. A fingerprint is the set of facts that identifies a unique system and its characteristics, including the architecture, operating system, the different products that are installed on that system and their versions, the entitlements that are in use on that system, and so on.

Fingerprinting data is generated when you run a scan job, but the data is used to create only one type of report. When you request a details report, you receive the raw facts for that scan without any fingerprinting. When you request a deployments report, you receive the fingerprinting data that includes the results from the deduplication, merging, and post-processing processes. These processes include identifying installed products and versions from the raw facts, finding consumed entitlements, finding and merging duplicate instances of products from different sources, and finding products installed in nondefault locations, among other steps.

A single system can be found in multiple sources during a scan. For example, a virtual machine on vCenter Server could be running a Red Hat Enterprise Linux operating system installation that is also managed by Satellite. If you construct a scan that contains each type of source, vcenter, satellite, and network, that single system is reported by all three sources during the scan.

To resolve this issue and build an accurate fingerprint, Discovery feeds unprocessed system facts from the scan into a fingerprint engine. The fingerprint engine matches and merges data for systems that are found in more than one source by using the deduplication and merge processes.

The system deduplication process uses specific facts about a system to identify duplicate systems. The process moves through several phases, using these facts to combine duplicate systems in successively broader sets of data:

After deduplication and merging are complete, there is a post-processing phase that creates derived system facts. A derived system fact is a fact that is generated from the evaluation of more than one system fact. The majority of derived system facts are related to product identification data, such as the presence of a specific product and its version.

The following example shows how the derived system fact system_creation_date is created.

The system_creation_date fact is a derived system fact that contains the real system creation time. The value for this fact is determined by the evaluation of the following facts. The value for each fact is examined in the following order of precedence, with the order of precedence determined by the accuracy of the match to the real system creation time. The highest non-empty value is used to determine the value of the system_creation_date fact.

After the processing of the report data is complete, the report creation process builds two reports in two different formats, JavaScript Object Notation (JSON) and comma-separated variable (CSV). The details report for each format contains the raw facts with no processing, and the deployments report for each format contains the output after the raw facts have passed through the fingerprinting, deduplication, merge, and post-processing processes.

The report format is designed to be used by the Red Hat Subscription Education and Awareness Program (SEAP) team during customer engagements and for other Red Hat internal processes.

A fingerprint is composed of a set of facts about a single system in addition to facts about products, entitlements, sources, and metadata on that system. The following example shows fingerprint data. A fingerprint for a single system, even with very few Red Hat products installed on it, can be many lines. Therefore, only a partial fingerprint is used in this example.

{
    "os_release": "Red Hat Enterprise Linux Atomic Host 7.4",
    "cpu_count": 4,
    "products": [
        {
            "name": "JBoss EAP",
            "version": null,
            "presence": "absent",
            "metadata": {
                "source_id": 5,
                "source_name": "S62Source",
                "source_type": "satellite",
                "raw_fact_key": null
            }
        }
    ],
    "entitlements": [
        {
            "name": "Satellite Tools 6.3",
            "entitlement_id": 54,
            "metadata": {
                "source_id": 5,
                "source_name": "S62Source",
                "source_type": "satellite",
                "raw_fact_key": "entitlements"
            }
        }
    ],
    "metadata": {
        "os_release": {
            "source_id": 5,
            "source_name": "S62Source",
            "source_type": "satellite",
            "raw_fact_key": "os_release"
        },
        "cpu_count": {
            "source_id": 4,
            "source_name": "NetworkSource",
            "source_type": "network",
            "raw_fact_key": "os_release"
        }
    },
    "sources": [
        {
            "id": 4,
            "source_type": "network",
            "name": "NetworkSource"
        },
        {
            "id": 5,
            "source_type": "satellite",
            "name": "S62Source"
        }
    ]
}

The first several lines of a fingerprint show facts about the system, including facts about the operating system and CPUs. In this example, the os_release fact describes the installed operating system and release as Red Hat Enterprise Linux Atomic Host 7.4.

Next, the fingerprint lists the installed products in the products section. A product has a name, version, presence, and metadata field. In the JBoss EAP section, the presence field shows absent as the value, so the system in this example does not have Red Hat JBoss Enterprise Application Platform installed.

The fingerprint also lists the consumed entitlements for that system in the entitlements section. Each entitlement in the list has a name, ID, and metadata that describes the original source of that fact. In the example fingerprint, the system has the Satellite Tools 6.3 entitlement.

In addition to the metadata fields that are in the products and entitlements sections, the fingerprint contains a metadata section that is used for system fact metadata. For each system fact, there is a corresponding entry in the metadata section of the fingerprint that identifies the original source of that system fact. In the example, the os_release fact was found in Satellite Server, during the scan of the satellite source.

Lastly, the fingerprint lists the sources that contain this system in the sources section. A system can be contained in more than one source. For example, for a scan that includes both a network source and a satellite source, a single system can be found in both parts of the scan.