Skip to main content

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:

FeatureWhat It Does
Configuration RegistrationRegister your plugin's configuration objects with Netdata
User Interface GenerationAutomatically create UI forms from JSON Schema definitions
Configuration PersistenceSave and restore configurations across Netdata agent restarts
Validation PipelineRoute configuration changes back to your plugin for validation
Standardized ExperienceProvide users with consistent configuration workflows
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:

  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:

TypeUse CaseExample
SINGLEOne standalone configurationsystemd-journal directories
TEMPLATEBlueprint for creating multiple configurationsNginx collector template
JOBSpecific instance created from a templateIndividual Nginx server to monitor

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

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

CategoryBest PracticeDescription
Configuration DesignUse clear ID structureFollow the component:category:name pattern consistently
Choose logical pathsThe path parameter affects how configurations appear in the UI
Design intuitive schemasInclude helpful descriptions and examples in your JSON Schema
Validation and Error HandlingValidate thoroughlyAlways validate configuration changes before accepting them
Provide helpful errorsGive users clear explanations when configurations are rejected
Return appropriate codesUse correct HTTP status codes for different situations
User ExperienceRespect type-action relationshipsDifferent actions behave differently for each configuration type
Test your UIVerify that your JSON Schema generates usable forms
Document your optionsHelp 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.