On Tue, Nov 18, 2014 at 11:45 AM, Joshua M. Clulow <j...@sysmgr.org> wrote:
> On 18 November 2014 10:18, Matthew Ahrens <mahr...@delphix.com> wrote:
> > But more importantly, I presume the JSON output will become a stable
> > interface. Does anyone else have opinions on this?
>
> I have some opinions, based on our use of JSON output from a number of
> tools at Joyent.
>
> >>> On Mon, Nov 17, 2014 at 10:22 AM, Francois Billard
> >>> <francois.bill...@alyseo.com> wrote:
> >>>> the good format is (what we have implemented):
> >>>> {
> >>>> "NAME" : "rpool",
> >>>> "USED" : "1.63G",
> >>>> "REFER" : "404M"
> >>>> }
> >>>>
> >>>> if you want the structure of a specified pool, you must specify it in
> >>>> the command as :
> >>>> "zfs list <pool name>"
>
> This seems a reasonable structure to me, except that I would make the
> keys precisely the same string (case included) as what would be
> specified in the "-o" arguments, rather than using the value that
> would display in the headings for human readable output.
And rather than using the standard property name (e.g. "referenced")? This
seems less standardized to me, but I guess parroting back the way they
specified it (e.g. "RefeR") should be workable as well.
> I would also
> suggest that the JSON format should _always_ contain parseable values,
> not human-readable values -- i.e. "1750199173" rather than "1.63G".
>
I agree.
>
> I would also suggest that the output should be _streaming_, rather
> than built in advance and emitted at the end of the run. Using
> linefeed-delimited JSON, where one JSON object appears on each "line"
> of output, makes for a more scalable output format. It consumes less
> memory to assemble for emission and less memory to parse the resultant
> output with, e.g. JSON.parse() in Javascript.
>
This implies that the sorting flags (-s / -S) would be invalid with -J, and
the output would be in nondeterministic order.
> To give a concrete example, I would expect the tool to output
> something like this:
>
> # zfs list -J -o name,used,refer
> {"name":"rpool","used":"1750199173","refer":"423624704"}
> {"name":"rpool/data","used":"1024","refer":"1024"}
> {"name":"rpool/data/child","used:"100","refer":"100"}
>
> Note that each line is a separate JSON object, which may be emitted
> immediately and parsed separately. I would also _not_ include any
> kind of header record, or information about the command that was run,
> in the output.
>
>
>
> Cheers.
>
> --
> Joshua M. Clulow
> UNIX Admin/Developer
> http://blog.sysmgr.org
>
_______________________________________________
developer mailing list
developer@open-zfs.org
http://lists.open-zfs.org/mailman/listinfo/developer
