VSC self-documentation

[Poul-Henning Kamp]

I have been prototyping the extensible VSC-stuff for some days and
this is a progress report of sorts.

The major issue with extensible VSC's is that they need to document
themselves so varnishstat(1) and other VSM users can understand them.

The layout of a VSM segment follows directly from that:

	{
	uint64_t	offset_to_doc;	// N * 8
	uint64_t	counters[N];
	char		doc[];
	}

The documentation should have 1+N parts, a "head" which explains what
this set of counters is about, and a "stanza" for each counter.

The 'stanza' tells the type (counter/gauge/bitmap), the level
(info/diag/debug) and maybe also unit of this counter.

It must have a "oneliner" and optionally also a multi-paragraph
"long" explanation.

And then we run into the how do we encode that in the VSM segment
thing, and after looking at all the alternatives I could imagine,
I end up with JSON ... again, again, again.

I have a small, 500 LOC, json parser in C we can use, so that is
not going to drag in a dependency.

If we're going to bite the JSON bullet, the other places it makes
sense to use it, is for the vcc_if.c::Vmod_Spec data structure
which explains the contents of a VMOD to VCC.

Given that we are going to expand what VMODs can contain, that
"minilanguage" needs expansion too, so all in all, I think we
are over the threshold were JSON makes sense.

... but I still feel dirty using JSON to pass data structures
from one C-program to another, or as it may be, from a python
program to another.

Poul-Henning

-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
phk at FreeBSD.ORG         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe
Never attribute to malice what can adequately be explained by incompetence.