updated plugin guide

Author: oetiker

CHANGES.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New
 - refactored plugin guide with added snmp plugin info
+- added renaming information to plugin guide
+- added special_agent informtion to plugin guide
 
 ### Changed
 

README.md

@@ -5,7 +5,7 @@
 
 > **⚠️ Disclaimer**: This is an independent, community-developed tool and is **not officially affiliated with or endorsed by CheckMK GmbH**. This project was developed by reverse-engineering existing MKP package formats and studying CheckMK documentation. Any issues, bugs, or incompatibilities are our responsibility and should be reported to this project's issue tracker, not to CheckMK support.
 
-> **📚 Plugin Development Guide**: Since many users of mkp-builder are developing CheckMK plugins, we maintain comprehensive documentation for CheckMK 2.3.x plugin development in [`cmk-pluigin-guide.md`](cmk-plugin-guide.md). This guide covers agent plugins, check plugins, rulesets, graphing, and bakery integration with practical examples and best practices.
+> **📚 Plugin Development Guide**: Since many users of mkp-builder are developing CheckMK plugins, we maintain comprehensive modular documentation for CheckMK 2.3.x plugin development in [`cmk-plugin-guide/`](cmk-plugin-guide/). The guide covers agent plugins, SNMP plugins, special agents, check plugins, rulesets, graphing, bakery integration, and metric migration with practical examples and best practices. Start with the [guide index](cmk-plugin-guide/00-index.md) or read the [guide overview](cmk-plugin-guide/README.md).
 
 > **🚨 Breaking Changes in v2.0.0**: If you're upgrading from v1.x, please note that v2.0.0 introduces breaking changes. The configuration file format has changed from `.mkp-builderrc` to `.mkp-builder.ini` with INI format syntax. GitHub Action input names have also been updated. See the [changelog](CHANGES.md) for full migration details.
 

cmk-plugin-guide/00-index.md

@@ -12,8 +12,10 @@
 | **Create my first plugin** | [01-quickstart.md](01-quickstart.md) | - |
 | **Monitor a network device via SNMP** | [02-snmp-plugins.md](02-snmp-plugins.md) | [04-check-plugins.md](04-check-plugins.md) |
 | **Collect data from a Linux/Windows host** | [03-agent-plugins.md](03-agent-plugins.md) | [04-check-plugins.md](04-check-plugins.md) |
+| **Monitor via REST API or custom protocol** | [12-special-agents.md](12-special-agents.md) | [04-check-plugins.md](04-check-plugins.md) |
 | **Process and check collected data** | [04-check-plugins.md](04-check-plugins.md) | [05-metrics-graphing.md](05-metrics-graphing.md) |
 | **Add graphs and visualizations** | [05-metrics-graphing.md](05-metrics-graphing.md) | - |
+| **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) |
 | **Debug a non-working plugin** | [08-testing-debugging.md](08-testing-debugging.md) | - |
@@ -29,9 +31,12 @@ START: What type of monitoring?
 │   └── Then → 04-check-plugins.md → 05-metrics-graphing.md
 ├── Agent-based (Linux/Windows) → 03-agent-plugins.md
 │   └── Then → 04-check-plugins.md → 05-metrics-graphing.md
+├── API/Cloud/Special Protocol → 12-special-agents.md
+│   └── Then → 04-check-plugins.md → 05-metrics-graphing.md
 └── Already have data → 04-check-plugins.md
     └── Then → 05-metrics-graphing.md
 
+Need to rename metrics? → 13-metric-migration.md
 Need GUI configuration? → 06-rulesets.md
 Need automatic deployment? → 07-bakery.md
 Having problems? → 08-testing-debugging.md
@@ -48,10 +53,12 @@ Having problems? → 08-testing-debugging.md
 #### Data Collection
 - **[02-snmp-plugins.md](02-snmp-plugins.md)** - SNMP monitoring via network
 - **[03-agent-plugins.md](03-agent-plugins.md)** - Host-based data collection
+- **[12-special-agents.md](12-special-agents.md)** - Server-side collection (APIs, cloud services)
 
 #### Data Processing
 - **[04-check-plugins.md](04-check-plugins.md)** - Parse data, determine states, generate metrics
 - **[05-metrics-graphing.md](05-metrics-graphing.md)** - Visualizations and performance data
+- **[13-metric-migration.md](13-metric-migration.md)** - Rename metrics while preserving historical data
 
 #### Configuration & Deployment
 - **[06-rulesets.md](06-rulesets.md)** - GUI configuration forms

cmk-plugin-guide/01-quickstart.md

@@ -69,17 +69,18 @@ def check_my_service(section):
     if not section:
         yield Result(state=State.UNKNOWN, summary="No data")
         return
-    
+
     status = section.get("status", "UNKNOWN")
     value = int(section.get("value", 0))
-    
+
     if status == "OK":
         state = State.OK
     else:
         state = State.WARN
-    
+
     yield Result(state=state, summary=f"Status: {status}")
-    yield Metric("value", value)
+    # Use prefixed metric name (replace 'mycompany' with your org)
+    yield Metric("mycompany_myservice_value", value)
 
 # CRITICAL: Name must start with check_plugin_
 check_plugin_my_service = CheckPlugin(
@@ -106,17 +107,57 @@ cmk -II target_hostname
 cmk -v --debug target_hostname
 ```
 
-### Entry Point Prefixes (MANDATORY!)
+### Naming Conventions (CRITICAL!)
+
+#### Entry Point Prefixes (MANDATORY!)
 
 Variables MUST start with these prefixes to be discovered:
 - `agent_section_` - Agent data parsers
-- `snmp_section_` - SNMP data parsers  
+- `snmp_section_` - SNMP data parsers
 - `check_plugin_` - Check logic
 - `inventory_plugin_` - Inventory
+- `special_agent_` - Special agent configs (in server_side_calls/)
+- `rule_spec_` - Ruleset definitions
 
 **Wrong**: `my_section = AgentSection(...)`  ❌
 **Right**: `agent_section_my_service = AgentSection(...)`  ✅
 
+#### Metric Names (CRITICAL!)
+
+**⚠️ ALWAYS prefix metric names with `mycompany_myplugin_` format!**
+
+CheckMK has ~1,000 built-in metrics. Unprefixed names will conflict and break:
+
+```python
+# ❌ WRONG - Generic names risk conflicts
+yield Metric("cpu_usage", 45.0)
+yield Metric("temperature", 65.0)
+yield Metric("latency", 0.05)
+
+# ✅ CORRECT - Prefixed with company and plugin name
+yield Metric("acme_widget_cpu_usage", 45.0)
+yield Metric("acme_widget_temperature", 65.0)
+yield Metric("acme_widget_latency", 0.05)
+```
+
+**Format**: `mycompany_myplugin_{metric_name}`
+- Replace `mycompany` with your company/organization
+- Replace `myplugin` with your plugin name
+- Example prefixes: `acme_weather_`, `myorg_api_`, `contoso_ups_`
+
+**Why this matters:**
+- Prevents conflicts with CheckMK's built-in metrics
+- Prevents your metrics being overridden by CheckMK updates
+- Makes metric ownership clear
+- Enables safe metric renaming via translations (see [13-metric-migration.md](13-metric-migration.md))
+
+#### Plugin/Section Names
+
+Choose descriptive, unique names for your plugins:
+- Use your organization prefix: `mycompany_service_name`
+- Examples: `acme_weather`, `contoso_ups`, `myorg_api`
+- Avoid generic names: `status`, `metrics`, `monitor`
+
 ### Common Pitfalls
 
 1. **Wrong directory** → Use exact paths shown above