integrate notification support both in the guide and in the mkp builder

Author: oetiker

CHANGES.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### New
+- Add notification plugin support to mkp-builder (collects from `local/share/check_mk/notifications/`, creates `notifications.tar`)
+- Add notification plugin development guide (14-notifications.md) covering Discord/webhook examples, environment variables, testing
 
 ### Changed
 

README.md

@@ -165,8 +165,11 @@ repository/
 │   │   │           └── your_plugin_bakery.py
 │   │   └── cmk/base/cee/plugins/bakery/
 │   │       └── your_plugin.py
-│   └── share/check_mk/agents/plugins/
-│       └── your_plugin
+│   └── share/check_mk/
+│       ├── agents/plugins/
+│       │   └── your_plugin
+│       └── notifications/
+│           └── your_notification.py
 ├── .mkp-builder.ini          # Optional config file
 └── .github/workflows/
     └── build.yml
@@ -271,8 +274,9 @@ package.mkp (tar file, gzip compressed)
 ├── info                    # Python dict with package metadata
 ├── info.json              # JSON version of metadata
 ├── agents.tar             # Agent plugins and scripts
-├── cmk_addons_plugins.tar # Checkmk addon plugins
-└── lib.tar                # Library files (bakery plugins)
+├── cmk_addons_plugins.tar # CheckMK addon plugins
+├── lib.tar                # Library files (bakery plugins)
+└── notifications.tar      # Notification scripts
 ```
 
 ## Supported Checkmk Versions
@@ -295,6 +299,10 @@ The action automatically maps files from your local directory structure:
 - Source: `local/lib/python3/cmk/base/cee/plugins/bakery/PACKAGE_NAME.py`
 - Target: `cmk/base/cee/plugins/bakery/PACKAGE_NAME.py` in lib.tar
 
+### Notification Scripts
+- Source: `local/share/check_mk/notifications/*`
+- Target: notification files in notifications.tar
+
 ## Troubleshooting
 
 ### Common Issues

cmk-mkp-format.md

@@ -20,8 +20,9 @@ package.mkp (gzip compressed)
 ├── info                    # Python dict with package metadata
 ├── info.json              # JSON version of metadata
 ├── agents.tar             # Agent plugins and scripts
-├── cmk_addons_plugins.tar # Checkmk addon plugins
-└── lib.tar                # Library files (bakery plugins)
+├── cmk_addons_plugins.tar # CheckMK addon plugins
+├── lib.tar                # Library files (bakery plugins)
+└── notifications.tar      # Notification scripts
 ```
 
 ## Component Details
@@ -43,7 +44,8 @@ package.mkp (gzip compressed)
             'rulesets/plugin_name.py',
             'rulesets/plugin_name_bakery.py'
         ],
-        'lib': ['check_mk/base/cee/plugins/bakery/plugin_name.py']
+        'lib': ['check_mk/base/cee/plugins/bakery/plugin_name.py'],
+        'notifications': ['notification_script.py']
     },
     'name': 'plugin_name',
     'title': 'Human Readable Title',
@@ -108,6 +110,16 @@ check_mk/base/cee/plugins/bakery/
 
 **Installation Path**: `~SITE/local/lib/python3/`
 
+### 5. Notification Scripts (`notifications.tar`)
+
+Contains notification scripts for alerting integrations:
+
+```
+notification_script.py        # Notification plugin script
+```
+
+**Installation Path**: `~SITE/local/share/check_mk/notifications/`
+
 ## Directory Structure Requirements
 
 Your source project should follow this structure:
@@ -126,8 +138,11 @@ project_root/
 │   │               ├── checkman/
 │   │               ├── graphing/
 │   │               └── rulesets/
-│   └── share/check_mk/agents/plugins/
-│       └── plugin_name
+│   └── share/check_mk/
+│       ├── agents/plugins/
+│       │   └── plugin_name
+│       └── notifications/
+│           └── notification_script.py
 ├── .mkp-builder.ini      # Package configuration
 ```
 
@@ -151,16 +166,19 @@ a symlink to `python3/cmk`.
    # Create agents.tar
    tar -cf agents.tar -C local/share/check_mk/agents plugins/
 
-   # Create cmk_addons_plugins.tar  
+   # Create cmk_addons_plugins.tar
    tar -cf cmk_addons_plugins.tar -C local/lib/python3/cmk_addons/plugins .
 
    # Create lib.tar
    tar -cf lib.tar -C local/lib/python3 check_mk/
+
+   # Create notifications.tar
+   tar -cf notifications.tar -C local/share/check_mk/notifications .
    ```
 
 3. **Package final MKP**:
    ```bash
-   tar -czf package_name-version.mkp info info.json agents.tar cmk_addons_plugins.tar lib.tar
+   tar -czf package_name-version.mkp info info.json agents.tar cmk_addons_plugins.tar lib.tar notifications.tar
    ```
 
 ### 2. Automated Build Script
@@ -208,11 +226,16 @@ The build process automatically maps files from your local directory structure:
 - Target: `PACKAGE_NAME/*` and flat structure in cmk_addons_plugins.tar
 - Pattern: Recursive inclusion of all Python files and documentation
 
-### Library Mapping  
+### Library Mapping
 - Source: `local/lib/python3/cmk/base/cee/plugins/bakery/PACKAGE_NAME.py`
 - Target: `check_mk/base/cee/plugins/bakery/PACKAGE_NAME.py` in lib.tar
 - Pattern: Bakery plugin files only
 
+### Notification Mapping
+- Source: `local/share/check_mk/notifications/*`
+- Target: notification files in notifications.tar
+- Pattern: All notification script files
+
 ## Version Management
 
 ### Semantic Versioning
@@ -332,8 +355,9 @@ tar -tzf package.mkp
 
 # Validate tar files
 tar -tf agents.tar
-tar -tf cmk_addons_plugins.tar  
+tar -tf cmk_addons_plugins.tar
 tar -tf lib.tar
+tar -tf notifications.tar
 
 # Check Python syntax
 python3 -m py_compile file.py

cmk-plugin-guide/00-index.md

@@ -18,6 +18,7 @@
 | **Rename metrics while preserving history** | [13-metric-migration.md](13-metric-migration.md) | [05-metrics-graphing.md](05-metrics-graphing.md) |
 | **Configure thresholds in the GUI** | [06-rulesets.md](06-rulesets.md) | - |
 | **Deploy plugins automatically** | [07-bakery.md](07-bakery.md) | [06-rulesets.md](06-rulesets.md) |
+| **Send alerts to external systems** | [14-notifications.md](14-notifications.md) | - |
 | **Debug a non-working plugin** | [08-testing-debugging.md](08-testing-debugging.md) | - |
 | **Handle cluster environments** | [09-advanced-patterns.md](09-advanced-patterns.md) | - |
 | **See a complete example** | [10-examples.md](10-examples.md) | - |
@@ -39,6 +40,7 @@ START: What type of monitoring?
 Need to rename metrics? → 13-metric-migration.md
 Need GUI configuration? → 06-rulesets.md
 Need automatic deployment? → 07-bakery.md
+Need custom alerts? → 14-notifications.md
 Having problems? → 08-testing-debugging.md
 ```
 
@@ -63,6 +65,7 @@ Having problems? → 08-testing-debugging.md
 #### Configuration & Deployment
 - **[06-rulesets.md](06-rulesets.md)** - GUI configuration forms
 - **[07-bakery.md](07-bakery.md)** - Automatic agent deployment
+- **[14-notifications.md](14-notifications.md)** - Custom alert integrations (Slack, Discord, etc.)
 
 #### Advanced Topics
 - **[08-testing-debugging.md](08-testing-debugging.md)** - Troubleshooting and validation

cmk-plugin-guide/08-testing-debugging.md

@@ -158,6 +158,43 @@ def test_snmp_detection():
     assert oid_responses.get(".1.3.6.1.4.1.318.1.1.1.1.1.1.0") is not None
 ```
 
+### Using Checkmk Debug Mode
+
+```python
+from cmk.ccc import debug
+
+def parse_my_service(string_table):
+    """Parse with conditional debug output"""
+    if debug.enabled():
+        print(f"DEBUG: Parsing {len(string_table)} lines")
+        print(f"DEBUG: Data: {string_table}")
+
+    parsed = {}
+    for line in string_table:
+        # Parse logic here
+        pass
+
+    if debug.enabled():
+        print(f"DEBUG: Parsed result: {parsed}")
+
+    return parsed
+
+def check_my_service(item, section):
+    """Check with conditional debug output"""
+    if debug.enabled():
+        print(f"DEBUG: Checking item: {item}")
+        print(f"DEBUG: Section data: {section}")
+
+    # Check logic here
+    yield Result(state=State.OK, summary="Status OK")
+```
+
+**Important Notes:**
+- In Checkmk 2.4.0+, the debug module moved from `cmk.utils.debug` to `cmk.ccc.debug`
+- Debug output is only shown when running with `--debug` flag (e.g., `cmk -II --debug hostname`)
+- Debug statements are automatically filtered out in production
+- Use `debug.enabled()` to check if debug mode is active before printing
+
 ### Debugging with Logging
 
 ```python

cmk-plugin-guide/12-special-agents.md

@@ -38,12 +38,13 @@ A complete special agent plugin consists of four parts:
 
 ```
 ~/local/lib/python3/cmk_addons/plugins/my_plugin/
+├── __init__.py                  # Package marker
 ├── libexec/
 │   └── agent_my_plugin          # 1. Executable data collector
 ├── server_side_calls/
-│   └── special_agent.py         # 2. Command builder
+│   └── my_plugin.py             # 2. Command builder
 ├── rulesets/
-│   └── special_agent.py         # 3. GUI configuration
+│   └── my_plugin.py             # 3. GUI configuration
 └── agent_based/
     └── my_plugin.py             # 4. Check plugin (data processor)
 ```
@@ -114,20 +115,27 @@ if __name__ == "__main__":
    chmod 755 agent_my_plugin
    ```
 
-2. **Password Handling**: Always call `replace_passwords()` first
+2. **Entry Point**: Must include `if __name__ == "__main__":` block
+   ```python
+   if __name__ == "__main__":
+       sys.exit(main())
+   ```
+   **Without this, the script will not execute when called from the command line!**
+
+3. **Password Handling**: Always call `replace_passwords()` first
    ```python
    from cmk.utils.password_store import replace_passwords
    replace_passwords()  # Must be FIRST thing in main()
    ```
 
-3. **Output Format**: Standard CheckMK agent output
+4. **Output Format**: Standard CheckMK agent output
    ```python
    print("<<<section_name>>>")
    print("key1 value1")
    print("key2 value2")
    ```
 
-4. **Error Handling**: Write errors to stderr, return non-zero on failure
+5. **Error Handling**: Write errors to stderr, return non-zero on failure
 
 ### JSON Output Pattern
 
@@ -164,20 +172,21 @@ Converts GUI ruleset parameters into command-line arguments for the special agen
 ### Basic Implementation
 
 ```python
-# File: ~/local/lib/python3/cmk_addons/plugins/my_plugin/server_side_calls/special_agent.py
+# File: ~/local/lib/python3/cmk_addons/plugins/my_plugin/server_side_calls/my_plugin.py
 
 from collections.abc import Iterator
 from pydantic import BaseModel
 from cmk.server_side_calls.v1 import (
     HostConfig,
+    Secret,
     SpecialAgentCommand,
     SpecialAgentConfig,
 )
 
 class Params(BaseModel):
     """Type-safe parameter model"""
     username: str
-    password: tuple[str, str]  # ("password", "stored_password_id") or ("store", "id")
+    password: Secret
     port: int | None = None
     protocol: str = "https"
 
@@ -188,9 +197,9 @@ def commands_function(
     """Build command-line arguments"""
 
     # Build argument list
-    args: list[str | tuple[str, str, str]] = [
+    args = [
         "-u", params.username,
-        "-p", params.password,  # Tuple for password store
+        "-p", params.password.unsafe(),  # Extract password from Secret
     ]
 
     # Optional parameters
@@ -257,7 +266,7 @@ host_config.macros                         # Custom macros
 ### Basic Ruleset
 
 ```python
-# File: ~/local/lib/python3/cmk_addons/plugins/my_plugin/rulesets/special_agent.py
+# File: ~/local/lib/python3/cmk_addons/plugins/my_plugin/rulesets/my_plugin.py
 
 from cmk.rulesets.v1 import Title, Help, Label
 from cmk.rulesets.v1.form_specs import (
@@ -518,19 +527,20 @@ if __name__ == "__main__":
     sys.exit(main())
 ```
 
-### 2. Server-Side Calls (server_side_calls/special_agent.py)
+### 2. Server-Side Calls (server_side_calls/my_plugin.py)
 
 ```python
 from collections.abc import Iterator
 from pydantic import BaseModel
 from cmk.server_side_calls.v1 import (
     HostConfig,
+    Secret,
     SpecialAgentCommand,
     SpecialAgentConfig,
 )
 
 class Params(BaseModel):
-    api_key: tuple[str, str]
+    api_key: Secret
     location: str
     units: str = "metric"
 
@@ -539,7 +549,7 @@ def commands_function(
     host_config: HostConfig,
 ) -> Iterator[SpecialAgentCommand]:
     yield SpecialAgentCommand(command_arguments=[
-        "-k", params.api_key,
+        "-k", params.api_key.unsafe(),
         "-l", params.location,
         "--units", params.units,
         host_config.primary_ip_config.address or "api.weather.com",
@@ -554,7 +564,7 @@ special_agent_acme_weather = SpecialAgentConfig(
 )
 ```
 
-### 3. Ruleset (rulesets/special_agent.py)
+### 3. Ruleset (rulesets/my_plugin.py)
 
 ```python
 from cmk.rulesets.v1 import Title, Help
@@ -818,18 +828,20 @@ local/share/check_mk/web/plugins/wato/my_plugin.py  # GUI
 ### New Structure (CheckMK 2.3+)
 ```
 local/lib/python3/cmk_addons/plugins/my_plugin/
+├── __init__.py
 ├── libexec/agent_my_plugin
-├── server_side_calls/special_agent.py
-├── rulesets/special_agent.py
+├── server_side_calls/my_plugin.py
+├── rulesets/my_plugin.py
 └── agent_based/my_plugin.py
 ```
 
 ### Migration Steps
-1. Move agent to `libexec/agent_<name>`
-2. Create `server_side_calls/special_agent.py` from old `special_agent_info`
-3. Convert WATO ruleset to `rulesets/special_agent.py`
-4. Update check plugin imports (v1 → v2)
-5. Test thoroughly
+1. Create `__init__.py` package marker
+2. Move agent to `libexec/agent_<name>`
+3. Create `server_side_calls/<name>.py` from old `special_agent_info`
+4. Convert WATO ruleset to `rulesets/<name>.py`
+5. Update check plugin imports (v1 → v2)
+6. Test thoroughly
 
 ---