Document function naming conventions (#21661)
vkalintiris committed
Jan 29, 2026 at 08:24 UTC
be6e49367e40ed00ef07e6ac2aaa9af04af3b9f1
1 file changed
+33
src/plugins.d/README.md
+33
@@ -546,6 +546,39 @@ After this line, Netdata resumes processing collected metrics from the plugin.
546
547
The maximum uncompressed payload size Netdata will accept is 100MB.
548
549
+##### Function naming conventions
550
+
551
+Function names can follow a **colon-separated hierarchical naming convention** to organize related functions under a common namespace. This is particularly useful for plugins that expose multiple related functions.
552
+
553
+The recommended format for module-level functions is:
554
+
555
+```
556
+module:method
557
+```
558
+
559
+Where:
560
+- `module` is the collector or module name (e.g., `mysql`, `postgres`, `snmp`)
561
+- `method` is the specific function/operation (e.g., `top-queries`, `deadlock-info`, `interfaces`)
562
+
563
+Examples:
564
+- `mysql:top-queries` - Top queries function for MySQL collector
565
+- `mysql:deadlock-info` - Deadlock information for MySQL collector
566
+- `postgres:top-queries` - Top queries function for PostgreSQL collector
567
+- `snmp:interfaces` - Network interfaces function for SNMP collector
568
+
569
+This naming convention:
570
+- Groups related functions under a single module namespace
571
+- Allows collectors to expose multiple methods
572
+- Improves discoverability in the Functions API
573
+- Follows the same colon-separator pattern used by [Dynamic Configuration (DynCfg)](#config) for consistency
574
+
575
+:::note
576
+
577
+This naming convention is distinct from DynCfg configuration IDs. DynCfg commands are sent through the special `config` function (e.g., `config go.d:mysql:local get`), while module functions use their own unique names directly (e.g.,
578
+`mysql:top-queries`).
579
+
580
+:::
581
+
582
##### Functions cancellation
583
584
Netdata is able to detect when a user made an API request, but abandoned it before it was completed. If this happens to an API called for a function served by the plugin, Netdata will generate a `FUNCTION_CANCEL` request to let the plugin know that it can stop processing the query.