1 The LTTng Documentation: Contributor's guide
2 ============================================
6 This guide presents the structure and conventions of the LTTng
7 Documentation's source. Make sure you read it thoroughly before
8 you contribute a change.
14 The LTTng Documentation exists to make the
15 https://lttng.org/[LTTng project] useable.
16 Without such a complete documentation consolidating the various
17 concepts, features, and procedures of LTTng-tools, LTTng-UST, and
18 LTTng-modules, most of the project would only be useable by
21 Why not simply read the man pages? While the LTTng man pages are
22 complementary to the LTTng Documentation, they remain formal
23 references: they lack the introductory quality and procedural user
24 guides found in this documentation.
26 The core principle of the LTTng Documentation is to make the text as
27 cleverly organized, easy to follow, precise, and consistent as possible.
28 This involves keeping a high level of rigor as to such things as the
29 document's style, voice, grammar, and layout.
31 Of course, those guidelines are not new to the technical writing realm,
32 and it would be bold to devise a brand new manual of style for the sole
33 existence of the LTTng Documentation when so many have already proven
34 their value. This is why the LTTng Documentation (especially starting
35 from version 2.7) does its best to follow the rules of the
36 https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual
37 of Style (4th edition)], a landmark work in its field. Of particular
38 interest in this book are:
40 * Chapter 1, _Microsoft style and voice_.
41 * Chapter 6, _Procedures and technical content_.
42 * Chapter 7, _Practical issues of style_.
43 * Chapter 8, _Grammar_.
44 * Chapter 9, _Punctuation_.
45 * Chapter 11, _Acronyms and other abbreviations_.
47 The <<terminology,Terminology>> section of this contributor's guide
48 adds terms to or overrides terms of Part 2, _Usage Dictionary_.
51 == Organization of the repository and format
53 The Git repository of the LTTng Documentation contains all the official
54 versions of the documentation as separate source files. Each source file
55 is in its own +2.__x__+ directory, along with documentation resources
56 specific to this version of LTTng. You can find common source files in
57 the `common` directory.
59 The source files are written in
60 http://www.methods.co.nz/asciidoc/[AsciiDoc], a rich, lightweight markup
61 language with all the blocks and inline elements needed to write
62 backend-agnostic content.
64 Although the official LTTng website uses a custom script to generate
65 its own HTML version of the LTTng Documentation, it is possible to
66 generate an autonomous HTML preview (see
67 link:README.adoc[`README.adoc`]). The `asciidoc.html5.conf` AsciiDoc
68 configuration file sets a few attributes and implements the required
69 macros for this preview target.
74 Before you submit any change, make sure that the check script passes.
75 This is a Python script which validates some elements of a specific
78 You need the following dependencies to run the check script:
80 * http://www.methods.co.nz/asciidoc/[AsciiDoc]
82 * http://lxml.de/[lxml] Python 3 package
83 * https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package
88 python3 tools/check.py 2.7/lttng-docs-2.7.txt
91 Replace `2.7` by the version of the document to validate in the previous
95 == Style considerations
97 As stated in <<principles,Principles>>, the LTTng Documentation follows
98 the Microsoft Manual of Style (4th edition). We encourage you to read
99 this work before contributing a major change to the document.
101 You also need to consider the following rules, often specific to the
102 AsciiDoc format used to write the LTTng Documentation, when you edit
103 existing content or when you create new sections.
108 * **Man page references**: Always use the +man:__command__(__section__)+
109 macro when you refer to a man page.
111 .Using the `man` macro.
114 See man:lttng-ust(3) for more details about ...
118 * [[opt-macro]] **LTTng command-line options**: Starting from v2.8,
119 always use the +opt:__command__(__section__):__option__+ macro when
120 you refer to a command-line option described in an LTTng man page.
122 .Using the `opt` macro.
125 You can use the opt:lttng-enable-event(1):--filter option to set the
126 filter expression of an event rule.
130 * **File names**: Always use the +path:{__path__}+ macro when you need
131 to write a file name.
133 .Using the `path` macro.
136 Load the configuration file path:{hello.lttng} directory by default.
140 * **Directory names**: Always use the +dir:{__path__}+ macro when you
141 need to write a directory name.
143 .Using the `dir` macro.
146 Traces are recorded to the dir:{~/lttng-traces} directory by default.
150 * **Environment variable**: Always use the +env:__VAR__+ macro when you
151 need to write an environment variable name. +__VAR__+ must not contain
152 the shell's `$` prefix.
154 .Using the `env` macro.
157 You can set the env:LTTNG_UST_DEBUG environment variable to `1` to
158 activate LTTng-UST's debug output.
162 * **Command names**: Always use the +cmd:__cmd__+ macro when you need to
163 write a command name.
165 .Using the `cmd` macro.
168 Run cmd:lttng-sessiond as the root user.
175 Em dashes can usually be written using `--` in AsciiDoc, but sometimes
176 the two hyphens are outputted as is, for example if the character at the
177 left or at the right of them is a punctuation. You can avoid this
178 by using the equivalent `—` HTML entity.
180 .Using `--` for an em dash.
183 And yet, when the car was finally delivered--nearly three months after it
184 was ordered--she decided she no longer wanted it, leaving the dealer with
185 an oddly equipped car that would be difficult to sell.
189 .Using `—` for an em dash.
192 As the frequency of recorded events increases--either because the event
193 throughput is actually higher or because you enabled more events than
194 usual—__event loss__ might be experienced.
199 === Non-breaking spaces
201 Always use a non-breaking space (`{nbsp}`, or HTML entity ` `)
202 between a quantity and its unit, or when it would be unnatural to have
203 two related words split on two lines.
205 .Using a non-breaking space between a quantity and its unit.
208 The size of this file is 1039{nbsp}bytes.
212 .Using a non-breaking space to avoid an odd line break.
215 This integer is displayed in base{nbsp}16.
220 === Placeholders in inline code
222 When a section of an inline code element is a placeholder, or variable,
223 use the `+` form of the element (instead of +`+), and place `__`
224 around the placeholder.
226 .Using a placeholder in an inline code element.
229 Name your file +something.__sys__.c+, where +__sys__+ is your system name.
236 There are two types of listing blocks:
238 * [[term-box]]**Terminal boxes** are used to show commands to be entered in a
239 terminal exclusively, that is, the output of commands must not be
240 written in terminal boxes. A terminal box is an AsciiDoc literal
241 block with the `term` role.
243 Start a command line with "+${nbsp}+" to indicate that a regular Unix user
244 should run it. Start a command line with "+#{nbsp}+" to indicate that a
245 priviledged Unix user should run it.
247 .Using a terminal box.
253 $ lttng create my-session
254 $ lttng enable-event --kernel --all
259 The output of a command line can be written using a simple, role-less
262 * **Source code boxes** are used to show syntax-highlighted snippets of
263 source code. A source code box is an AsciiDoc source code block.
265 .Using a source code box.
275 puts("Hello, World!");
283 The second attribute is the name of the programming language for
284 proper syntax highlighting (for example, `c`, `python`, `make`, `java`).
285 This name must be known to http://pygments.org/[Pygments].
287 Always indent source code examples with 4{nbsp}spaces.
289 In any listing block, the lines must not exceed 80 characters (prefer a
290 maximum of 72 characters).
293 === Command-line options
295 When specifying command-line options:
297 * Always use the long form of the option (with two hyphens).
298 * **If the command which accepts this option is an LTTng program**,
299 use the <<opt-macro,`opt` macro>>. Otherwise use simple backticks.
300 * Always follow the option name by the _option_ word.
302 .Using a command-line option.
305 You can use the `lttng` tool's opt:lttng(1):--group option to specify a
306 custom tracing group.
310 In <<term-box,terminal boxes>>, always put `=` between the option name
311 and its argument, if any.
315 In this example, `provider:'sys_*'` is not the argument of the
316 `--userspace` option: it's the first positional argument, and
317 the `--userspace` option has no arguments.
323 $ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \
324 --exclude=sys_send,sys_block --loglevel=TRACE_INFO
332 Use an ordered list to write a procedure.
334 If a step is optional, prepend `**Optional**:` followed by a space to
335 the step's first sentence. Start the first sentence with a capital
336 letter. Do not use an optional step followed by a condition; use a
337 conditional step for this.
339 If a step is conditional, put the condition (_If something_) in bold,
340 followed by a comma, followed by the step itself.
345 When using a hyperlink to an LTTng repository's file or directory,
346 link to the GitHub code browser. Make sure to link to the appropriate
347 Git branch (usually +stable-2.__x__+). You can use the `revision`
348 attribute in the URL.
350 .Link to source file.
354 https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}]
355 for more details about [...]
362 If a whole section describes a feature which was introduced in LTTng 2.1
363 or later, add the +since-2.__x__+ role to the section's heading, where
364 +__x__+ is the minor version of the LTTng release which introduced
367 .Section heading describing a feature introduced in LTTng 2.5.
380 What follows is an official, partial list of technical terms used by the
381 LTTng Documentation. Other forms of those terms are _not_ permitted. For
382 example, do not write `use-case` or `filesystem`.
387 Do not use _autotools_.
390 The Babeltrace project, which includes the `babeltrace` command, some
391 libraries, and Python bindings.
393 Use +`babeltrace`+ to refer to the actual `babeltrace` command.
395 Babeltrace Python bindings::
396 The Python bindings of Babeltrace.
398 The plural _bindings_ is important.
406 A layout of tracing buffers applied to a given channel.
412 Prefer expanding this acronym to _command-line interface_ in the text.
415 A reference of time for a tracer.
417 Use _system time_ to refer to the date and time as seen by a user.
420 Adjective version of _command line_: _command-line option_,
421 _command-line interface_.
423 command-line interface::
424 An interface in which the user enters command lines to instruct the
427 Prefer using _command_ or _command-line tool_ to refer to a
431 An actual line of command entered by the user in a terminal, at a
434 Write _command-line_ when used as an adjective.
437 The LTTng consumer daemon.
439 Do not use _consumerd_.
441 Use +`lttng-consumerd`+ to refer to the consumer daemon
445 Do not use when referring to a _tracing domain_.
448 Occurrence recognised by software, emitted by a tracer when specific
449 conditions are met, at a given time. An event _occurs_ at a specific
450 time, after which a tracer can record its payload.
453 The mechanism by which event records of a given channel are lost
454 (not recorded) when there is no sub-buffer space left to store them.
457 The name of an event, which is also the name of the event record.
458 This is different from a _tracepoint name_, which is only the name
459 of the instrumentation point, not necessarily equal to the event
463 Record, in a trace, of the payload of an event which occured.
466 Set of conditions which must be satisfied for one or more events
467 to occur. The `lttng enable-event` command creates and enables
468 _event rules_, not _events_.
471 Contains directories, files, and links in an organized structure.
473 Do not use _filesystem_ or _file-system_.
475 +`java.util.logging`+::
476 Even though the `--jul` command-line option is an acronym for this
477 term, there is no such thing as _Java Util Logging_. The only
478 correct form is the name of the Java package,
479 +`java.util.logging`+.
482 The use of LTTng probes to make a software traceable.
487 Use _the C standard library_ to refer to the standard library for
488 the C programming language, or _glibc_ to refer to the GNU C Library
492 LTTng-UST supports Java logging using Apache _log4j_, not Apache
496 Level of severity of a log statement.
501 In general, do not use _kernel_ to refer to the _Linux kernel_: use
502 the whole _Linux kernel_ term, because other operating system kernels
503 exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng
506 Linux Trace Toolkit: next generation::
507 The expansion of the _LTTng_ acronym.
509 The colon and the lowercase _n_ and _g_ are important.
512 The LTTng-analyses project.
515 The LTTng-modules project.
518 The LTTng-tools project.
521 The LTTng-UST project.
523 LTTng-UST Java agent::
524 LTTng-UST Python agent::
525 An LTTng user space agent.
527 Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_.
529 LTTng Documentation::
530 The name of this project.
532 Do not use _LTTng documentation_.
534 When referring to the project, the _the_ determiner can be lowercase:
535 _Welcome to the LTTng Documentation!_.
538 The name of a communication protocol between Babeltrace and the
539 relay daemon which makes it possible to see events "live",
540 as they are received by the relay daemon.
544 the +`lttng`+ tool::
545 the +`lttng`+ command line tool::
546 The `lttng` command line tool.
548 When _tool_ has been mentioned in the previous sentences, you can use
549 +`lttng`+ alone.
552 An input for the make tool.
554 Do not use _makefile_ or _make file_.
557 Unix-style reference manual page.
561 per-process buffering::
562 A buffering scheme in which each process has its own buffer for a
563 given user space channel.
565 Do not use _per-PID buffering_.
568 A buffering scheme in which all the processes of a user share the same
569 buffer for a given user space channel.
571 Do not use _per-UID buffering_.
574 An instrumentation point.
576 Prefer _tracepoint_ when referring to a user space or Linux kernel
580 A clock which keeps track of the current time, including eventual
583 Do not use _realtime clock_ or _real time clock_.
586 The LTTng relay daemon.
590 Use +`lttng-relayd`+ to refer to the relay daemon executable.
593 A superuser of a Linux system.
595 Do not use +`root`+.
598 Do not use when referring to a _tracing session_.
601 The LTTng session daemon.
603 Do not use _sessiond_.
605 Use +`lttng-sessiond`+ to refer to the session daemon
609 Copy of the current data of all the buffers of a given tracing
610 session, saved as a trace.
613 One part of an LTTng ring buffer.
615 Do not use _subbuffer_ since it's harder to read with the two
619 Time information attached to an event when it is emitted. This is not
620 necessarily a _Unix timestamp_.
622 Do not use _time stamp_.
625 As a verb: a user or a tracer can _trace_ an application.
628 The Trace Compass project and application.
630 Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or
634 An instrumentation point using the tracepoint mechanism of
635 the Linux kernel or of LTTng-UST.
637 Do not use _trace point_ or _trace-point_.
639 tracepoint definition::
640 The definition of a single tracepoint.
643 The name of a _tracepoint_.
645 Not to be confused with an _event name_.
647 tracepoint provider::
648 A set of functions providing tracepoints to an instrumented user
651 Not to be confused with a _tracepoint provider package_: many tracepoint
652 providers can exist within a tracepoint provider package.
654 tracepoint provider package::
655 One or more tracepoint providers compiled as an object file or as
659 An LTTng tracing domain.
661 Always use the complete _tracing domain_ term, not _domain_ alone,
662 unless _tracing domain_ has been used in the few preceding sentences.
665 The Unix group in which a user can be to be allowed to trace the
668 Do not use _`tracing` group_, as the name of the tracing
669 group is configurable.
672 An LTTng tracing session.
674 Always use the complete _tracing session_ term, not _session_ alone.
677 Unix operating system or philosophy.
682 Absolute reference of a real-time clock.
684 Use the term as a proper noun: do not precede it with _the_.
686 Do not use _Epoch_ alone.
689 Timestamp represented as the number of seconds since Unix epoch.
692 According to Wikipedia: List of actions or event steps, typically
693 defining the interactions between a role and a system, to
699 An application running in user space, as opposed to a Linux kernel
702 Do not use _user space application_, as this is redundant.