| 1 | # Developing with Dynamic Configuration (DynCfg) |
| 2 | |
| 3 | :::tip |
| 4 | |
| 5 | **What You'll Learn** |
| 6 | |
| 7 | How to integrate Dynamic Configuration into your Netdata plugins and modules to create configurable, user-friendly monitoring solutions. |
| 8 | |
| 9 | ::: |
| 10 | |
| 11 | Dynamic Configuration (DynCfg) enables your plugins and modules to expose their configurations through Netdata's unified interface. Instead of requiring users to manually edit configuration files, they can configure your plugin directly through the Netdata UI. |
| 12 | |
| 13 | ## What DynCfg Does for You |
| 14 | |
| 15 | DynCfg provides a complete configuration management system that handles: |
| 16 | |
| 17 | | Feature | What It Does | |
| 18 | |--------------------------------|----------------------------------------------------------------| |
| 19 | | **Configuration Registration** | Register your plugin's configuration objects with Netdata | |
| 20 | | **User Interface Generation** | Automatically create UI forms from JSON Schema definitions | |
| 21 | | **Configuration Persistence** | Save and restore configurations across Netdata agent restarts | |
| 22 | | **Validation Pipeline** | Route configuration changes back to your plugin for validation | |
| 23 | | **Standardized Experience** | Provide users with consistent configuration workflows | |
| 24 | |
| 25 | :::info |
| 26 | |
| 27 | **Key Benefits** |
| 28 | |
| 29 | - Users configure your plugin through the UI instead of editing files |
| 30 | - JSON Schema automatically generates user-friendly forms |
| 31 | - Your plugin validates all configuration changes before they're applied |
| 32 | - Configurations persist automatically across restarts |
| 33 | |
| 34 | ::: |
| 35 | |
| 36 | ## How DynCfg Works |
| 37 | |
| 38 | The system consists of four main parts working together: |
| 39 | |
| 40 | ```mermaid |
| 41 | graph TB |
| 42 | DM("**DynCfg Manager**<br/><br/>Tracks all configurations<br/>Routes commands between<br/>components") |
| 43 | |
| 44 | IPA("**Internal Plugin API**<br/><br/>For modules built into<br/>the Netdata agent") |
| 45 | |
| 46 | EPA("**External Plugin API**<br/><br/>For independent plugins<br/>using plugins.d protocol") |
| 47 | |
| 48 | WA("**Web API**<br/><br/>Exposes configuration<br/>management to users<br/>and applications") |
| 49 | |
| 50 | %% Connections showing data flow |
| 51 | DM <--> IPA |
| 52 | DM <--> EPA |
| 53 | DM <--> WA |
| 54 | |
| 55 | %% Style definitions |
| 56 | classDef manager fill:#f9f9f9,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px |
| 57 | classDef api fill:#ffeb3b,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px |
| 58 | classDef web fill:#4caf50,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px |
| 59 | |
| 60 | %% Apply styles |
| 61 | class DM manager |
| 62 | class IPA,EPA api |
| 63 | class WA web |
| 64 | ``` |
| 65 | |
| 66 | 1. **DynCfg Manager** - Tracks all configurations and routes commands between components |
| 67 | 2. **Internal Plugin API** - For modules built into the Netdata agent |
| 68 | 3. **External Plugin API** - For independent plugins using the plugins.d protocol |
| 69 | 4. **Web API** - Exposes configuration management to users and applications |
| 70 | |
| 71 | ## Configuration Types You Can Create |
| 72 | |
| 73 | Choose the configuration type that matches your use case: |
| 74 | |
| 75 | | Type | Use Case | Example | |
| 76 | |--------------|------------------------------------------------|------------------------------------| |
| 77 | | **SINGLE** | One standalone configuration | systemd-journal directories | |
| 78 | | **TEMPLATE** | Blueprint for creating multiple configurations | Nginx collector template | |
| 79 | | **JOB** | Specific instance created from a template | Individual Nginx server to monitor | |
| 80 | |
| 81 | ## Implementation Guides |
| 82 | |
| 83 | ### Getting Started |
| 84 | |
| 85 | 1. **Choose your implementation path** - Internal module or external plugin? |
| 86 | 2. **Read the relevant implementation guide** - Follow the detailed documentation for your chosen approach |
| 87 | 3. **Study working examples** - Look at existing implementations for patterns and best practices |
| 88 | 4. **Start with simple configurations** - Begin with basic SINGLE type configurations before moving to TEMPLATE/JOB patterns |
| 89 | 5. **Test thoroughly** - Verify your configurations work correctly through both API and UI |
| 90 | |
| 91 | :::tip |
| 92 | |
| 93 | Ready to make your plugin configurable through the Netdata UI? Choose your implementation guide and start building! |
| 94 | |
| 95 | ::: |
| 96 | |
| 97 | ### For Internal Modules |
| 98 | |
| 99 | Are you developing a module built into the Netdata agent? |
| 100 | |
| 101 | 👉 **[Internal DynCfg Implementation Guide](/src/daemon/dyncfg/README.md)** |
| 102 | |
| 103 | <details> |
| 104 | <summary><strong>This guide covers:</strong></summary><br/> |
| 105 | |
| 106 | - Low-level and high-level APIs for internal modules |
| 107 | - Configuration ID structure and naming conventions |
| 108 | - Response codes and status handling |
| 109 | - Action behavior for different configuration types |
| 110 | - JSON Schema implementation details |
| 111 | - API access patterns and endpoints |
| 112 | - Implementation best practices |
| 113 | |
| 114 | <br/> |
| 115 | </details> |
| 116 | |
| 117 | ### For External Plugins |
| 118 | |
| 119 | Are you developing a standalone plugin that communicates with Netdata using the plugins.d protocol? |
| 120 | |
| 121 | 👉 **[External Plugin DynCfg Implementation Guide](/src/plugins.d/DYNCFG.md)** |
| 122 | |
| 123 | <details> |
| 124 | <summary><strong>This guide covers:</strong></summary><br/> |
| 125 | |
| 126 | - Plugin protocol commands and response formats |
| 127 | - Configuration registration process |
| 128 | - Handling incoming configuration commands |
| 129 | - Responding to status changes and validation requests |
| 130 | - Schema definition and management |
| 131 | - Complete working examples with code |
| 132 | |
| 133 | <br/> |
| 134 | </details> |
| 135 | |
| 136 | ## Learn from Working Examples |
| 137 | |
| 138 | Study these real implementations to understand DynCfg patterns: |
| 139 | |
| 140 | <details> |
| 141 | <summary><strong>Health Alerts System (Internal Module)</strong></summary><br/> |
| 142 | |
| 143 | The health module manages alert definitions through DynCfg: |
| 144 | |
| 145 | - **File**: `src/health/health_dyncfg.c` |
| 146 | - **Pattern**: Uses high-level internal API |
| 147 | - **Type**: TEMPLATE and JOB configurations for alert definitions |
| 148 | |
| 149 | <br/> |
| 150 | </details> |
| 151 | |
| 152 | <details> |
| 153 | <summary><strong>systemd-journal.plugin (External Plugin, C)</strong></summary><br/> |
| 154 | |
| 155 | External C plugin that manages journal directory configurations: |
| 156 | |
| 157 | - **File**: `src/collectors/systemd-journal.plugin/systemd-journal-dyncfg.c` |
| 158 | - **Pattern**: SINGLE configuration type |
| 159 | - **Use Case**: Managing journal directory paths |
| 160 | |
| 161 | <br/> |
| 162 | </details> |
| 163 | |
| 164 | <details> |
| 165 | <summary><strong>go.d.plugin (External Plugin, Go)</strong></summary><br/> |
| 166 | |
| 167 | Go-based plugin managing multiple data collector configurations: |
| 168 | |
| 169 | - **Pattern**: TEMPLATE and JOB configurations |
| 170 | - **Feature**: Dynamically generates JSON Schema from Go struct tags |
| 171 | - **Scale**: Manages dozens of different collector types |
| 172 | |
| 173 | <br/> |
| 174 | </details> |
| 175 | |
| 176 | ## Implementation Best Practices |
| 177 | |
| 178 | | Category | Best Practice | Description | |
| 179 | |-----------------------------------|-----------------------------------|------------------------------------------------------------------| |
| 180 | | **Configuration Design** | Use clear ID structure | Follow the `component:category:name` pattern consistently | |
| 181 | | | Choose logical paths | The path parameter affects how configurations appear in the UI | |
| 182 | | | Design intuitive schemas | Include helpful descriptions and examples in your JSON Schema | |
| 183 | | **Validation and Error Handling** | Validate thoroughly | Always validate configuration changes before accepting them | |
| 184 | | | Provide helpful errors | Give users clear explanations when configurations are rejected | |
| 185 | | | Return appropriate codes | Use correct HTTP status codes for different situations | |
| 186 | | **User Experience** | Respect type-action relationships | Different actions behave differently for each configuration type | |
| 187 | | | Test your UI | Verify that your JSON Schema generates usable forms | |
| 188 | | | Document your options | Help users understand what each configuration option does | |