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 you refer to a man page. The official online version of the
110 LTTng Documentation has hyperlinks to the correct online versions
111 of the LTTng man pages thanks to this macro.
113 .Using the `man` macro.
116 See man:lttng-ust(3) for more details about ...
120 * **File names**: Always use the +path:{__path__}+
121 macro when you need to write a file name.
123 .Using the `path` macro.
126 Load the configuration file path:{hello.lttng} directory by default.
130 * **Directory names**: Always use the +dir:{__path__}+
131 macro when you need to write a directory name.
133 .Using the `dir` macro.
136 Traces are recorded to the dir:{~/lttng-traces} directory by default.
140 * **Environment variable**: Always use the +env:__VAR__+ macro when
141 you need to write an environment variable name. +__VAR__+ must not
142 contain the shell's `$` prefix.
144 .Using the `env` macro.
147 You can set the env:LTTNG_UST_DEBUG environment variable to `1` to
148 activate LTTng-UST's debug output.
152 * **Command names**: Always use the +cmd:__cmd__+
153 macro when you need to write a command name.
155 .Using the `cmd` macro.
158 Run cmd:lttng-sessiond as the root user.
165 Em dashes can usually be written using `--` in AsciiDoc, but sometimes
166 the two hyphens are outputted as is, for example if the character at the
167 left or at the right of them is a punctuation. You can avoid this
168 by using the equivalent `—` HTML entity.
170 .Using `--` for an em dash.
173 And yet, when the car was finally delivered--nearly three months after it
174 was ordered--she decided she no longer wanted it, leaving the dealer with
175 an oddly equipped car that would be difficult to sell.
179 .Using `—` for an em dash.
182 As the frequency of recorded events increases--either because the event
183 throughput is actually higher or because you enabled more events than
184 usual—__event loss__ might be experienced.
189 === Non-breaking spaces
191 Always use a non-breaking space (`{nbsp}`, or HTML entity ` `)
192 between a quantity and its unit, or when it would be unnatural to have
193 two related words split on two lines.
195 .Using a non-breaking space between a quantity and its unit.
198 The size of this file is 1039{nbsp}bytes.
202 .Using a non-breaking space to avoid an odd line break.
205 This integer is displayed in base{nbsp}16.
210 === Placeholders in inline code
212 When a section of an inline code element is a placeholder, or variable,
213 use the `+` form of the element (instead of +`+), and place `__`
214 around the placeholder.
216 .Using a placeholder in an inline code element.
219 Name your file +something.__sys__.c+, where +__sys__+ is your system name.
226 There are two types of listing blocks:
228 * [[term-box]]**Terminal boxes** are used to show commands to be entered in a
229 terminal exclusively, that is, the output of commands must not be
230 written in terminal boxes. A terminal box is an AsciiDoc literal
231 block with the `term` role.
233 .Using a terminal box.
239 lttng create my-session
240 lttng enable-event --kernel --all
245 The output of a command line can be written using a simple, role-less
248 * **Source code boxes** are used to show syntax-highlighted snippets of
249 source code. A source code box is an AsciiDoc source code block.
251 .Using a source code box.
261 puts("Hello, World!");
269 The second attribute is the name of the programming language for
270 proper syntax highlighting (for example, `c`, `python`, `make`, `java`).
271 This name must be known to http://pygments.org/[Pygments].
273 Always indent source code examples with 4{nbsp}spaces.
275 In any listing block, the lines must not exceed 80 characters (prefer a
276 maximum of 72 characters).
279 === Command-line options
281 When specifying command-line options:
283 * Always use the long form of the option (with two hyphens).
284 * Use a code element for the option name (backticks).
285 * Always follow the option name by the _option_ word.
287 .Using a command-line option.
290 You can use the `lttng` tool's `--group` option to specify a custom
295 In <<term-box,terminal boxes>>, always put `=` between the option name
296 and its argument, if any.
300 In this example, `provider:'sys_*'` is not the argument of the
301 `--userspace` option: it's the first positional argument, and
302 the `--userspace` option has no arguments.
308 lttng enable-event --userspace provider:'sys_*' --filter='field < 23'
309 --exclude=sys_send,sys_block --loglevel=TRACE_INFO
317 Use an ordered list to write a procedure.
319 If a step is optional, prepend `**Optional**:` followed by a space to
320 the step's first sentence. Start the first sentence with a capital
321 letter. Do not use an optional step followed by a condition; use a
322 conditional step for this.
324 If a step is conditional, put the condition (_If something_) in bold,
325 followed by a comma, followed by the step itself.
330 When using a hyperlink to an LTTng repository's file or directory,
331 link to the GitHub code browser. Make sure to link to the appropriate
332 Git branch (usually +stable-2.__x__+). You can use the `revision`
333 attribute in the URL.
335 .Link to source file.
339 https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}]
340 for more details about [...]
347 If a whole section describes a feature which was introduced in LTTng 2.1
348 or later, add the +since-2.__x__+ role to the section's heading, where
349 +__x__+ is the minor version of the LTTng release which introduced
352 .Section heading describing a feature introduced in LTTng 2.5.
365 What follows is an official, partial list of technical terms used by the
366 LTTng Documentation. Other forms of those terms are _not_ permitted. For
367 example, do not write `use-case` or `filesystem`.
372 Do not use _autotools_.
375 The Babeltrace project, which includes the `babeltrace` command, some
376 libraries, and Python bindings.
378 Use +`babeltrace`+ to refer to the actual `babeltrace` command.
380 Babeltrace Python bindings::
381 The Python bindings of Babeltrace.
383 The plural _bindings_ is important.
391 A layout of tracing buffers applied to a given channel.
397 Prefer expanding this acronym to _command-line interface_ in the text.
400 A reference of time for a tracer.
402 Use _system time_ to refer to the date and time as seen by a user.
405 Adjective version of _command line_: _command-line option_,
406 _command-line interface_.
408 command-line interface::
409 An interface in which the user enters command lines to instruct the
412 Prefer using _command_ or _command-line tool_ to refer to a
416 An actual line of command entered by the user in a terminal, at a
419 Write _command-line_ when used as an adjective.
422 The LTTng consumer daemon.
424 Do not use _consumerd_.
426 Use +`lttng-consumerd`+ to refer to the consumer daemon
430 Do not use when referring to a _tracing domain_.
433 Occurrence recognised by software, emitted by a tracer when specific
434 conditions are met, at a given time. An event _occurs_ at a specific
435 time, after which a tracer can record its payload.
438 The mechanism by which event records of a given channel are lost
439 (not recorded) when there is no sub-buffer space left to store them.
442 The name of an event, which is also the name of the event record.
443 This is different from a _tracepoint name_, which is only the name
444 of the instrumentation point, not necessarily equal to the event
448 Record, in a trace, of the payload of an event which occured.
451 Set of conditions which must be satisfied for one or more events
452 to occur. The `lttng enable-event` command creates and enables
453 _event rules_, not _events_.
456 Contains directories, files, and links in an organized structure.
458 Do not use _filesystem_ or _file-system_.
460 +`java.util.logging`+::
461 Even though the `--jul` command-line option is an acronym for this
462 term, there is no such thing as _Java Util Logging_. The only
463 correct form is the name of the Java package,
464 +`java.util.logging`+.
467 The use of LTTng probes to make a software traceable.
472 Use _the C standard library_ to refer to the standard library for
473 the C programming language, or _glibc_ to refer to the GNU C Library
477 LTTng-UST supports Java logging using Apache _log4j_, not Apache
481 Level of severity of a log statement.
486 In general, do not use _kernel_ to refer to the _Linux kernel_: use
487 the whole _Linux kernel_ term, because other operating system kernels
488 exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng
491 Linux Trace Toolkit: next generation::
492 The expansion of the _LTTng_ acronym.
494 The colon and the lowercase _n_ and _g_ are important.
497 The LTTng-analyses project.
500 The LTTng-modules project.
503 The LTTng-tools project.
506 The LTTng-UST project.
508 LTTng-UST Java agent::
509 LTTng-UST Python agent::
510 An LTTng user space agent.
512 Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_.
514 LTTng Documentation::
515 The name of this project.
517 Do not use _LTTng documentation_.
519 When referring to the project, the _the_ determiner can be lowercase:
520 _Welcome to the LTTng Documentation!_.
523 The name of a communication protocol between Babeltrace and the
524 relay daemon which makes it possible to see events "live",
525 as they are received by the relay daemon.
529 the +`lttng`+ tool::
530 the +`lttng`+ command line tool::
531 The `lttng` command line tool.
533 When _tool_ has been mentioned in the previous sentences, you can use
534 +`lttng`+ alone.
537 An input for the make tool.
539 Do not use _makefile_ or _make file_.
542 Unix-style reference manual page.
546 per-process buffering::
547 A buffering scheme in which each process has its own buffer for a
548 given user space channel.
550 Do not use _per-PID buffering_.
553 A buffering scheme in which all the processes of a user share the same
554 buffer for a given user space channel.
556 Do not use _per-UID buffering_.
559 An instrumentation point.
561 Prefer _tracepoint_ when referring to a user space or Linux kernel
565 A clock which keeps track of the current time, including eventual
568 Do not use _realtime clock_ or _real time clock_.
571 The LTTng relay daemon.
575 Use +`lttng-relayd`+ to refer to the relay daemon executable.
578 A superuser of a Linux system.
580 Do not use +`root`+.
583 Do not use when referring to a _tracing session_.
586 The LTTng session daemon.
588 Do not use _sessiond_.
590 Use +`lttng-sessiond`+ to refer to the session daemon
594 Copy of the current data of all the buffers of a given tracing
595 session, saved as a trace.
598 One part of an LTTng ring buffer.
600 Do not use _subbuffer_ since it's harder to read with the two
604 Time information attached to an event when it is emitted. This is not
605 necessarily a _Unix timestamp_.
607 Do not use _time stamp_.
610 As a verb: a user or a tracer can _trace_ an application.
613 The Trace Compass project and application.
615 Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or
619 An instrumentation point using the tracepoint mechanism of
620 the Linux kernel or of LTTng-UST.
622 Do not use _trace point_ or _trace-point_.
624 tracepoint definition::
625 The definition of a single tracepoint.
628 The name of a _tracepoint_.
630 Not to be confused with an _event name_.
632 tracepoint provider::
633 A set of functions providing tracepoints to an instrumented user
636 Not to be confused with a _tracepoint provider package_: many tracepoint
637 providers can exist within a tracepoint provider package.
639 tracepoint provider package::
640 One or more tracepoint providers compiled as an object file or as
644 An LTTng tracing domain.
646 Always use the complete _tracing domain_ term, not _domain_ alone,
647 unless _tracing domain_ has been used in the few preceding sentences.
650 The Unix group in which a user can be to be allowed to trace the
653 Do not use _`tracing` group_, as the name of the tracing
654 group is configurable.
657 An LTTng tracing session.
659 Always use the complete _tracing session_ term, not _session_ alone.
662 Unix operating system or philosophy.
667 Absolute reference of a real-time clock.
669 Use the term as a proper noun: do not precede it with _the_.
671 Do not use _Epoch_ alone.
674 Timestamp represented as the number of seconds since Unix epoch.
677 According to Wikipedia: List of actions or event steps, typically
678 defining the interactions between a role and a system, to
684 An application running in user space, as opposed to a Linux kernel
687 Do not use _user space application_, as this is redundant.