Reporting UI

Table of contents

CFEngine collects a large amount of data. To inspect it, you can run and schedule pre-defined reports or use thequery builder for your own custom reports. You can save these queries for later use, and schedule reports for specified times.

If you are familiar with SQL syntax, you can input your query into the interface directly. Make sure to take a look at the database schema. Please note: manual entries in the query field at the bottom of thequery builder will invalidate all field selections and filters above, and vice-versa.

You can share the report with other users - either by using "Save" button, or by base64-encoding the report query into a URL. You can also provide an optional title by addingtitle parameter to the URL, like this:

code

HUB_URL="https://hub"API="/index.php/advancedreports/#/report/run?sql="SQL_QUERY="SELECT Hosts.HostName AS 'Host Name' FROM Hosts"REPORT_TITLE="Example Report"LINK="${HUB_URL}${API}$(echo ${SQL_QUERY} | base64)&title=$(/usr/bin/urlencode ${REPORT_TITLE})"echo "${LINK}"

code

https://hub/index.php/advancedreports/#/report/run?sql=U0VMRUNUIEhvc3RzLkhvc3ROYW1lIEFTICdIb3N0IE5hbWUnIEZST00gSG9zdHMK&title=Example%20Report

You can query fewer hosts with the help of filters above the displayed table. These filters are based on the same categorization you can find in the other apps.

You can also filter on the type of promise: user defined, system defined, or all.

Query builder

Users not familiar with SQL syntax can easily create their own custom reports in this interface. Please note that query builder can beextended with your custom data.

Tables - Select the data tables you want include in your report first.
- When more than one table is selected the Query builder opens modal window to select the (join strategy between tables):
  - Main table - the main data source, other tables will be connected to it.
  - Extend main table (left join) - returns all records from the main table, and the matched records from the joined table.
  - Include only common rows (inner join) - returns records from the main table that intersect the joined table.Useful for filtering, in the case where you have custom views that have pre-filtered hosts. For example, web_servers - a custom view that contains hostkeys of hosts that are web servers.
Fields - Define your table columns based on your selection above.
Filters - Filter your results. Remember that unless you filter, you may be querying large data sets, so think about what you absolutely need in your report.
Group - Group your results. May be expensive with large data sets.
Sort - Sort your results. May be expensive with large data sets.
Limit - Limit the number of entries in your report. This is a recommended practice for testing your query, and even in production it may be helpful if you don't need to see every entry.
Show me the query - View and edit the SQL query directly. Please note, that editing the query directly here will invalidate your choices in the query builder interface, and changing your selections there will override your SQL query.

Report Builder

Ensure the report collection is working

The reporting bundle must be called frompromises.cf. For example,the following defines the attributeRole which is set todatabase_server. You need to add it to the top-levelbundlesequence inpromises.cf or in a bundle that it calls.

promises.cf

bundleagentmyreport{vars:"myrole"string=>"database_server",meta=>{"inventory","attribute_name=Role"};}

note themeta taginventory
The hub must be able to collect the reports from the client. TCPport 5308 must be open and, because 3.6 uses TLS, should not beproxied or otherwise intercepted. Note that bootstrapping and otherstandalone client operations go from the client to the server, so theability to bootstrap and copy policies from the server doesn'tnecessarily mean the reverse connection will work.
Ensure that variables and classes tagged asinventory orreportare not filtered bycontrols/cf_serverd.cf in your infrastructure.The standard configuration from the stock CFEngine packages allowsthem and should work.

Note: The CFEngine report collection model accounts for long periods oftime when the hub is unable to collect data from remote agents. This modelpreserves data recorded until it can be collected. Data (promise outcomes, etc...) recorded by the agent during normal agent runs is stored locally until itis collected from by the cf-hub process. At the time of collection the localdata stored on the client is cleaned up and only the last hours worth of dataremains client. It is important to understand that the time between hubcollection and number of clients that are unable to be collected from grows theamount of data to transfer and store in the central database also grows. Alarge number of clinets that have not been collected from that become availableat once can cause increased load on the hub collector and affect itsperformance until it has been able to collect from all hosts.

Define a new single table report

InMission Portal select theReport application icon on the left hand side of the screen.
This will bring you to theReport builder screen.
The default for what hosts to report on isAll hosts. The hosts can be filtered under theFilters section at the top of the page.
For this tutorial leave it asAll hosts.
Set which tables' data we want reports for.
For this tutorial selectHosts.
Select the columns from theHosts table for the report.
For this tutorial click theSelect all link below the column lables.
LeaveFilters,Sort, andLimit at the default settings.
Click the orangeRun button in the bottom right hand corner.

Check report results

The report generated will show each of the selected columns across the report table's header row.
In this tutorial the columns being reported back should be:Host key,Last report time,Host name,IP address,First report-time.
Each row will contain the information for an individual data record, in this case one row for each host.
Some of the cells in the report may provide links to drill down into more detailed information (e.g.Host name will provide a link to aHost information page).
It is possible to also export the report to a file.
Click the orangeExport button.
You will then see aReport Download dialog.
Report type can be eithercsv orpdf format.
Leave other fields at the default values.
If the server's mail configuration is working properly, it is possible to email the report by checking theSend in email box.
ClickOK to download or email thecsv orpdf version of the report.
Once the report is generated it will be available for download or will be emailed.