docs: Add a manual / language reference / man page #1711

fbs · 2021-03-01T18:40:44Z

The reference_guide was meant to be a short guide to quickly see how a
feature works. It was never meant to be the place where all technical
details are discussed but as there was no better place that is where it
ended up.

This introduces a new place for all the technical details. It is
written in asciidoc as that, improves plain text readability (slighly
personal) and it is easy exportable to a lot of other formats which
makes it possible to use this for our man-page and website.

This is still work in progress but hoping to get some feedback on it.

Open questions:

do we want to render the asciidoc into man and add it to the repository or do we ask packages to add asciidoctor as a dependency?
do we want this to be one manpage or should we split it up into bpftrace and bpftrace-language (i'd prefer one page for now)
is there a reason to not use asciidoc and go to back to man instead? I chose adoc as its easier to read/write imo and it is readable in github.

TODO:

finish calls
finish probes
go over styling of html and man
strip details from the ref guide

Note that I don't expect this to be completely finished when the todo items are done. I'm hoping its good enough for a first version so we can expand later. We also have some behaviour that isn't clearly defined, I hope we can define them before we put it in the manpage.

danobi · 2021-03-05T00:49:06Z

do we want to render the asciidoc into man and add it to the repository or do we ask packages to add asciidoctor as a dependency?

I'd prefer if we only had source files. Less confusion and less stuff to forget to update. Also it looks like most distros have it already: https://pkgs.org/search/?q=asciidoctor

do we want this to be one manpage or should we split it up into bpftrace and bpftrace-language (i'd prefer one page for now)

One seems fine to me

is there a reason to not use asciidoc and go to back to man instead? I chose adoc as its easier to read/write imo and it is readable in github.

I'd really rather not write raw man pages. That sounds too painful. adoc seems appealing b/c it can generate reasonable .htmls and man pages.

danobi

Will review some more later

man/adoc/bpftrace.adoc

danobi · 2021-03-16T01:29:24Z

man/adoc/bpftrace.adoc

+
+Make this larger if you wish to read bigger strings with str().
+
+Beware that the BPF stack is small (512 bytes), and that you pay the toll again inside printf() (whilst


I'm not sure what "and that you pay the toll again inside printf() (whilst it ....)". Is this referring to the string constant or the scratch space needed for submitting an event to the perf event buffer?

If it's the latter, not sure we need to describe implementation details (as it might change later)

this is copy/pasta from the refguide, ill just leave it out :)

man/adoc/bpftrace.adoc

brendangregg · 2021-03-16T02:30:06Z

Yes, the reference guide is intended to be brief. As a general rule, I don't like to see a wall of text anywhere: there should be at least one heading visible on the screen at all times. This forces all sections to be less than one screenful.

I wouldn't delete things entirely from the reference guide, as it'll still be the number one place people do searches on. So things like BPFTRACE_STRLEN should still be mentioned, even if it's just a list of keywords and a reference. E.g., "For environment variables BPFTRACE_STRLEN, ..., ..., ..., see the xxx.doc". Then people can still search on it.

I don't understand bpftrace.adoc: it says its a man page. I think that's the right place for man page things, but not "all technical details." Right now we have:

Reference guide: brief summary of everything
Tool example files: where you can discuss anything about the tools.
internal_development.md: where you can discuss anything about the code.

So if we have a bunch of technical details including code snippits or command outputs that doesn't fit into those locations, then we can create another file for it. I hope we can come up with a name that makes sense. I'm not sure what though. The "bpftrace Appendix?" The "bpftrace Encyclopedia"?

It could also be a more of a community developed wiki, where people are free to dump stuff in there that might be useful for searching later on. Whereas we carefully review what goes into the official reference guide.

fbs · 2021-03-16T08:52:50Z

Yes, the reference guide is intended to be brief. As a general rule, I don't like to see a wall of text anywhere: there should be at least one heading visible on the screen at all times. This forces all sections to be less than one screenful.

I wouldn't delete things entirely from the reference guide, as it'll still be the number one place people do searches on. So things like BPFTRACE_STRLEN should still be mentioned, even if it's just a list of keywords and a reference. E.g., "For environment variables BPFTRACE_STRLEN, ..., ..., ..., see the xxx.doc". Then people can still search on it.

Yes i want to link to the env section of the manpage

I don't understand bpftrace.adoc: it says its a man page. I think that's the right place for man page things, but not "all technical details." Right now we have:
* Reference guide: brief summary of everything

* Tool example files: where you can discuss anything about the tools.

* internal_development.md: where you can discuss anything about the code.
So if we have a bunch of technical details including code snippits or command outputs that doesn't fit into those locations, then we can create another file for it. I hope we can come up with a name that makes sense. I'm not sure what though. The "bpftrace Appendix?" The "bpftrace Encyclopedia"?

The manpage I wrote documents:

flags
env vars
all the language details (builtins, calls, probetypes, types & pointers)
all the details about using bpftrace, address space, etc

It doesn't say anything about the internals or about the tools we ship, we have separate docs for it.

It could also be a more of a community developed wiki, where people are free to dump stuff in there that might be useful for searching later on. Whereas we carefully review what goes into the official reference guide.

Sounds good

fbs · 2021-03-16T08:52:57Z

thanks @danobi

fbs · 2021-06-26T23:27:03Z

man/adoc/bpftrace.adoc

+
+The second action block uses two probes, one for `open` and one for `openat`, and defines an action that prints the file being `open`ed as well as the `pid` and `comm` of the process that execute the syscall.
+See the <<Probe types>> section for details on the available probe types.
+


Feel like more words describing actions should go here, but i lack inspration

fbs · 2021-06-26T23:29:27Z

Took a while but I think im almost there. I still need to do the details of a few probe types but other than that I think its good enough for a first version.

man/adoc/bpftrace.adoc

fbs · 2021-07-09T21:31:10Z

Added the int syntax from #1900

fbs · 2021-07-10T09:32:02Z

I fixed the section naming thing so linking is easier now. I uploaded a html version as well http://dump.madhax.nl/bpftrace.html#functions-reg , this is what it would look like if we put it on bpftrace.org

fbs · 2021-07-10T09:34:05Z

Ready for review @danobi @viktormalik @brendangregg . There is always more to add but I think its good enough for a first man page

$ asciidoctor  man/adoc/bpftrace.adoc
$ open man/adoc/bpftrace.html
$ asciidoctor man/adoc/bpftrace.adoc  -b manpage
$ man man/adoc/bpftrace.8

man/adoc/bpftrace.adoc

viktormalik

Just a bunch of formatting/spelling suggestions. The content itself looks good.

man/adoc/bpftrace.adoc

danobi

Also I think we need a cmake rule to generate man page using asciidoctor + install it

man/adoc/bpftrace.adoc

danobi · 2021-07-15T23:22:15Z

man/adoc/bpftrace.adoc

+
+== Supported architectures
+
+x86_64, arm64 and s390x


Make these bullet points instead?

man/adoc/bpftrace.adoc

fbs · 2021-07-17T20:03:30Z

Addressed the comments.

all typos fixes are applied
new strftime has been added
function heading has changed from buf_t buf(...) to just buf
all other small comments have been addressed too

If there are no objections im hoping to merge this as is. CI integration etc can be done in a follow up. Once this is in we can update it as part of PRs instead of having to sync this PR the whole time :)

danobi · 2021-07-19T17:04:22Z

Yeah, let's get this in now so we can all commit changes to it. Looks fairly complete already

The reference_guide was meant to be a short guide to quickly see how a feature works. It was never meant to be the place where all technical details are discussed but as there was no better place that is where it ended up. This introduces a new place for all the technical details. It is written in asciidoc as that, improves plain text readability (slighly personal) and it is easy exportable to a lot of other formats which makes it possible to use this for our man-page and website.

fbs requested a review from brendangregg March 1, 2021 18:40

fbs force-pushed the manpage branch 2 times, most recently from 1ca2291 to 7325e19 Compare March 8, 2021 17:06

danobi reviewed Mar 16, 2021

View reviewed changes

fbs added this to the 0.13.0 milestone May 4, 2021

fbs added the docs Issues related to bpftrace documentation, man page, --help message, and error/warning messages. label May 4, 2021

fbs modified the milestones: 0.13.0, 0.14.0 Jun 19, 2021

fbs force-pushed the manpage branch 4 times, most recently from 7cba092 to 82f06a4 Compare June 26, 2021 23:26

fbs commented Jun 26, 2021

View reviewed changes

man/adoc/bpftrace.adoc Outdated Show resolved Hide resolved

fbs force-pushed the manpage branch from 82f06a4 to 0eb9201 Compare June 27, 2021 17:34

fbs marked this pull request as ready for review June 27, 2021 17:34

fbs force-pushed the manpage branch from 0eb9201 to 0022bb2 Compare June 27, 2021 17:36

fbs force-pushed the manpage branch from 0022bb2 to 4737d3f Compare July 9, 2021 21:31

fbs commented Jul 10, 2021

View reviewed changes

man/adoc/bpftrace.adoc Outdated Show resolved Hide resolved

fbs commented Jul 10, 2021

View reviewed changes

man/adoc/bpftrace.adoc Outdated Show resolved Hide resolved

viktormalik reviewed Jul 12, 2021

View reviewed changes

danobi reviewed Jul 15, 2021

View reviewed changes

danobi mentioned this pull request Jul 15, 2021

Support microsecond timestamps in strftime() #1922

Merged

3 tasks

fbs force-pushed the manpage branch from b80362b to 0d70f4f Compare July 17, 2021 20:01

danobi approved these changes Jul 19, 2021

View reviewed changes

fbs force-pushed the manpage branch from b292a75 to bddd13c Compare July 19, 2021 17:12

fbs merged commit e5bb5fe into bpftrace:master Jul 19, 2021

fbs deleted the manpage branch July 19, 2021 17:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add a manual / language reference / man page #1711

docs: Add a manual / language reference / man page #1711

fbs commented Mar 1, 2021 •

edited

Loading

danobi commented Mar 5, 2021

danobi left a comment

danobi Mar 16, 2021

fbs Jun 25, 2021

brendangregg commented Mar 16, 2021

fbs commented Mar 16, 2021

fbs commented Mar 16, 2021

fbs Jun 26, 2021

fbs commented Jun 26, 2021

fbs commented Jul 9, 2021

fbs commented Jul 10, 2021

fbs commented Jul 10, 2021

viktormalik left a comment

danobi left a comment

danobi Jul 15, 2021

fbs commented Jul 17, 2021

danobi commented Jul 19, 2021


		Make this larger if you wish to read bigger strings with str().

		Beware that the BPF stack is small (512 bytes), and that you pay the toll again inside printf() (whilst


		The second action block uses two probes, one for `open` and one for `openat`, and defines an action that prints the file being `open`ed as well as the `pid` and `comm` of the process that execute the syscall.
		See the <<Probe types>> section for details on the available probe types.

docs: Add a manual / language reference / man page #1711

docs: Add a manual / language reference / man page #1711

Conversation

fbs commented Mar 1, 2021 • edited Loading

danobi commented Mar 5, 2021

danobi left a comment

Choose a reason for hiding this comment

danobi Mar 16, 2021

Choose a reason for hiding this comment

fbs Jun 25, 2021

Choose a reason for hiding this comment

brendangregg commented Mar 16, 2021

fbs commented Mar 16, 2021

fbs commented Mar 16, 2021

fbs Jun 26, 2021

Choose a reason for hiding this comment

fbs commented Jun 26, 2021

fbs commented Jul 9, 2021

fbs commented Jul 10, 2021

fbs commented Jul 10, 2021

viktormalik left a comment

Choose a reason for hiding this comment

danobi left a comment

Choose a reason for hiding this comment

danobi Jul 15, 2021

Choose a reason for hiding this comment

fbs commented Jul 17, 2021

danobi commented Jul 19, 2021

fbs commented Mar 1, 2021 •

edited

Loading