Debugging special agent

Hi all,

I am learning of how to write a special plugin and interested in viewing stdout from a sample special plugin. The special plugin I used as an example here is azure_ad. But when I tried either commands “cmk --debug -vvII --no-cache localhost” or “cmk --debug -vv --no-cache localhost” not seeing any output from the console. What I did is add extra print(“something”) block in the code. I can get the output from check plugin, wato plugin but not the special plugin unless I execute the sepcial plugin directly from the console.
For example:
Wato plugin: /omd/sites/test/lib/python3/cmk/gui/plugins/wato/special_agents/azure.py
Check plugin: /omd/sites/test/share/check_mk/checks/agent_azure
Special plugin: /omd/sites/test/lib/python3/cmk/special_agents/agent_azure.py

Is there any good documents for writing a special plugin and the process flows as the document Writing agent-based check plug-ins is very basis not enough for me, also it is for agent-based plugin.

A special agent is its own program that outputs agent data.
You always can call a special agent directly. Usually they also have --debug as option.

Run cmk -D HOSTNAME | head -15 to see the invocation of a special agent for a specific host.

2 Likes

When working with Checkmk special plugins, debugging and logging can be a bit tricky due to how the framework handles the execution and output of these plugins. Here’s a more detailed approach to help you understand the process and debug your special plugin effectively:

Understanding Special Plugins in Checkmk

Special plugins in Checkmk are typically used to gather data from external sources, such as APIs. They are often executed by the Checkmk service and their output is processed to create check results. Unlike standard check plugins, special plugins may not produce output directly to stdout in the way you’re expecting.

Debugging Techniques

  1. Direct Execution: As you mentioned, running the special plugin directly from the console will show its output:
/omd/sites/test/lib/python3/cmk/special_agents/agent_azure.py

This is useful for immediate debugging but does not simulate the full Checkmk execution environment.
2. Modify the Plugin for Debugging: To get output during a full Checkmk run, you can temporarily modify the plugin to write to a log file instead of (or in addition to) printing to stdout. Here’s how you can do this:

import logging

logging.basicConfig(filename='/tmp/agent_azure_debug.log', level=logging.DEBUG)

def your_function():
    logging.debug("Debug message")
    # rest of your code

This way, you can check the /tmp/agent_azure_debug.log file for your debug messages.
3. Use Checkmk Debug Options: The cmk command has debug options, but they might not catch all the output from special plugins. Ensure you use both -vv and --debug flags together:

cmk --debug -vvII --no-cache localhost
cmk --debug -vv --no-cache localhost

These commands increase verbosity and enable debug mode, but output from the plugin itself might still be missed unless explicitly captured.

Documentation

Unfortunately, documentation for writing special plugins is sparse compared to agent-based plugins. However, here are some resources and steps you can follow:

  1. Existing Special Plugins: Examine existing special plugins within the Checkmk codebase. These can serve as examples of best practices and typical structures.
  2. Checkmk Development Guide: Although you mentioned the guide is basic, it is still a good starting point. It might be beneficial to re-examine it with a focus on understanding the flow and framework conventions:
  • Checkmk Agent-based Plugins Guide
  1. Checkmk Mailing Lists and Forums: Engage with the Checkmk community. The mailing lists and forums can be valuable resources for getting specific questions answered:
  • Checkmk Community
  1. Source Code Exploration: If you have access to the Checkmk source code, exploring how other special agents are implemented can provide insights:
  • Look into /opt/omd/versions/default/lib/python/cmk/special_agents/
1 Like

Thanks boomlau, I also confused between the check_info and special_agent_info from the base class cmk.base.config. Do we need to register the agent rule for special plug-in same as agent-based plugin using register.agent_section and register.check_plugin?