Chapter 10. Using Report Templates to Monitor Hosts
You can use report templates to query Satellite data to obtain information about, for example, host status, registered hosts, applicable errata, applied errata, subscription details, and user activity. You can use the report templates that ship with Satellite or write your own custom report templates to suit your requirements. The reporting engine uses the embedded Ruby (ERB) syntax. For more information about writing templates and ERB syntax, see Appendix A, Template Writing Reference.
You can create a template, or clone a template and edit the clone. For help with the template syntax, click a template and click the Help tab.
10.1. Generating Host Monitoring Reports
To view the report templates in the Satellite web UI, navigate to Monitor > Report Templates. To schedule reports, configure a cron job or use the Satellite web UI.
Procedure
In the Satellite web UI, navigate to Monitor > Report Templates. For example, the following templates are available:
- Host – Installed Products
- Use this template for hosts in Simple Content Access (SCA) organizations. It generates a report with installed product information along with other metrics included in Subscription – Entitlement Report except information about subscriptions.
- Subscription – Entitlement Report
- Use this template for hosts that are not in SCA organizations. It generates a report with information about subscription entitlements including when they expire. It only outputs information for hosts in organizations that do not use SCA.
- To the right of the report template that you want to use, click Generate.
- Optional: To schedule a report, to the right of the Generate at field, click the icon to select the date and time you want to generate the report at.
- Optional: To send a report to an e-mail address, select the Send report via e-mail checkbox, and in the Deliver to e-mail addresses field, enter the required e-mail address.
- Optional: Apply search query filters. To view all available results, do not populate the filter field with any values.
- Click Submit. A CSV file that contains the report is downloaded. If you have selected the Send report via e-mail checkbox, the host monitoring report is sent to your e-mail address.
CLI procedure
List all available report templates:
# hammer report-template list
Generate a report:
# hammer report-template generate --id My_Template_ID
This command waits until the report fully generates before completing. If you want to generate the report as a background task, you can use the
hammer report-template schedule
command.NoteIf you want to generate a subscription entitlement report, you have to use the
Days from Now
option to specify the latest expiration time of entitlement subscriptions. You can use theno limit
value to show all entitlements.Show all entitlements
# hammer report-template generate \ --inputs "Days from Now=no limit" \ --name "Subscription - Entitlement Report"
Show all entitlements that are going to expire within 60 days
# hammer report-template generate \ --inputs "Days from Now=60" \ --name "Subscription - Entitlement Report"
10.2. Creating a Report Template
In Satellite, you can create a report template and customize the template to suit your requirements. You can import existing report templates and further customize them with snippets and template macros.
Report templates use Embedded Ruby (ERB) syntax. To view information about working with ERB syntax and macros, in the Satellite web UI, navigate to Monitor > Report Templates, and click Create Template, and then click the Help tab.
When you create a report template in Satellite, safe mode is enabled by default.
Procedure
- In the Satellite web UI, navigate to Monitor > Report Templates, and click Create Template.
- In the Name field, enter a unique name for your report template.
- If you want the template to be available to all locations and organizations, select Default.
- Create the template directly in the template editor or import a template from a text file by clicking Import. For more information about importing templates, see Section 10.5, “Importing Report Templates”.
- Optional: In the Audit Comment field, you can add any useful information about this template.
-
Click the Input tab, and in the Name field, enter a name for the input that you can reference in the template in the following format:
input('name')
. Note that you must save the template before you can reference this input value in the template body. - Select whether the input value is mandatory. If the input value is mandatory, select the Required checkbox.
- From the Value Type list, select the type of input value that the user must input.
- Optional: If you want to use facts for template input, select the Advanced checkbox.
- Optional: In the Options field, define the options that the user can select from. If this field remains undefined, the users receive a free-text field in which they can enter the value they want.
- Optional: In the Default field, enter a value, for example, a host name, that you want to set as the default template input.
- Optional: In the Description field, you can enter information that you want to display as inline help about the input when you generate the report.
- Optional: Click the Type tab, and select whether this template is a snippet to be included in other templates.
- Click the Location tab and add the locations where you want to use the template.
- Click the Organizations tab and add the organizations where you want to use the template.
- Click Submit to save your changes.
Additional resources
- For more information about safe mode, see Section 10.9, “Report Template Safe Mode”.
- For more information about writing templates, see Appendix A, Template Writing Reference.
- For more information about macros you can use in report templates, see Section A.6, “Templates Macros”.
- To view a step by step example of populating a template, see Section 10.8, “Creating a Report Template to Monitor Entitlements”.
10.3. Exporting Report Templates
You can export report templates that you create in Satellite.
Procedure
- In the Satellite web UI, navigate to Monitor > Report Templates.
- Locate the template that you want to export, and from the list in the Actions column, select Export.
- Repeat this action for every report template that you want to download.
An .erb
file that contains the template downloads.
CLI procedure
To view the report templates available for export, enter the following command:
# hammer report-template list
Note the template ID of the template that you want to export in the output of this command.
To export a report template, enter the following command:
# hammer report-template dump --id My_Template_ID > example_export.erb
10.4. Exporting Report Templates Using the Satellite API
You can use the Satellite report_templates
API to export report templates from Satellite. For more information about using the Satellite API, see API Guide.
Procedure
Use the following request to retrieve a list of available report templates:
Example request:
$ curl --insecure --user admin:redhat \ --request GET \ --config https://satellite.example.com/api/report_templates \ | json_reformat
In this example, the
json_reformat
tool is used to format the JSON output.Example response:
{ "total": 6, "subtotal": 6, "page": 1, "per_page": 20, "search": null, "sort": { "by": null, "order": null }, "results": [ { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Applicable errata", "id": 112 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Applied Errata", "id": 113 }, { "created_at": "2019-11-30 16:15:24 UTC", "updated_at": "2019-11-30 16:15:24 UTC", "name": "Hosts - complete list", "id": 158 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Host statuses", "id": 114 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Registered hosts", "id": 115 }, { "created_at": "2019-11-20 17:49:52 UTC", "updated_at": "2019-11-20 17:49:52 UTC", "name": "Subscriptions", "id": 116 } ] }
Note the
id
of the template that you want to export, and use the following request to export the template:Example request:
$ curl --insecure --output /tmp/_Example_Export_Template.erb_ \ --user admin:password --request GET --config \ https://satellite.example.com/api/report_templates/My_Template_ID/export
Note that
158
is an example ID of the template to export.In this example, the exported template is redirected to
host_complete_list.erb
.
10.5. Importing Report Templates
You can import a report template into the body of a new template that you want to create. Note that using the Satellite web UI, you can only import templates individually. For bulk actions, use the Satellite API. For more information, see Section 10.6, “Importing Report Templates Using the Satellite API”.
Prerequisite
- You must have exported templates from Satellite to import them to use in new templates. For more information see Section 10.3, “Exporting Report Templates”.
Procedure
- In the Satellite web UI, navigate to Monitor > Report Templates.
- In the upper right of the Report Templates window, click Create Template.
-
On the upper right of the Editor tab, click the folder icon, and select the
.erb
file that you want to import. - Edit the template to suit your requirements.
- Click Submit.
For more information about customizing your new template, see Appendix A, Template Writing Reference.
10.6. Importing Report Templates Using the Satellite API
You can use the Satellite API to import report templates into Satellite. Importing report templates using the Satellite API automatically parses the report template metadata and assigns organizations and locations. For more information about using the Satellite API, see the API Guide.
Prerequisites
Create a template using
.erb
syntax or export a template from another Satellite.For more information about writing templates, see Appendix A, Template Writing Reference.
For more information about exporting templates from Satellite, see Section 10.4, “Exporting Report Templates Using the Satellite API”.
Procedure
Use the following example to format the template that you want to import to a
.json
file:# cat Example_Template.json { "name": "Example Template Name", "template": " Enter ERB Code Here " }
Example JSON File with ERB Template:
{ "name": "Hosts - complete list", "template": " <%# name: Hosts - complete list snippet: false template_inputs: - name: host required: false input_type: user advanced: false value_type: plain resource_type: Katello::ActivationKey model: ReportTemplate -%> <% load_hosts(search: input('host')).each_record do |host| -%> <% report_row( 'Server FQDN': host.name ) -%> <% end -%> <%= report_render %> " }
Use the following request to import the template:
$ curl --insecure --user admin:redhat \ --data @Example_Template.json --header "Content-Type:application/json" \ --request POST --config https://satellite.example.com/api/report_templates/import
Use the following request to retrieve a list of report templates and validate that you can view the template in Satellite:
$ curl --insecure --user admin:redhat \ --request GET --config https://satellite.example.com/api/report_templates | json_reformat
10.7. Generating a List of Installed Packages
Use this procedure to generate a list of installed packages in Report Templates.
Procedure
- In the Satellite web UI, navigate to Monitor > Report Templates.
- To the right of Host - All Installed Packages, click Generate.
- Optional: Use the Hosts filter search field to search for and apply specific host filters.
- Click Generate.
- If the download does not start automatically, click Download.
Verification
- You have the spreadsheet listing the installed packages for the selected hosts downloaded on your machine.
10.8. Creating a Report Template to Monitor Entitlements
You can use a report template to return a list of hosts with a certain subscription and to display the number of cores for those hosts. For more information about writing templates, see Appendix A, Template Writing Reference.
Procedure
- In the Satellite web UI, navigate to Monitor > Report Templates, and click Create Template.
Optional: In the Editor field, use the
<%# >
tags to add a comment with information that might be useful for later reference. For example:<%# name: Entitlements snippet: false model: ReportTemplate require: - plugin: katello version: 3.14.0 -%>
Add a line with the
load_hosts()
macro and populate the macro with the following method and variables:<%- load_hosts(includes: [:lifecycle_environment, :operatingsystem, :architecture, :content_view, :organization, :reported_data, :subscription_facet, :pools => [:subscription]]).each_record do |host| -%>
To view a list of variables you can use, click the Help tab and in the Safe mode methods and variables table, find the Host::Managed row.
Add a line with the
host.pools
variable with theeach
method, for example:<%- host.pools.each do |pool| -%>
Add a line with the
report_row()
method to create a report and add the variables that you want to target as part of the report:<%- report_row( 'Name': host.name, 'Organization': host.organization, 'Lifecycle Environment': host.lifecycle_environment, 'Content View': host.content_view, 'Host Collections': host.host_collections, 'Virtual': host.virtual, 'Guest of Host': host.hypervisor_host, 'OS': host.operatingsystem, 'Arch': host.architecture, 'Sockets': host.sockets, 'RAM': host.ram, 'Cores': host.cores, 'SLA': host_sla(host), 'Products': host_products(host), 'Subscription Name': sub_name(pool), 'Subscription Type': pool.type, 'Subscription Quantity': pool.quantity, 'Subscription SKU': sub_sku(pool), 'Subscription Contract': pool.contract_number, 'Subscription Account': pool.account_number, 'Subscription Start': pool.start_date, 'Subscription End': pool.end_date, 'Subscription Guest': registered_through(host) ) -%>
Add end statements to the template:
<%- end -%> <%- end -%>
To generate a report, you must add the
<%= report_render -%>
macro:<%= report_render -%>
- Click Submit to save the template.
10.9. Report Template Safe Mode
When you create report templates in Satellite, safe mode is enabled by default. Safe mode limits the macros and variables that you can use in the report template. Safe mode prevents rendering problems and enforces best practices in report templates. The list of supported macros and variables is available in the Satellite web UI.
To view the macros and variables that are available, in the Satellite web UI, navigate to Monitor > Report Templates and click Create Template. In the Create Template window, click the Help tab and expand Safe mode methods.
While safe mode is enabled, if you try to use a macro or variable that is not listed in Safe mode methods, the template editor displays an error message.
To view the status of safe mode in Satellite, in the Satellite web UI, navigate to Administer > Settings and click the Provisioning tab. Locate the Safemode rendering row to check the value.