combine not honoring comments location

[SID800]

The problem

ksconf combine moves comment lines around in the target files. This makes it challenging to understand the comments intentions. It also reorders (sort?) the stanzas, which can sound like a good idea... until that alters the logical flow of the code within a .conf file. Yes, I realize it does not change how Splunk parses/combines the configs, but often developers place things in a certain order on purpose.

Environment

• Ksconf version: ksconf 0.7.7rc3 (Build 449)
• OS & version used: windows
• Python version: 2.7.16 (c:\python27\python.exe)
• Installed via: pip

Details

Here is an Splunk_TA_Windows original /default/wmi.conf

and wmi.conf after ksconf combine (I have no local changes so this should just be a file copy).

Note how the comments related to [WMI:LocalApplication] were moved under [settings] which would lead an admin astray.

[lowell80]

Yes, this is a known limitation. The solution requires re-writing the parser so that comments are no longer just second-class citizens. I mean, they will always be "lesser" because they don't have any functional impact, but they should be preserved, where possible.

Where do comments belong?

Sometimes it's impossible to always determine what entity a comment should be associated to. Take for example:

# Global comment

# Thoughts about my stanza
[cool_stanza]
attribute1 = x
# comment about attr2
attr = some complex thing
....

How can the parser know if a comment goes with the stanza before or after it? How do you know if a comment should be pinned to an attribute? Should the comment be before or after the attribute?
It will never be fully correct.

I eventually want the option to (where possible) preserve stanza ordering and/or key ordering on a file-by-file basis. Specifically props.conf and transforms.conf are often managed by hand, where comments greatly enhance reliability. But for now pretty much every time ksconf writes to a.conf file, that file is sorted (and normalized); (ksconf unarchive is one exception; all files are expanded as-is). Typically this is a good thing, and some places this will be unavoidable, but I want it to be more flexible in the future.

Current behavior

Right now the behavior is:

1. Stanzas are sorted by their name.
2. Comments always go with the stanza above it. (I've gotten decent leverage by just keeping all my comments at the very top of the stanzas; and if I'm commenting on an attribute I'm careful to NAME the attribute at the front of the comment.) Global comments are normally handled okay typically, because they are considered to be part of the default/global/top-level stanza.
3. Attribute names are sorted.
4. Comment order is preserved (per stanza); but comments mixed with attributes are moved to the top of the stanza, in the order they occur.
5. Sorting can be blocked on individual files by using the KSCONF-NO-SORT magic "marker". But this only works for the sort command, anytime ksconf has to write to a conf file, the result will be a sorted file.

Preserving order with complex commands

Certain operations, like merge, combine, or promote are very likely never going to support preservation of comments. And the reason is that it gets too complex too fast, and it hasn't been worth the effort to try to implement this.

How should comments be "meged"? Suppose we could solve the above problem of figuring out where a comment belongs. The next question is how would you merge them across stanzas? Should identical comments be suppressed and just outputted once? What if an identical lines are in a different order between two files? What if the same comment is present in 3 out of 4 files, and the 4th file is the highest precedence. Should that comment be removed?

The primary purpose of these higher-order tools is to provide output that's usable by Splunk; not humans.

If ksconf gets widely adopted by app developers and they really need this feature; then I'm sure we could come up with some meta-language or markup feature to "inject" comments into the output files. But I think that would end up being way to tedious for anyone simply trying to manage their own Splunk environment (so I'd consider that a different feature entirely.)

As much as it annoys me to have my comments screwed up; I've learned to live with it (at least for now). I haven't been able to justify prioritizing the effort required to properly fix this over all the other things that make a functional impact.

Also keep in mind, that any conf file that Splunk edits is subject to the same potential chaotic updates ;-(

TL;DR

1. Yes this is a known limitation
2. Your comments will be kept with the correct stanza if you move them down into the body of a stanza rather than before it. (It felt weird to me at first, but I got used to it. Best option for now.)
3. It may be fixed when the core parser is reworked, however:
4. Don't expect it to be available for all commands.

[lowell80]

Reviewing tickets and just realized that I didn't point out the other obvious solution. Just place the string KSCONF-NO-SORT in a comment at the top of the file that that will prevent some commands from touching it, like ksconf sort. I used this for files that I really want to maintain myself, which is often props.conf for me. I like to add example log messages along side the EXTRACT-* entries so that I can see the different variations as I have to update the regexes over time. Also, indexes.conf and searchbnf.conf....