Checkmk
to checkmk.com

1. What are reports?

CEE A report in Checkmk is intended to provide an overview of the data, content, and state in Checkmk in a printable form. It is a compilation of various elements (views, availability tables, graphs, body text, logos) into a printable PDF document.

Example of a report.

Reports in Checkmk are easy to use:

  • No external tools such as Jasper, DB or similar are needed.

  • The PDF file is cleanly created, including vector graphics.

  • Reports can be managed using templates and inheritance.

  • Use the report scheduler to define reports to be sent periodically.

  • Instant reports can be generated via Export > This view as PDF.

Expanded 'Export' menu with the entry for PDF creation.
Views can be exported as PDF documents at any time

2. Checkmk’s built-in reports

The Checkmk commercial editions provide some built-in reports as standard. You can either use these as predefined to get reports from Checkmk, or use them as templates for customizing own reports as required.

Just like views and dashboards, reports supplied in Checkmk cannot be modified. But you can clone/copy any existing reports as many times as you like, then modify each to suit your needs. The procedure for creating simple as well as complex reports is described below.

An overview of all reports in Checkmk, built-in and custom, can be found at Customize > Business reporting > Reports (you may need to click show more first):

List of reports.
Some of the built-in reports

On the left side at each line, the following icons are available for the editing functions:

Icon for copying a report.

Clone report

Icon for creating a report preview.

View preview

Icon for opening the report scheduler.

Open report scheduler

3. Launching reports

Reports can be launched from various points in Checkmk, depending on their context and purpose. For example, the appropriate reports can be called from the navigation bar in the Monitor menu.

Selecting reports from the navigation bar.

Contextually, you can find the reports in the Export menu of the various views:

List of reports in Export menu.

In the sidebar the Reporting snap-in gives you quick access to all reports that have been designated for display in the Monitor menu and sidebar, as well as the report scheduler:

'Reporting' snap-in in the sidebar.
The Reporting snap-in can be added to the sidebar

There are three buttons in this snap-in:

Change Timerange

Change the time range for instant reports

Scheduler

Open the report scheduler

Edit

Open the list of existing reports

3.1. Context for reports

There are a number of options for giving reports a context, i.e. to fill them with the data from specific hosts and services. As a result, reports have to be called in different ways in order to contain meaningful information. If the context is missing, i.e. specifying which hosts and services should be included in the report, instead of the correct output you will receive only error messages highlighted in red:

Output of a report with unspecified data.

The difference is where the context is specified:

  • Context specified (via report properties): The report can be called from anywhere and it will always be filled with the correct information.

  • Context not given: Call made via the Export menu in the various views, context is provided by the (filtered) view.

Output of a report with specified data.

Now think again about the Reporting snap-in mentioned above: this takes you directly to the rendered reports without any further preselection / restriction etc. — so only those reports that have a built-in context actually make sense here. Reports whose context is only created via (filtered) views can therefore be safely excluded from the Monitor menu as well as the snap-in via the Hide this report in the monitor menu option.

Selection to hide the report in the main menu and snap-in.

4. Creating a first custom report

Based on the existing reports and report templates, you can create your first custom report relatively quickly and easily. We will explain how to do this in a moment. More in-depth information around more complex reports will follow below in the text.

The fastest way to create a report is to copy an existing report and then customize it. For example, if you want to create an overview of the availability of services on a specific host, the host named mycmkserver, do the following.

First, open the report overview with Customize > Business reporting > Reports:

Selection from the list of reports.

Clicking Icon for cloning (copying) a report. (clone) in front of the report service_availability will take you to the basic settings for your new report based on the existing report:

Entering the basic settings of a report.

Enter the desired texts for Unique ID and Title. We won’t deal with the other options in this box, as well as the Report Properties, until we get to the more complex reports.

For now, it’s enough to scroll down to the Context / Search Filters box. For Host, select Hostname. Next click Add filter, to select the appropriate host from the list of host names:

Selecting the appropriate host for the report.

Click Icon for saving. to save your new report and to return to the reports overview page. In the section Customized you can now directly access your new report by clicking on its title:

View of custom report.

4.1. Editing functions

You can use the following functions to edit your own reports:

icon clone

Clone (copy) report

icon delete

Delete report

icon edit

Edit report settings

button report element lo

Edit report contents

icon pdf

Display preview

icon reportscheduler

Schedule regular report

A description of the various available options follows in the subsequent sections.

4.2. Creating a new report without a template

Things get a little more complex now if you want to create a completely new report instead of a copy of an existing report. As an example, below you will create a simple overview of all problematic services on your site, i.e. all services with a WARN, CRIT or UNKNOWN status. This overview will be titled ‘critical_services‘.

You create a new report on the Edit Reports page via Reports > Add report.

Open a new report.

In the first step, leave the filter Select specific object type on the No restrictions to specific objects selection and go directly to the next selection page with Icon for continuing. Continue.

Keep selection 'No restriction to specific objects'.

As with copying an existing report, first specify a Unique ID and Title:

Assigning unique ID and title for the new report.

In the Context / Search Filters section, under Service now select the Service states, then with a click on Add filter you can set the desired states:

Selecting service states for the report.

With Icon for saving. Save & go to list the new report will be added to the Customized section of the reports overview list.

List of reports with the created own report.

If you now call up this report in joyful anticipation, the result is sobering. The report page has an initial layout and also a heading, but is otherwise empty. Not exactly the result to impress your boss with …​

Empty report.

So now you need to define the design of the content for the report. The Icon for editing the report content. will take you to the page for defining the content to be included in the report. The selection of report elements is done in three stages, each with a click on Symbol for proceeding in the process. Continue in between.

Start by clicking Add content. For this example in Step 1 select the element type Availability table. Set Step 2 to All services and Step 3 to No restrictions to specific objects. Leave the other options on the following page unchanged for the moment. Instead, click directly on Icon for saving. Save. Now view the preview of your report:

Preview the report with the added content.

On the left you can see the preview, here for the report of critical_services. To the right, the elements of the report are displayed in a list. These elements can be icon edit edited, icon clone copied, icon delete deleted and icon drag reordered.

You can now flexibly customize this simple, self-created report with additional elements as required (see below) and call it up at any time, e.g. from the sidebar.

5. Building complex reports

In the previous sections you have seen how to create initial reports with little effort, either as a copy of an existing report or completely new. These are great ways to achieve initial success. Most of the time, however, it doesn’t stop at such simply structured reports. More complex presentations, a mixture of different content, a custom layout, etc. are the next logical steps.

The many possibilities can best be shown with an example:

reporting complex report

5.1. Defining the basic settings

In almost every step of the report creation there is the possibility to adjust the content to suit your needs.

In the first step, at the start you can set a filter and limit the report to a specific host or data source, such as network interfaces, BI aggregations, sensors, and so on:

List of filters to restrict the report.
Most of the time, however, you will not need the filters at this level

Next, again enter the Unique ID and the Title. For the title you can also use the provided macros (= text modules). Next, choose a Icon with which the report should be visible in the menus. By setting the Make this report available for other users option to the contact group, in the example check-mk-notify, you give the associated group members the ability to independently access the report at any time and get information on their own.

Setting the more complex basic properties for the report.

In the Context / Search Filters box, as usual extensive filtering options are available, from specific hosts to individual Docker containers to values from Oracle monitoring.

Selection for report content.

For this example, the host selection is limited to one folder and additionally to specified host issues. This restriction speeds up data retrieval, especially in more complex environments.

With Save & go to list you get to the report overview. The next step is to define the report’s content.

5.2. Defining report content

Using the button report element lo you get to the report content:

Calling report content.

Open report content editing with Reports > Add content. Use this to add tables, graphs, tables of contents, or text (also via macros or HTTP) to the report, for example. These contents appear one after the other and thus also determine the final length of the report.

Adding a content element.
A list of all content elements can be found at the end of this article

In Step 1, select the element you want, for this example Multiple graphs. This will give you, depending on your other settings, multiple graphs of the same type arranged one below the other. For example, you can map a direct comparison between the states of multiple hosts.

Selecting multiple graphs.

Continue with Icon for proceeding. Continue. As the data source for the graphics, for this example, in step 2 select All services, i.e. all services running on the hosts:

Selecting the data source.

Continue with Icon for proceeding. Continue. In step 3 you could now limit the volume of data to be displayed. This option is not needed for the current example. Again, switch to the next selection with Icon for proceeding. Continue.

Setting various properties.

For the sample report, under Graph layout, in the Properties box, specify that you want provide a title for each of the graphs, consisting of the graph’s title, host name, and service description. In addition, set the displayed time range to four hours under Graph time range.

In the Context / Search Filters box, you limit the report to specified host or service characteristics. Here you select the CPU utilization for the Service in this example.

By clicking Icon for saving. Save you have completed the first report element.

For the second graph in this exercise, start again with Reports > Add content and in Step 1 select Metrics graph of a single service. Switch to Step 2 with Icon for proceeding. Continue and restrict the search filters to host name and service description:

Selecting host name and service description.

By clicking Icon for saving. Save the second report element will now also be ready.

The third element to be created is an overview of the current alerts. The procedure remains the same:

  1. Call Reports > Add content

  2. Step 1: Select the Availability table element

  3. Step 2: Data source Alert Statistics

  4. Step 3: Restrict to a single host

  5. No further options in the following step

With a click on Icon for saving. Save this report element is also finished.

To make the display clearer, add headings:

Open Reports > Add content to edit the report content. In Step 1 select Heading as element type. Switch to Step 2 with Icon for proceeding. Continue. Optionally, specify a hierarchy level for the heading. Enter the heading at The text.

Entering the heading text.

Click Icon for saving. Save to return to the overview. However, the new heading will now be positioned below the graphics in the list. So, in the list of content items, use the Icon for moving elements. icon to drag the heading to the desired position in the list.

Editing view of the report with red elements.

Tip: In the preview, you may see red lines and error messages instead of real data — because in these places the report in the editor lacks context, here, for example, the specification of a host that would only be revealed by calling the report from an appropriate view. If you want to see a usable preview, simply filter for a specific host in the report settings in the Context / Search Filters area in the meantime. This makes designing the report much easier.

Editing view of the report without red elements.

5.3. Visual design of a report

There are complementary design elements available for structuring the appearance of the report, such as horizontal line, image, page frame and a single line of text. You can display these building blocks on all or specific pages in your report.

For the example report, insert a frame around the report. Again, the definition is done step by step, each continued by clicking Icon for proceeding.. Start with Reports > Add page element.

Frame selection.
A list of all available page elements can be found at the end of this article

Since the frame should be visible on all pages, the next step requires no changes:

Selection of element placement.

The new page frame is now displayed in the overview, both in the preview on the left and in the static page elements table on the right.

Current overview of the report.

Tip: You can also use the macros (=text modules) available in Checkmk, for example, to create another footer with page numbers and the name of the report. To do this, select the page element One line of text and in the second step specify the position at the bottom of the page as well as the text including the desired macros:

Setting the footer.

5.4. Customizing the layout

Right away reports look more appealing with a higher-quality appearance, for example, with the company logo added.

Open the report settings with Reports > Edit properties:

Selecting the report settings.

In the second box, you will find the Report Properties. This is where you configure values for font, page format, time and date settings, report layout, and file name for downloads.

Report layout preferences form.
At this point you can specify basic design features

Copy your company logo to the ~/local/share/check_mk/reporting/images/ directory and save it as logo_mk.png file. From now on this logo will be displayed on all reports.

View of report header with custom logo.

Note: Currently, you customize the existing report template to suit your needs. Alternatively, you can create a complete, new report template according to your company specifications, to reflect the company’s corporate design (CI/CD), for example.

Inserting an additional image

Images that you want to use as design elements in your reports must have been previously stored in the ~/local/share/check_mk/reporting/images/ directory.

Click the Add page element button in the report creation.

Call to select image elements.

In the following Step 1, select Embedded image as type and continue with Icon for proceeding. Continue.

Dialog for selecting an image element.
A list of all available page elements can be found at the end of this article

The following dialog is used to specify more detailed settings such as position, file name and size.

Dialog for image properties.
Sizes in millimeters for easy print design

When you are done with all settings, save with Icon for saving. Save. After that the report overview will be displayed and will see the image inserted into the report.

View of report header with custom logo.

6. Scheduling a report

You can use the report scheduler to have existing reports created and sent automatically. You can reach the scheduler on the Edit Reports page via Reports > Scheduler.

6.1. Sending a report on a regular basis

Open a new schedule using Scheduled reports > Add schedule, then select the report and click Icon for proceeding. Continue.

In the General Options box, you specify basic settings such as title, creation time, reporting period, and so on:

Report scheduler settings.
For example, you can have a weekly report automatically sent to you as a PDF on Friday afternoons

Under Context / Search Filters you will find the usual filter options, depending on the selected report. Then save the schedule to return to the list of your scheduled reports.

In the list you will also find information about the last time the report was generated/sent, if there was an error, when it will be generated/sent the next time and some more information (shown slightly abbreviated here):

List of scheduled reports.
A scheduled report with detailed, here slightly abbreviated, information

Entries in the list are managed using the five icons at the beginning of an entry:

icon edit

Edit report settings

icon clone

Copy report settings

icon delete

Delete scheduled report

icon pdf

Create report

icon pdfpreview

Display preview

Note: Reports that have been sent are not stored on the site.

6.2. Storing a report locally on a regular basis

Instead of sending the report, you can also store it locally. To do this, select Action - Store locally:

Parameters for storing a report locally.

Next specify a file name and optionally a report title. To be able to build a history of reports — Checkmk provides various macros (= text modules) instead of overwriting the previous report version every time the report is newly created.

The overview of all locally stored reports can be accessed in the Edit Reports window via the Reports > Stored reports menu item:

Calling stored reports.

7. Global defaults for reports

Some basic settings for reports can be defined globally, for example to create and manage a corporate design (CI/CD) centrally. Settings for an individual report then only specify any deviations from the corporate design. The global settings for reports can be configured via Setup > General > Global settings > Reporting.

Global settings for reports.
Settings such as templates and font sizes can be defined globally

8. Creating your own report template

Checkmk provides a built-in, clear report template that you can add to and use as you wish, as described above. However, especially reports that are passed on to management look even better if they correspond to your own company layout. For this purpose, there is an option to create your own report template.

By default, the Default template for all reports is used for all reports in Checkmk:

The standard template in the report list.

To create your own report template, copy the default template using Icon for copying. First, give the new template a Unique ID and Title.

To mark this report template as such, in the Report Properties box check This is a front matter Template:

Specify as a report template.

Following the first save, you will find this new template in the custom report templates list:

List of report templates.

Now you can customize this template according to the above descriptions, just like any other report. Change the page layout, font, line colors, etc. Also set the content elements at the same time. Exclusively for report templates there is also the report element Table of Contents:

Table of Contents selection.

To create one of your reports now with the new template, change the settings in the report’s Report Properties one more time. Set the Use settings and page layout from option to the name of your new template:

Change the report template.

Once this template has been saved, future reports will always be based on it.

9. Supplementary information

9.1. Content elements

Content elements are listed when you select Reports > Add content when editing a report.

Element Function Options

A Multisite view

Complex view on definable topic

Multilayer selection

Availability table

List of availability states

Selection of data source and further restrictions of data possible

Combined graph

Graphs based on multiple data series

Use of a template, selection of data source and various layout settings possible

Custom Graph

Individually created graphs

Standard layout options

Embedded image

Static image

Size can be specified. The position of this image is dynamic, relative to surrounding content elements.

Forecast Graph

Forecast view

Specify hosts, services and time periods to be considered

Graph collection

All graphs in a collection

Default layout options

Heading

Heading in headers of different hierarchies possible

Host report for multiple hosts

Status reports for multiple hosts

Definition of sub-reports to be included including structuring

Metrics graph of a single service

Metrics of a single service as graph

Standard layout options

Multiple graphs

Collection of multiple graphs on a single topic

Selection of data source, different design features of the graphs

Page break

Paragraph of text

Static text

The position of this text is dynamic, relative to surrounding content elements.

Service report for multiple services

Service report collection for multiple services

Default of sub-reports to be included, different design features of individual reports

Table of available text macros

Overview of all available macros

Name and current output of the macros are displayed

Table of Contents (only active in frontmatter templates)

Table of contents

Only active in report templates

Vertical space

Free space

Height as well as behavior at the top of a page can be defined

9.2. Page elements

Page elements are listed when you select Reports > Add page element when editing a report.

Element Function Options

A frame around the page

Frame around the entire page

Optionally around all or specific pages

Embedded image

Static image

Optionally on one or on specific pages. Position and size can be specified. This image does not move with the report content.

Horizontal rule

Horizontal line

Optionally on all or specific pages. Position, color and thickness can be specified.

One line of text

Static line of text

Optionally on all or specific pages. Position and font properties can be specified.

9.3. Available macros

Name Content

$FROM_TIME$

Report start time

$NOW_TIME$

Current time

$UNTIL_TIME$

Report end time

$FROM_EPOCH$

Start time of the report in Unix time

$NOW_EPOCH$

Current time in Unix time

$UNTIL_EPOCH$

End time of the report in Unix time

$CHECK_MK_VERSION$

Current Checkmk version

$NOW_DATE$

Current date

$FROM_DATE$

Start date of the report

$UNTIL_DATE$

End date of the report

$FROM$

Report start date and time

$NOW$

Current date and time

$UNTIL$

End date and time of the report

$PAGE$

Number of pages

$REPORT_TITLE$

Title of the report

$RANGE_TITLE$

Time period of the report

$USER_ALIAS$

User account

$USER_ID$

User ID

$OMD_SITE$

Name of the site

$REPORT_NAME$

Name of the report

10. Files and directories

File path Description

~/var/check_mk/web/[owner_id]/user_reports.mk

These files store the customized and newly created reports of the respective Owner of the reports.

~/local/share/check_mk/reporting/images/

Directory for storing custom images to be used in reports.

On this page