On Mon, Nov 14, 2016 at 11:34:18AM +0100, Simon Horman wrote: > > Sometimes a description like above appears in your example, is it just > > for a few fields or do you intend to describe all of them ? I'm asking > > because we don't have such descriptions right now, and while I won't > > deny that forcing contributors to add one when adding new stats could be > > reasonable (it's like doc), I fear that it would significantly inflate > > the output. > > My understanding is that the description is part of the schema but would > not be included in a JSON instance. Or on other words, would not > be included in the output of a show command.
OK. So does this mean that a schema will have to be maintained by hand in parallel or will it be deduced from the dump ? I'm starting to be worried about something not being kept up to date if we have to maintain it, or causing a slow down in adoption of new stats entries. > My intention was to add descriptions for all fields. But in many case > the field name seemed to be sufficiently descriptive or at least I couldn't > think of a better description. And in such cases I omitted the description > to avoid being repetitive. OK that's a good point. So we can possibly have a first implementation reusing the field name everywhere, and later make these descriptions mandatory in the code for new fields so that the output description becomes more readable. > I do not feel strongly about the descriptions. I'm happy to remove some or > all of them if they are deemed unnecessary or otherwise undesirable; to add > them to every field for consistency; or something in between. I think dumping only known descriptions and falling back to the name (or simply suggesting that the consumer just uses the same when there's no desc) sounds reasonable to me for now. > > Also, do you have an idea about the verbosity of the dump here ? For > > example let's say you have 100 listeners with 4 servers each (which is > > an average sized config). I'm just looking for a rought order of magnitude, > > ie closer to 10-100k or to 1-10M. The typed output is already quite heavy > > for large configs so it should not be a big deal, but it's something we > > have to keep in mind. > > I don't think the type, description, etc... should be included in such > output as they can be supplied by the schema out-of-band. But the field > name and values along with syntactic elements (brackets, quotes, etc...) do > need to be included. OK. > I can try and come up with an estimate if it is > important but my guess is the result would be several times the size of the > typed output (mainly owing to the size of the field names in the output). No, don't worry, this rough estimate is enough. Cheers, Willy
