Hi Willy, On Mon, Nov 14, 2016 at 03:10:18PM +0100, Willy Tarreau wrote: > 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.
I envisage the schema being maintained in the same way that documentation is. In the draft schema I posted it should not be necessary to update each time a new item is added to the output of show flow or show info. Rather, the schema would need to be updated if the format of the data changes some how: f.e. a new field is added which would be analagous to adding a new column to the output of typed output, or a new type of value, such as u16, was added. > > 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. -- Simon Horman si...@horms.nl Horms Solutions BV www.horms.nl Parnassusweg 819, 1082 LZ Amsterdam, Netherlands Tel: +31 (0)20 800 6155 Skype: horms7
