ldmsd_setgroup

Date:

5 Jul 2018

NAME

ldmsd_setgroup - explanation, configuration, and commands for ldmsd set group

SYNOPSIS

setgroup_add

name=GROUP_NAME [producer=PRODUCER] [interval=USEC] [offset=USEC]

setgroup_mod

name=GROUP_NAME [interval=USEC] [offset=USEC]

setgroup_del

name=GROUP_NAME

setgroup_ins

name=GROUP_NAME instance=COMMA_SEPARATED_LIST_OF_INSTANCES

setgroup_rm

name=GROUP_NAME instance=COMMA_SEPARATED_LIST_OF_INSTANCES

DESCRIPTION

An ldmsd setgroup (referred to as setgroup for short) is an ldms_set with special information for LDMS daemon (ldmsd). The setgroup information contains a list of other sets so that the LDMSD updtr can update all the sets in the collection at once (iteratively). This will help administrators in configuration, and help sampler plugin developer to manage their collection of sets. For an example usage of `ldmsd_group_*` APIs, please see grptest.c, and `ldmsd_group_*()` declarations (with doxygen doc) in ldmsd.h. In this manual page, we will focus on LDMSD commands that manage the setgroup from the configuration side. The description for each command and its parameters is as follows.

setgroup_add adds (creates) a new setgroup. The following list describes the command parameters:

name=GROUP_NAME

The name of the setgroup.

[producer=PRODUCER]

(Optional) The producer name of the setgroup. If not set, the name of the LDMSD (the -n option) is used.

[interval=USEC]

(Optional) The micro-second update interval hint.

[offset=USEC]

(Optional) The micro-second update offset hint.

setgroup_mod modifies (mutable) attributes of the setgroup. The list of parameters is as follows:

name=GROUP_NAME

The name of the setgroup.

[interval=USEC]

(Optional) The micro-second update interval hint.

[offset=USEC]

(Optional) The micro-second update offset hint.

setgroup_ins inserts a list of set instances into the setgroup.

name=GROUP_NAME

The name of the setgroup.

instance=COMMA_SEPARATED_LIST_OF_INSTANCES

A comma-separated list of set instances.

setgroup_rm removes a list of set instances from the setgroup.

name=GROUP_NAME

The name of the setgroup.

instance=COMMA_SEPARATED_LIST_OF_INSTANCES

A comma-separated list of set instances.

setgroup_del deletes the setgroup.

name=GROUP_NAME

The name of the setgroup.

EXAMPLE

In this example, we will have 2 ldmsd’s, namely sampler and aggregator for the sampler daemon and the aggregator daemon respectively. The sampler will have `meminfo`, `set_0`, `set_1`, `set_2`, `set_3` as its regular sets. `thegroup` will be the setgroup created in the sampler that contains `meminfo` and `set_0`. The aggregator will be setup to update only `thegroup`.

### sampler.conf
# It is OK to add the group first, please also not that our group has no
# update hint so that the updater in the aggregator can control its update
# interval.
setgroup_add name=thegroup

# Insert meminfo and set_0 into the group
setgroup_ins name=thegroup instance=meminfo,set_0

# test_sampler will generate a bunch of sets, with this config it will create
# set_0, set_1, set_2, set_3
load name=test_sampler
config name=test_sampler producer=sampler \
       action=default \
       base=set \
       num_sets=4 \
       push=0
start name=test_sampler interval=1000000 offset=0
# meminfo
load name=meminfo
config name=meminfo producer=sampler \
       instance=meminfo
start name=meminfo interval=1000000 offset=0
### END OF sampler.conf

### aggregator.conf
# Normal producer setup
prdcr_add name=prdcr host=localhost port=10001 xprt=sock \
          interval=1000000 \
          type=active
prdcr_start name=prdcr
# Setup the `grp_updtr` so that it only updates `thegroup`.
updtr_add name=grp_updtr interval=1000000 offset=500000
updtr_match_add name=grp_updtr regex=thegroup
updtr_prdcr_add name=grp_updtr regex=prdcr
updtr_start name=grp_updtr
### END OF sampler.conf

The daemons can be started with the following commands:

# For sampler, foreground start
$ ldmsd -F -c sampler.conf -x sock:10001
# For aggregator, foreground start
$ ldmsd -F -c aggregator.conf -x sock:10000

When listing the sets on the aggregator with -v option, you’ll see that only `meminfo` and `set_0` are recent. `thegroup` is only updated when its information changed. The rest of the sets only been looked-up, but not updated.

$ ldms_ls -x sock -p 10000 -v | grep update
thegroup: consistent, last update: Thu Jul 05 16:22:08 2018 [303411us]
set_3: inconsistent, last update: Wed Dec 31 18:00:00 1969 [0us]
set_2: inconsistent, last update: Wed Dec 31 18:00:00 1969 [0us]
set_1: inconsistent, last update: Wed Dec 31 18:00:00 1969 [0us]
set_0: consistent, last update: Thu Jul 05 16:36:30 2018 [1793us]
meminfo: consistent, last update: Thu Jul 05 16:36:31 2018 [1946us]

While when listing the sets on the sampler, we will see all of them being updated (except `thegroup`).

thegroup: consistent, last update: Thu Jul 05 16:22:08 2018 [303411us]
set_3: consistent, last update: Thu Jul 05 16:39:52 2018 [1915us]
set_2: consistent, last update: Thu Jul 05 16:39:52 2018 [1916us]
set_1: consistent, last update: Thu Jul 05 16:39:53 2018 [1948us]
set_0: consistent, last update: Thu Jul 05 16:39:53 2018 [1948us]
meminfo: consistent, last update: Thu Jul 05 16:39:53 2018 [2022us]

Removing/inserting instances from/into the group can also be done interactively via ldmsd_controller. If we do the following on the sampler:

$ ldmsd_controller --port 10001
Welcome to the LDMSD control processor
sock:localhost:10001> setgroup_rm name=thegroup instance=set_0
sock:localhost:10001> setgroup_ins name=thegroup instance=set_3

`set_0` will be removed from `thegroup`, and `set_3` will be added into `thegroup`. Listing the sets on the aggregator will see that `set_0` stopped being updated, and `set_3` becomes recent.

thegroup: consistent, last update: Thu Jul 05 16:42:12 2018 [378918us]
set_3: consistent, last update: Thu Jul 05 16:42:14 2018 [2070us]
set_2: inconsistent, last update: Wed Dec 31 18:00:00 1969 [0us]
set_1: inconsistent, last update: Wed Dec 31 18:00:00 1969 [0us]
set_0: consistent, last update: Thu Jul 05 16:41:25 2018 [1116us]
meminfo: consistent, last update: Thu Jul 05 16:42:15 2018 [1223us]

The members of the group can be listed by the following:

$ ldms_ls -x sock -p 10000 -v thegroup
thegroup: consistent, last update: Thu Jul 05 16:42:12 2018 [378918us]
  APPLICATION SET INFORMATION ------
         grp_member: set_3 : -
         grp_member: meminfo : -
             ldmsd_grp_gn : 8
  METADATA --------
    Producer Name : a:10001
    Instance Name : thegroup
      Schema Name : ldmsd_grp_schema
             Size : 184
     Metric Count : 1
               GN : 1
             User : root(0)
            Group : root(0)
      Permissions : -rwxrwxrwx
  DATA ------------
        Timestamp : Thu Jul 05 16:42:12 2018 [378918us]
         Duration : [0.000017s]
       Consistent : TRUE
             Size : 64
               GN : 8
  -----------------