.. _ldmsd_config_files: ================================== ldmsd Configuration File Reference ================================== ------------------------------------ Manual for LDMSD Configuration Files ------------------------------------ :Date: 27 April 2026 :Manual section: 7 :Manual group: LDMSD SYNOPSIS ======== ldmsd [-c ] [-c ..] DESCRIPTION =========== LDMSD configuration files provide a maintainable way to define the initial state and behavior of an LDMS daemon. These files contain configuration commands that are processed sequentially at daemon startup. SPECIFYING CONFIGURATION FILES =============================== Configuration files are specified using the **-c** command-line option: :: ldmsd -c /path/to/config_file Multiple configuration files can be provided by repeating the **-c** option: :: ldmsd -c /path/to/config_path_1 -c /path/to/config_file_2 When multiple configuration files are given, they are processed in the order specified on the command line. ENVIRONMENT VARIABLES ===================== Configuration files support defining and referencing environment variables, enabling parameterized configurations. Defining Environment Variables ------------------------------- Use the **env** command to define an environment variable within a configuration file: :: env = Example: :: env MYNAME=node-1 env MYCOMPID=1 Referencing Environment Variables ---------------------------------- Reference environment variables using the syntax **${}**: :: config name=meminfo producer=${MYNAME} instance=${MYNAME}/meminfo component_id=${MYCOMPID} Environment variables can be: * Defined within the configuration file using the **env** command * Already present in the environment when ldmsd starts **Important**: If a referenced environment variable does not exist (neither defined in the configuration file nor in the environment), it will be substituted with an empty string. This behavior is the same as shell variable expansion. CONFIGURATION COMMANDS ====================== Configuration files can contain two types of commands: 1. **Initialization commands** - Commands that set up the initial state of LDMS daemon. 2. **Operational commands** - Commands that define the work LDMS daemon needs to perform, such as loading plugins, configuring plugins, starting samplers, connecting to other LDMS daemons, and defining storage policies. For a complete list of these commands, see :ref:`ldmsd_controller(8) `. Commands to Initialize LDMS Daemon ----------------------------------- The following commands are equivalent to command-line options and are used to initialize LDMS daemon settings. These commands provide the same functionality as command-line options but in a more readable and maintainable format. **log_file** sets the log file path. path=PATH The log file path **log_level** sets the log verbosity. The default is ERROR. level=LEVEL The log level ordered from the most to the least severity: CRITICAL, ERROR, WARNING, INFO, and DEBUG. **set_memory** sets the total set memory. The default is 512 MB. size=SIZE The total set memory size. **pid_file** sets the path to the PID file. path=PATH The PID file path **banner** specifies the banner mode. mode=0|1|2 0 means no banner; 1 means auto-deleting the banner file at exit; and 2 means leaving the banner file. **worker_threads** sets the number of threads scheduling sample and update events. num=NUM Number of threads that are responsible for scheduling sample, dir, lookup, and update events. Default: 1 The value can be set only once and cannot be changed after ldmsd initialization. Example: :: worker_threads num=4 **storage_threads** sets the number of dedicated worker threads for storage operations. num=NUM Number of dedicated storage worker threads. Must be a positive integer. Default: 1 Storage operations are performed asynchronously on dedicated worker threads, reducing latency in the update path. This allows decoupling storage overhead from the data collection process. The value can be set only once and cannot be changed after ldmsd initialization. Example: :: storage_threads num=4 **storage_queue_depth** sets the maximum number of events queued per storage worker thread. num=NUM Maximum queue depth per worker thread. Use -1 or 0 for unlimited queue depth. Default: -1 (unlimited) This setting provides backpressure when storage operations cannot keep pace with metric collection. When a worker's queue reaches the maximum depth, the update callback blocks until space becomes available. Negative values and 0 enable unlimited queue depth, which allows the system to absorb burst workloads but risks excessive memory growth if storage falls significantly behind. The value can be set only once and cannot be changed after ldmsd initialization. Example: :: storage_queue_depth num=1000 **default_auth** defines the default authentication domain. The default is no authentication. plugin=NAME The authentication plugin name [auth_attr=attr_value] The attribute-value pairs of the authentication plugin **auth_add** defines an additional authentication domain. name=NAME The authentication domain name plugin=PI_NAME The authentication plugin name [auth_attr=attr_value] The attribute-value pairs of the authentication plugin **listen** defines a listen endpoint. xprt=XPRT Endpoint transport: sock, rdma, ugni port=PORT Listening port [host=HOST] Listening host [auth=AUTH] Authentication domain. The default authentication domain is used if none is specified. **default_quota** sets the receiving quota in bytes quota=BYTES The quota limit in bytes **publish_kernel** enables LDMSD to publish kernel metrics and specifies the kernel metric file. path=PATH The path to the kernel metric file **daemon_name** sets the LDMS process name. name=NAME LDMS process name **stream_enable** enables stream communication in the daemon. Stream communication is disabled by default and must be explicitly enabled when needed. No Parameters **msg_enable** enables LDMS message functionality in the daemon. LDMS message is disabled by default and must be explicitly enabled when needed. No Parameters IO Thread Pool ~~~~~~~~~~~~~~ The IO thread pool is managed by the Zap transport library and is controlled through environment variables that must be set in the shell environment before starting ldmsd. ``ZAP_IO_MAX`` sets the maximum total number of IO threads. The default is half the number of online processors (``get_nprocs() / 2``), with a minimum of 1. IO threads are created lazily as endpoints are assigned; this variable caps how many can exist at once. ``ZAP_POOLS`` sets the number of pool buckets across which endpoints are distributed in round-robin order. The default is the number of configured processors (``_SC_NPROCESSORS_CONF``). Each pool grows its threads independently up to the ``ZAP_IO_MAX`` global cap. ``ZAP_IO_BUSY`` sets the utilization threshold (0.0–1.0) above which an IO thread is considered too busy to accept another endpoint, prompting Zap to create a new thread if the cap permits. The default is 0.8. Example: :: export ZAP_IO_MAX=16 export ZAP_POOLS=4 ldmsd -c /path/to/config 'option' configuration command to set the command-line options -------------------------------------------------------------- Apart from the configuration commands above, the configuration command 'option' can be used to specify the command-line option. option * **-a,--default_auth** * **-A,--default_auih_args** * **-B,--banner** * **-k,--publish_kernel** * **-l,--log_file** * **-m,--set_memory** * **-n,--daemon_name** * **-P,--worker_threads** * **-r,--pid_file** * **-s,--kernel_set_path** * **-v,--log_level** * **-L,--log_config** COMMAND PROCESSING ORDER ======================== LDMS daemons process configuration commands in a specific order to ensure proper initialization. Understanding this order is important when working with multiple configuration files or when dependencies exist between commands. Priority Commands ----------------- The following commands are processed **before** all other commands, regardless of where they appear in the configuration file(s): * **env** - Environment variable definitions * Initialization commands listed in the **Commands to Initialize LDMS Daemon** section * **listen** - Listen endpoint definitions * **auth_add** - Additional authentication domains * **stream_enable** - Enable Stream functionality * **msg_enable** - Enable Message functionality Processing Order with Multiple Configuration Files --------------------------------------------------- When multiple configuration files are specified with **-c**, the processing order is: 1. **Priority commands** are extracted from all configuration files and processed first: a. All Priority commands from the first configuration file are processed in the order they appear in that file b. Then all Priority commands from the second configuration file are processed in order c. This continues for all configuration files 2. **All other commands** are then processed: a. Remaining commands from the first configuration file are processed in order b. Then remaining commands from the second configuration file c. This continues for all configuration files Deferred Commands ----------------- Some commands are deferred and executed after all configuration files have been processed: * **prdcr_start** - Start producers * **updtr_start** - Start updaters * **strgp_start** - Start storage policies * **failover_start** - Start failover service (**DEPRECATED**) If **failover_start** is present, the failover service will start first among the deferred commands. Upon failover pairing success or failure, the other deferred configuration objects will be started. **Note 1**: While failover service is in use, prdcr, updtr, and strgp cannot be altered (start, stop, or reconfigure) over in-band configuration. **Note 2**: The failover functionality is deprecated and will be removed in a future release/ EXAMPLES ======== Sampler Configuration --------------------- A simple sampler daemon configuration (samplerd.conf): :: > cat samplerd.conf # Daemon settings log_file path=/var/log/ldmsd_samplerd.log set_memory size=512M # Authentication and listen endpoint default_auth plugin=munge listen xprt=sock port=10001 # Environment variables for plugin configuration env SAMP_INTERVAL=1s # Load and configure meminfo sampler plugin load name=meminfo config name=meminfo producer=${HOSTNAME} instance=${HOSTNAME}/meminfo component_id=${MYCOMPID} start name=meminfo interval=${SAMP_INTERVAL} > export MYCOMPID=1; ldmsd -c samplerd.conf Aggregator Configuration ------------------------ A simple aggregator daemon configuration (agg.conf): :: > cat agg.conf # Daemon settings log_file path=/var/log/ldmsd_agg.log set_memory size=1G # Authentication and listen endpoint default_auth plugin=munge listen xprt=sock port=10001 # Storage configuration storage_threads num=4 storage_queue_depth num=1000 # Environment variables env LDMS_XPRT=sock env RECONNECT=5s env UPDT_INTERVAL=1s # Define producers to aggregate from prdcr_add name=node-1 port=10001 xprt=${LDMS_XPRT} host=node-1 type=active reconnect=${RECONNECT} prdcr_start_regex regex=.* # Define updater to collect metrics updtr_add name=all interval=${UPDT_INTERVAL} offset=100ms updtr_prdcr_add name=all regex=.* updtr_start name=all SEE ALSO ======== :ref:`ldmsd(8) `, :ref:`ldmsd_controller(8) `, :ref:`ldms_authentication(7) `, :ref:`ldms_quickstart(7) `, :ref:`ldmsd_event_based_storage(7) `