Decomposition documentation and format need clarification/improvement

[morrone]

The ldmsd_decomposition man page is very confusing.

Right off the bat, the documentation presents that there are three seemingly equal decomposition mechanisms: as_is, static, and flex. This does not appear to match reality. There are really two kinds of decomposition: as_is and static. "flex" appears to be a wrapper around the the other decomposition methods. That should be explicitly stated.

It is insufficient to document the indices as "index definitions". Tell us what they are and how they are used. To the best of my knowledge they are hints to the store, and may or may not be used. If we know that they are not used, can we leave those out? It doesn't say.

There is an example in the "STATIC DECOMPOSITION" section showing "a static decomposition definition converting meminfo set into two schemas, "meminfo_filter" ... and "meminfo_directmap". It isn't even remotely clear how one would know that these rules should apply to the "meminfo" schema.

In the "FLEX DECOMPOSITION" sections, the example uses "DECOMP_1" as the label in the decomposition section, but "DECOMP_A" as the label in the digest section. I presume they were supposed to be the same. If not, I really don't understand how the digest section works, and that needs more documenation.

I would also recommend that we change the labels used in the flex decomposition so those labels do not conflict with standard sampler or schema names. It would be easy to think from the example that the field somehow match to schemas, when in reality they are just labels that match the digest section. Unless, again, I don't understand how it works, and in that case the documentation also needs improving.

[tom95858]

@morrone, I want to get rid of the three 'strategies' altogether and only support 'flex'. I think this is v4.5.1 work.