Developing with Dynamic Configuration (DynCfg)
What You'll Learn
How to integrate Dynamic Configuration into your Netdata plugins and modules to create configurable, user-friendly monitoring solutions.
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.
What DynCfg Does for You
DynCfg provides a complete configuration management system that handles:
Feature | What It Does |
---|---|
Configuration Registration | Register your plugin's configuration objects with Netdata |
User Interface Generation | Automatically create UI forms from JSON Schema definitions |
Configuration Persistence | Save and restore configurations across Netdata agent restarts |
Validation Pipeline | Route configuration changes back to your plugin for validation |
Standardized Experience | Provide users with consistent configuration workflows |
Key Benefits
- Users configure your plugin through the UI instead of editing files
- JSON Schema automatically generates user-friendly forms
- Your plugin validates all configuration changes before they're applied
- Configurations persist automatically across restarts
How DynCfg Works
The system consists of four main parts working together:
- DynCfg Manager - Tracks all configurations and routes commands between components
- Internal Plugin API - For modules built into the Netdata agent
- External Plugin API - For independent plugins using the plugins.d protocol
- Web API - Exposes configuration management to users and applications
Configuration Types You Can Create
Choose the configuration type that matches your use case:
Type | Use Case | Example |
---|---|---|
SINGLE | One standalone configuration | systemd-journal directories |
TEMPLATE | Blueprint for creating multiple configurations | Nginx collector template |
JOB | Specific instance created from a template | Individual Nginx server to monitor |
Implementation Guides
Getting Started
- Choose your implementation path - Internal module or external plugin?
- Read the relevant implementation guide - Follow the detailed documentation for your chosen approach
- Study working examples - Look at existing implementations for patterns and best practices
- Start with simple configurations - Begin with basic SINGLE type configurations before moving to TEMPLATE/JOB patterns
- Test thoroughly - Verify your configurations work correctly through both API and UI
Ready to make your plugin configurable through the Netdata UI? Choose your implementation guide and start building!
For Internal Modules
Are you developing a module built into the Netdata agent?
👉 Internal DynCfg Implementation Guide
This guide covers:
- Low-level and high-level APIs for internal modules
- Configuration ID structure and naming conventions
- Response codes and status handling
- Action behavior for different configuration types
- JSON Schema implementation details
- API access patterns and endpoints
- Implementation best practices
For External Plugins
Are you developing a standalone plugin that communicates with Netdata using the plugins.d protocol?
👉 External Plugin DynCfg Implementation Guide
This guide covers:
- Plugin protocol commands and response formats
- Configuration registration process
- Handling incoming configuration commands
- Responding to status changes and validation requests
- Schema definition and management
- Complete working examples with code
Learn from Working Examples
Study these real implementations to understand DynCfg patterns:
Health Alerts System (Internal Module)
The health module manages alert definitions through DynCfg:
- File:
src/health/health_dyncfg.c
- Pattern: Uses high-level internal API
- Type: TEMPLATE and JOB configurations for alert definitions
systemd-journal.plugin (External Plugin, C)
External C plugin that manages journal directory configurations:
- File:
src/collectors/systemd-journal.plugin/systemd-journal-dyncfg.c
- Pattern: SINGLE configuration type
- Use Case: Managing journal directory paths
go.d.plugin (External Plugin, Go)
Go-based plugin managing multiple data collector configurations:
- Pattern: TEMPLATE and JOB configurations
- Feature: Dynamically generates JSON Schema from Go struct tags
- Scale: Manages dozens of different collector types
Implementation Best Practices
Category | Best Practice | Description |
---|---|---|
Configuration Design | Use clear ID structure | Follow the component:category:name pattern consistently |
Choose logical paths | The path parameter affects how configurations appear in the UI | |
Design intuitive schemas | Include helpful descriptions and examples in your JSON Schema | |
Validation and Error Handling | Validate thoroughly | Always validate configuration changes before accepting them |
Provide helpful errors | Give users clear explanations when configurations are rejected | |
Return appropriate codes | Use correct HTTP status codes for different situations | |
User Experience | Respect type-action relationships | Different actions behave differently for each configuration type |
Test your UI | Verify that your JSON Schema generates usable forms | |
Document your options | Help users understand what each configuration option does |
Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.