Developing with Dynamic Configuration (DynCfg)

:::tip

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:

:::info

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:

graph TB
    DM("**DynCfg Manager**

Tracks all configurations
Routes commands between
components")
    
    IPA("**Internal Plugin API**

For modules built into
the Netdata agent")
    
    EPA("**External Plugin API**

For independent plugins
using plugins.d protocol")
    
    WA("**Web API**

Exposes configuration
management to users
and applications")
    
    %% Connections showing data flow
    DM <--> IPA
    DM <--> EPA
    DM <--> WA
    
    %% Style definitions
    classDef manager fill:#f9f9f9,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px
    classDef api fill:#ffeb3b,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px
    classDef web fill:#4caf50,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px
    
    %% Apply styles
    class DM manager
    class IPA,EPA api
    class WA web

1. DynCfg Manager - Tracks all configurations and routes commands between components
2. Internal Plugin API - For modules built into the Netdata agent
3. External Plugin API - For independent plugins using the plugins.d protocol
4. Web API - Exposes configuration management to users and applications

Configuration Types You Can Create

Choose the configuration type that matches your use case:

Implementation Guides

Getting Started

1. Choose your implementation path - Internal module or external plugin?
2. Read the relevant implementation guide - Follow the detailed documentation for your chosen approach
3. Study working examples - Look at existing implementations for patterns and best practices
4. Start with simple configurations - Begin with basic SINGLE type configurations before moving to TEMPLATE/JOB patterns
5. Test thoroughly - Verify your configurations work correctly through both API and UI

:::tip

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

• 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

• 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:

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

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-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