Chapter 5. Downloading reports

After you run a scan, you can download the reports for that scan to view the data that was gathered and processed during that scan.

Learn more

To learn more about downloading reports, see the following information:

5.1. Downloading reports

After you run a scan, you can download the reports for that scan to view the data that was gathered and processed during that scan.

Reports for a scan are available in two formats, a comma-separated variable (CSV) format and a JavaScript Object Notation (JSON) format. They are also available in two content types, raw output from the scan as a details report and processed content as a deployments report.

Note

A third type of report is available, the insights report, but this report can be generated only through the Discovery command line interface. Downloading the insights report provides a .tar.gz file that you can transfer to the Hybrid Cloud Console at cloud.redhat.com. Transferring this file allows the report data to be used in the Red Hat Insights inventory service and in the subscriptions service.

Learn more

To learn more about merging and downloading reports, see the following information:

To learn more about how reports are created, see the following information. This information includes a chronology of the processes of report generation. These processes change the raw facts of a details report into fingerprint data, and then change fingerprint data into the deduplicated and merged data of a deployments report. This information also includes a partial fingerprint example to show the types of data that are used to create a Discovery report.

5.1.1. Downloading reports

From the Scans view, you can select one or more reports and download them to view the report data.

Prerequisites

If you want to download a report for a scan, the most recent scan job for that scan must have completed successfully.

Procedure

  1. From the Scans view, navigate to the row of the scan for which you want to download the report.
  2. Click Download for that scan.

Verification steps

The downloaded report is saved to the downloads location for your browser as a .tar.gz file, for example, report_id_224_20190702_173309.tar.gz. The filename format is report_id_ID_DATE_TIME.tar.gz, where ID is the unique report ID assigned by the server, DATE is the date in yyyymmdd format, and TIME is the time in the hhmmss format, based on the 24-hour system. The date and time data is determined by the interaction of the browser that is running the client with the server APIs.

To view the report, uncompress the .tar.gz file into a report_id_ID directory. The uncompressed report bundle includes four report files: two details reports in CSV and JSON formats, and two deployments reports in CSV and JSON formats.

Note

While you can view and use the output of these reports for your own internal processes, the Discovery documentation does not provide any information to help you interpret report results. In addition, although Red Hat Support can provide some basic assistance related to the installation and use of Discovery, the support team does not provide any assistance to help you understand the reports. The reports and their format are 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, such as providing data to various Hybrid Cloud Console services.

5.1.2. How reports are created

The scan process is used to discover the systems in your IT infrastructure, to inspect and gather information about the nature and contents of those systems, and to create a report from the information that it gathers during the inspection of each system.

A system is any entity that can be interrogated by the inspection tasks through an SSH connection, vCenter Server data, the Satellite Server API, or the Red Hat OpenShift cluster API. Therefore, a system can be a machine, such as a physical or virtual machine, and it can also be a different type of entity, such as a container or a cluster.

5.1.2.1. Facts and fingerprints

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.

5.1.2.2. System deduplication and system merging

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.

Note

Currently, you cannot combine an OpenShift or Ansible source with any other type of source in a scan, so deduplication and merging processes do not apply for an OpenShift or Ansible 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:

  • All systems from network sources are combined into a single network system set. Systems are considered to be duplicates if they have the same value for the subscription_manager_id or bios_uuid facts.
  • All systems from vcenter sources are combined into a single vcenter system set. Systems are considered to be duplicates if they have the same value for the vm_uuid fact.
  • All systems from satellite sources are combined into a single satellite system set. Systems are considered to be duplicates if they have the same value for the subscription_manager_id fact.
  • The network system set is merged with the satellite system set to form a single network-satellite system set. Systems are considered to be duplicates if they have the same value for the subscription_manager fact or matching MAC address values in the mac_addresses fact.
  • The network-satellite system set is merged with the vcenter system set to form the complete system set. Systems are considered to be duplicates if they have matching MAC address values in the mac_addresses fact or if the vcenter value for the vm_uuid fact matches the network value for the bios_uuid fact.
5.1.2.2.1. System merging

After the deduplication process determines that two systems are duplicates, the next step is to perform a merge of those two systems. The merged system has a union of system facts from each source. When a fact that appears in two systems is merged, the merge process uses the following order of precedence to merge that fact, from highest to lowest:

  1. network source fact
  2. satellite source fact
  3. vcenter source fact

A system fingerprint contains a metadata dictionary that captures the original source of each fact for that system.

5.1.2.3. System post-processing

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.

  1. date_machine_id
  2. registration_time
  3. date_anaconda_log
  4. date_filesystem_create
  5. date_yum_history

5.1.2.4. Report creation

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.

Note

While you can view and use the output of these reports for your own internal processes, the Discovery documentation does not provide any information to help you interpret report results. In addition, although Red Hat Support can provide some basic assistance related to the installation and use of Discovery, the support team does not provide any assistance to help you understand the reports. The reports and their format are 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, such as providing data to various Hybrid Cloud Console services.

5.1.2.5. A fingerprint example

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.

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.