man sysdig-chisel

[Hefeweizen]

Chisels have built-in descriptions, but further information, such as example usage would be awesome. This idea was started in the google group, but as an 'issue' we'll have better tracking.

One suggested implementation of this would be to add a usage block to each chisel. Some template could then be created that auto-builds a man page at package build time.

Such a template could also be used to auto-create a wiki page - however execution of this could be tricky. Would we clobber the previous wiki page, including additional commentary? My wiki skills are weak, so I don't know how hard it would be to just update a subsection of the wiki page.

[rmack]

Hey,

Thank you very much for submitting this feature request.

There have been some off-line discussions around this topic as well. We were discussing adding additional variable strings internal to each chisel which sysdig could pick up and then print out in the appropriate format. Currently this is done with the following variables in lua: description, short_description, and category given Sysdig Chisel API Reference Manual; which are a core requirement when building a chisel. Other categories could be included such as the examples below; with some of these examples being optional instead of mandatory.

In addition, there was also a quick discussion around making help more intuitive enabling users to dig into sysdig. Please see the referenced examples below; which includes a similar idea to yours. Please note it might be best to roll out changes and we could start with sudo sysdig -i [chisel_name] [flag] instead of -help or help. Example flags provided below.

Example only

Example flags

• [chisel_name] - print all relevant information
• description - only print the description
• filters - only print relevant sysdig filters
• arguments - only print argument information
• return - only print return information
• example - only print examples / usage

Examples and Info

• sudo sysdig -help chisel_name - List information about chisel_name, information, and help. Similar to a man page. And would potentially display all relevant information.
• sudo sysdig -help chisel_name filters - What filters are relevant to chisel_name
• sudo sysdig -help chisel_name arguments - What arguments are relevant to chisel_name.
• sudo sysdig -help chisel_name return - What return values, output format, and structures are relevant to chisel_name.
• sudo sysdig -help chisel_name example - All examples/usage to use this chisel, how to use it or usage.

I would be interested in discussing this in more detail here. Any input would be appreciated, thank you.

[Hefeweizen]

My entry point on all this was behaviour around ps/lsof/netstat and the behaviour of the thread_table. A long format discussion of this (man page style) should be external to these three*, both for normalization and also so that future chisels using the thread_table are implicitly included. I think the example/usage block works best as it allows capturing both the point-in-time caveat, but other interesting cases as well.

I think the example/usage section could get quite lengthy. The embedded description is currently a lua string. That could get tricky as entries get longer. I'm aware of perldoc (I'm using it as an example, not particularly advocating); would it make sense to have a syntax like that for writing example/usage sections in the chisel script?

But then, maybe I'm getting to far ahead. Just using lua strings allows us to get started. It's a straight-foward implementation that should involve no additional engineering to get out of later that we wouldn't have to do now to implement.

• an existing blog post already captures this discussion pretty well.

[ldegio]

I think that the example/usage block is a great idea. I agree that it could get long but, if well formatted, it would also act as documentation when people are reading the chisel source code.

Do we need other blocks other then the examples one? Return value might be useful, but is a bit ambiguous for scripts that could have anything ranging from a number to a full blown visualization as an output. Anything else?

Regarding the format, I propose markdown. It's easy, it's clear event when it's not formatted, and github picks it up automatically. This means you can link a file in the source code repo from the wiki, and it will render nicely (for example, this is a file in the repo). When we do a release, It would be pretty easy to extract the markdown from the chisels, put them in the single file, and push it to github. That would take care of versioning implicitly.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.