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 printable form. It is a compilation of different elements (table views, availability tables, history graphs, body text, logos) into a printable PDF document.

Example of a report.

Reports in Checkmk are easy to use:

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

  • The PDF file is cleanly created with vector graphics.

  • Reports can be managed using templates and inheritance.

  • The report scheduler sends reports periodically on demand.

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

  • Views can be exported as PDF at any time

Expanded 'Export' menu with the entry for PDF creation.

2. Pre-built reports in Checkmk

The CEE Checkmk Enterprise Editions provide some pre-built reports. You can either use these directly to get reports from Checkmk, or use them as templates for own reports at any time.

2.1. Contents and usage

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

Which reports are available?

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

Some of the prefabricated reports image::reporting_list.png[alt="List of reports."]

On the left side, the following icons are available for editing:

Icon for copying a report.

Copy report.

Icon to create a report preview.

View preview.

Symbol to open report scheduler.

Open report scheduler.

2.2. Launching reports

Reports can be launched at various points in Checkmk, depending on their context and purpose. For example, designated reports can be called from the main menu.

Selecting reports from the main menu.

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

View of reports in Export menu.

Quick access to reports - Snapin reporting in sidebar

The snapin reporting in the sidebar gives you quick access to all reports that have been designated for display in the main menu and sidebar, and the report scheduler (scheduler):

You can add the quick access to the sidebar. image::reporting_sidebar.png[alt="Snapin 'Reporting' in the sidebar.",width=45%]

There are three buttons in this snapin:

Change Timerange

Change Timerange for Instant Reports

Scheduler

Open report scheduler

Edit

Open list of existing reports

Context for reports

To give reports a context, i.e. to fill them with data of specific hosts and services, there are several possibilities. As a result, reports have to be called in different ways to contain meaningful information. If the context is missing, i.e. specifying which hosts and services should be included in the report, you will only get error messages highlighted in red instead of correct output:

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, it is always filled with correct information.

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

Output of a report with specified data.

Now think again about the snapin Reporting mentioned above: this takes you directly to the rendered reports without any further preselection / restriction etc. - so actually only those reports that have a built-in context make sense here.

Reports whose context is only created via (filtered) views can therefore be safely excluded from the main menu as well as the snapin via the Hide this report in the monitor menu option.

Selection to hide the report in the main menu and snapin.

2.3. Create your own reports - basics.

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.

Create a first custom report

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 to copy a report. in front of the report service_availability will take you to the basic settings of your report copy:

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. Now, once you click Add filter, you can select the appropriate host from the list of hostnames:

Selecting the appropriate host for the report.

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

View of custom report.

Editing functions

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

icon clone

Copy report

icon delete

Delete report

icon edit

Edit report settings

button report element lo

Edit report contents

icon pdf

Display previews

icon reportscheduler

Schedule regular report

A description of the different possibilities follows in the subsequent chapters.

Create 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 report copy. As an example, below you will create a simple overview of all problematic services of your instance, i.e. all services in 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 selection No restrictions to specific objects and go directly to the next selection with Icon to continue. Continue.

Keep selection 'No restriction to specific objects'.

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

Assigning unique ID and title for the new report.

In the Context / Search Filters section, now select the Service states under Service. After clicking Add filter you can set the desired states:

Selecting service states for the report.

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

View custom report in overview.

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 …​

Amnview of the 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 content definition for 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 the selection All services and Step 3 to the selection No restrictions to specific objects. Leave the other options on the following page unchanged for the moment. Instead, click directly on icon to save. Save. Now view the preview of your report:

View first custom element.

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

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

2.4. 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 for achieving 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 step.

The many possibilities can best be shown with an example.

.

Set basic settings

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

In the first step, you can set a filter and limit the report to a specific host or data source from the start, such as network interfaces, BI aggregates, 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, enter the Unique ID and the Title again. 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, extensive filtering options are available as usual, from specific hosts to individual Docker containers to values from Oracle monitoring.

Selection for report content design.

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 content.

Define report content

Using the button report element lo you get to the content design.

Calling content design.

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 page elements can be found in the overview of content and page elements.

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 one below the other. For example, you can map the direct comparison between the states of multiple hosts.

Selecting a graph.

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

Data source selection.

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

Setting various properties.

For the sample report, in the Properties box, under Graph layout, specify that you want to see a title for each of the graphs, consisting of the graph 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 usage for the Service this time.

By clicking icon to save. Save you have completed the first report element.

For the second graph in the example, start again with Reports > Add content and in Step 1 select Metrics graph of a single service. Switch to Step 2 with icon to skip. Continue and restrict the search filters to host and service description:

Selecting host and service description.

By clicking icon to save. Save the second report element is ready.

The third element you create is an overview of current alerts. The procedure remains the same:

  • Call Reports > Add content.

  • Step 1: Selection of the element Availability table

  • Step 2: Data source Alert Statistics

  • Step 3: Restrict to Restrict to a single host

  • no further options in the following step

With a click on icon to save. Save this report element is also finished.

To make the display cleaner, 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 to skip. Continue. Optionally, specify a hierarchy level for the heading. Enter the heading at The text.

Entering the heading.

Click Icon to save. Save to return to the overview. However, the new heading is now below the graphics in the order. Therefore, click the corresponding icon drag in the list of content items and move 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 much easier.

Editing view of the report without red elements.
Visual design of the report

To structure the report, there are complementary design elements: Horizontal line, image, page frame and a single line of text. You can display these building blocks on all or specific pages of 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 to skip.. Start with Reports > Add page element.

Frame selection.
For a listing of all page elements, see overview of content and page elements.

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

Selection of placement.

The new page border 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 number and 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:

.

Customize the layout

Reports look more appealing right away with a higher-quality appearance, e.g. with the company logo added.

Open the report settings with Reports > Edit properties:

Selecting the 'Edit properties' option.

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

At this point you can specify basic design features image::reporting_report_properties2.png[alt="Report layout preferences form."]

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, e.g. to reflect the company’s corporate design.

Insert 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 to continue. Continue. (A listing of all elements)

Dialog for selecting an image element.
For a listing of all page elements, see overview of content and page elements.

The following dialog is used to set detail settings such as position, filename and size.

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

When you are done with all settings, save with icon to save. Save. After that you will get to the report overview and see the inserted image in the report.

View of report header with custom logo.

2.5. Schedule 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.

Send a report regularly

Open a new schedule using Scheduled reports > Add schedule, then select the report and click icon to continue. 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 via PDF on Friday afternoons.

Under Context / Search Filters you will find the usual filter options, depending on the selected report. Then save the report 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 (slightly shortened here):

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

Entries in the list are managed using the five icons at the top of the list:

icon edit

Edit report settings

icon clone

Copy report settings

icon delete

Delete scheduled report

icon pdf

Create report

icon pdfpreview

Display preview

Note: Sent reports are not stored in the instance.

Store a report locally on a regular basis.

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

Parameters for storing a report locally.

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

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.

2.6. Global defaults for reports

Some basic settings for reports can be set globally, for example to create and manage a corporate design centrally. Settings for an individual report then only specify the deviations from the corporate design. You configure the global settings for reports via Setup > General > Global settings > Reporting.

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

2.7. Create your own report template

Checkmk provides a pre-built, 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:

Selection from list of reports.

To create your own report template, copy the default template using icon to copy. First, change Unique ID and Title.

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

Specify as a report template.

From the first save, you will then find this template in the custom report templates:

Selection of report template in the 'Customized' box.

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 report template.

Your report will always be created with this template in the future from the time you save it.

3. Supplementary information

3.1. Content and page elements

content elementfunctionoptions

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

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

Design elementFunctionPossibilities

A frame around the page

selectively 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 on specific pages, position, color and thickness can be specified

One line of text

3.2. Available macros

Macro nameContent

$FROM_TIME$

Report start time

$NOW_TIME$

current time

$UNTIL_TIME$

End time of the report

$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 ID

$USER_ID$

User ID

$OMD_SITE$

Name of the instance

$REPORT_NAME$

Name of the report

4. Files and directories

path/filemeaning

var/check_mk/web/ID_of_the_owner/user_reports.mk

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

On this page