We use cookies to ensure that we give you the best experience on our website.  Visit our Privacy Policy to learn more. If you continue to use this site, we will assume that you are okay with it.

Your choices regarding cookies on this site.
Your preferences have been updated.
In order for the changes to take effect completely please clear your browser cookies and cache. Then reload the page.

Writing your own check plug-ins

This article is just a draft and not yet finished!

1. Introduction

Checkmk includes nearly 2000 ready-made check plug-ins for all imaginable hardware and software. These are maintained by the Checkmk team, and new plug-ins are added every week. On the Checkmk-Exchange there are also more plug-ins contributed by our users.

And yet there are always situations where a device, an application, or just a specific metric that is important to you is not covered by any of these plug-ins - maybe because it is something that was developed within your own company and is therefore not available to anyone else.

1.1. Does it always have to be a real plug-in?

What options do you have for implementing an effective monitoring here? Well - you could of course contact our support team and request that they develop a suitable plug-in for you - but naturally it's quicker if you can do it yourself. You have three options:

Method How to do it Advantages Disadvantages
Localcheck Extend a Checkmk Agent with a simple script Is very simple, is possible in all programming languages offered by the monitored host’s operating system, even supports service detection Threshold configuration only for the agent itself, SNMP not possible or very cumbersome
Nagios-compatible check plug-in Run the plug-in via MRPE from the Windows or Linux agent. Access to all existing Nagios plug-ins, also free choice of the programming language Threshold configuration only for the agent itself, SNMP not possible or very cumbersome, no service discovery possible
Genuine Checkmk plug-in Explained here in the manual Inserts itself 100% into Checkmk, automatic service recognition, central configuration of the thresholds via WATO, very high performance, supports SNMP, automatic host and service labels possible, supports HW/SW inventory, Checkmk provides a lot so you do not have to program standard functions yourself. Only a real plug-in has a chance to become part of the official Checkmk. Requires more training and knowledge of the Python programming language
log messages Monitor messages with the Event Console No development necessary, but only need to set up rules in the Event Console All of the disadvantages of event-based monitoring compared to state-based: no current status, no metrics, no configurable thresholds - you do not know for sure whether any messages actually be received.

This article will show you how to develop real Checkmk check plug-ins - along with everything that goes with them. Here we show you how to use the newly-developed API for programming plug-ins in version 1.7.0 of Checkmk. If you want to develop plug-ins that will work on legacy Checkmk versions you can refer to previous manuals. However these have not been maintained for some time and are only available in English.

1.2. Different types of check plug-ins

Before we jump into action, let's first review the different types of check plug-ins that CMK works with:

Agent-based The ‘normal’ plug-ins evaluate data that the Checkmk agent sends for Linux, Windows or other operating systems. This agent monitors operating system parameters and applications, and sometimes also server hardware. Each new check plug-in requires an extension of the agent to provide the necessary data. Therefore you first develop an agent plug-in, and then one or more check plug-ins that evaluate this data.
SNMP When monitoring via SNMP you do not need an extension of an agent, but evaluate the data that your device retrieves data from your device via SNMP, which provides this by default. Checkmk supports you and takes over all details and special features of the SNMP protocol.
Special Agent You need a special agent if you do not receive the data that is relevant for monitoring from either the normal Checkmk agent or SNMP. The most common application for Special Agent is querying HTTP-based APIs. Examples are, e.g. Monitoring AWS, Azure, or VMware. In this case you write a script that runs directly on the Checkmk server, connects to the API, and outputs data in the same format as an agent plug-in would. For this you write suitable check plug-ins in the same way as with the ‘agent-based’ monitoring.
Active Check This check type forms a special role. Here you first write a classic Nagios-compatible plug-in which is intended for execution on the Checkmk server, and which from there uses a network protocol to directly query a service on the target device. The most prominent example is the check_http plug-in which allows you to monitor web servers and web pages. You can then integrate this plug-in into Checkmk so that it can be set up as usual via WATO.

1.3. Prerequisites

If you feel like programming check plug-ins, you need to satisfy the following prerequisites:

  • Knowledge of the Python programming language, or at least experience in a similar language (such as PHP, Ruby, Java, etc.), along with the desire to become familiar with Python.
  • Experience with Checkmk, especially with regard to agents and checks
  • Experience with Linux on the command line

As preparation, the following articles are recommended:

1.4. Steps to your own plug-in

Typically, there are the following phases that you go through when writing your own plug-in:

  1. Getting data: Find out how to actually get the status data you want to monitor. Which command line commands, SNMP paths or API calls provide the necessary raw data? That is sometimes the hardest job.
  2. Extending the agent: You now write a plug-in for the agent with the correct commands — or a special agent to get the API. SNMP eliminates this step.
  3. The Check plug-in: Now write the actual check plug-in which analyzes the data and, based on this, recognizes services and generates their status.

If that works, you are done — but you can also extend the whole process with several additional features:

  • Definitions of the metrics provided by the services to produce beautiful and well-labelled graphs and perf-o-meters.
  • A set of rules for WATO that you can use to configure check plug-in parameters.
  • A ruleset for WATO that configures the agent plug-in for the Agent Bakery.
  • A ruleset for WATO that configures the special agent.
  • A manual page that documents the check plug-in for the user.

2. This article is not finished yet

Now you are probably wondering why this article ends here. The main reason is that we are currently working on a major overhaul and improvement of the programming API for check plugins. As soon as it is finalized, we will rewrite this article – and many more articles on programming extensions. The plan is that this will be finished with the release of Checkmk version VERSION [1.7.0].

Until then, we ask for a little patience!