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 .Using a terminal box.
249 lttng create my-session
250 lttng enable-event --kernel --all
255 The output of a command line can be written using a simple, role-less
258 * **Source code boxes** are used to show syntax-highlighted snippets of
259 source code. A source code box is an AsciiDoc source code block.
261 .Using a source code box.
271 puts("Hello, World!");
279 The second attribute is the name of the programming language for
280 proper syntax highlighting (for example, `c`, `python`, `make`, `java`).
281 This name must be known to http://pygments.org/[Pygments].
283 Always indent source code examples with 4{nbsp}spaces.
285 In any listing block, the lines must not exceed 80 characters (prefer a
286 maximum of 72 characters).
289 === Command-line options
291 When specifying command-line options:
293 * Always use the long form of the option (with two hyphens).
294 * **If the command which accepts this option is an LTTng program**,
295 use the <<opt-macro,`opt` macro>>. Otherwise use simple backticks.
296 * Always follow the option name by the _option_ word.
298 .Using a command-line option.
301 You can use the `lttng` tool's opt:lttng(1):--group option to specify a
302 custom tracing group.
306 In <<term-box,terminal boxes>>, always put `=` between the option name
307 and its argument, if any.
311 In this example, `provider:'sys_*'` is not the argument of the
312 `--userspace` option: it's the first positional argument, and
313 the `--userspace` option has no arguments.
319 lttng enable-event --userspace provider:'sys_*' --filter='field < 23'
320 --exclude=sys_send,sys_block --loglevel=TRACE_INFO
328 Use an ordered list to write a procedure.
330 If a step is optional, prepend `**Optional**:` followed by a space to
331 the step's first sentence. Start the first sentence with a capital
332 letter. Do not use an optional step followed by a condition; use a
333 conditional step for this.
335 If a step is conditional, put the condition (_If something_) in bold,
336 followed by a comma, followed by the step itself.
341 When using a hyperlink to an LTTng repository's file or directory,
342 link to the GitHub code browser. Make sure to link to the appropriate
343 Git branch (usually +stable-2.__x__+). You can use the `revision`
344 attribute in the URL.
346 .Link to source file.
350 https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}]
351 for more details about [...]
358 If a whole section describes a feature which was introduced in LTTng 2.1
359 or later, add the +since-2.__x__+ role to the section's heading, where
360 +__x__+ is the minor version of the LTTng release which introduced
363 .Section heading describing a feature introduced in LTTng 2.5.
376 What follows is an official, partial list of technical terms used by the
377 LTTng Documentation. Other forms of those terms are _not_ permitted. For
378 example, do not write `use-case` or `filesystem`.
383 Do not use _autotools_.
386 The Babeltrace project, which includes the `babeltrace` command, some
387 libraries, and Python bindings.
389 Use +`babeltrace`+ to refer to the actual `babeltrace` command.
391 Babeltrace Python bindings::
392 The Python bindings of Babeltrace.
394 The plural _bindings_ is important.
402 A layout of tracing buffers applied to a given channel.
408 Prefer expanding this acronym to _command-line interface_ in the text.
411 A reference of time for a tracer.
413 Use _system time_ to refer to the date and time as seen by a user.
416 Adjective version of _command line_: _command-line option_,
417 _command-line interface_.
419 command-line interface::
420 An interface in which the user enters command lines to instruct the
423 Prefer using _command_ or _command-line tool_ to refer to a
427 An actual line of command entered by the user in a terminal, at a
430 Write _command-line_ when used as an adjective.
433 The LTTng consumer daemon.
435 Do not use _consumerd_.
437 Use +`lttng-consumerd`+ to refer to the consumer daemon
441 Do not use when referring to a _tracing domain_.
444 Occurrence recognised by software, emitted by a tracer when specific
445 conditions are met, at a given time. An event _occurs_ at a specific
446 time, after which a tracer can record its payload.
449 The mechanism by which event records of a given channel are lost
450 (not recorded) when there is no sub-buffer space left to store them.
453 The name of an event, which is also the name of the event record.
454 This is different from a _tracepoint name_, which is only the name
455 of the instrumentation point, not necessarily equal to the event
459 Record, in a trace, of the payload of an event which occured.
462 Set of conditions which must be satisfied for one or more events
463 to occur. The `lttng enable-event` command creates and enables
464 _event rules_, not _events_.
467 Contains directories, files, and links in an organized structure.
469 Do not use _filesystem_ or _file-system_.
471 +`java.util.logging`+::
472 Even though the `--jul` command-line option is an acronym for this
473 term, there is no such thing as _Java Util Logging_. The only
474 correct form is the name of the Java package,
475 +`java.util.logging`+.
478 The use of LTTng probes to make a software traceable.
483 Use _the C standard library_ to refer to the standard library for
484 the C programming language, or _glibc_ to refer to the GNU C Library
488 LTTng-UST supports Java logging using Apache _log4j_, not Apache
492 Level of severity of a log statement.
497 In general, do not use _kernel_ to refer to the _Linux kernel_: use
498 the whole _Linux kernel_ term, because other operating system kernels
499 exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng
502 Linux Trace Toolkit: next generation::
503 The expansion of the _LTTng_ acronym.
505 The colon and the lowercase _n_ and _g_ are important.
508 The LTTng-analyses project.
511 The LTTng-modules project.
514 The LTTng-tools project.
517 The LTTng-UST project.
519 LTTng-UST Java agent::
520 LTTng-UST Python agent::
521 An LTTng user space agent.
523 Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_.
525 LTTng Documentation::
526 The name of this project.
528 Do not use _LTTng documentation_.
530 When referring to the project, the _the_ determiner can be lowercase:
531 _Welcome to the LTTng Documentation!_.
534 The name of a communication protocol between Babeltrace and the
535 relay daemon which makes it possible to see events "live",
536 as they are received by the relay daemon.
540 the +`lttng`+ tool::
541 the +`lttng`+ command line tool::
542 The `lttng` command line tool.
544 When _tool_ has been mentioned in the previous sentences, you can use
545 +`lttng`+ alone.
548 An input for the make tool.
550 Do not use _makefile_ or _make file_.
553 Unix-style reference manual page.
557 per-process buffering::
558 A buffering scheme in which each process has its own buffer for a
559 given user space channel.
561 Do not use _per-PID buffering_.
564 A buffering scheme in which all the processes of a user share the same
565 buffer for a given user space channel.
567 Do not use _per-UID buffering_.
570 An instrumentation point.
572 Prefer _tracepoint_ when referring to a user space or Linux kernel
576 A clock which keeps track of the current time, including eventual
579 Do not use _realtime clock_ or _real time clock_.
582 The LTTng relay daemon.
586 Use +`lttng-relayd`+ to refer to the relay daemon executable.
589 A superuser of a Linux system.
591 Do not use +`root`+.
594 Do not use when referring to a _tracing session_.
597 The LTTng session daemon.
599 Do not use _sessiond_.
601 Use +`lttng-sessiond`+ to refer to the session daemon
605 Copy of the current data of all the buffers of a given tracing
606 session, saved as a trace.
609 One part of an LTTng ring buffer.
611 Do not use _subbuffer_ since it's harder to read with the two
615 Time information attached to an event when it is emitted. This is not
616 necessarily a _Unix timestamp_.
618 Do not use _time stamp_.
621 As a verb: a user or a tracer can _trace_ an application.
624 The Trace Compass project and application.
626 Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or
630 An instrumentation point using the tracepoint mechanism of
631 the Linux kernel or of LTTng-UST.
633 Do not use _trace point_ or _trace-point_.
635 tracepoint definition::
636 The definition of a single tracepoint.
639 The name of a _tracepoint_.
641 Not to be confused with an _event name_.
643 tracepoint provider::
644 A set of functions providing tracepoints to an instrumented user
647 Not to be confused with a _tracepoint provider package_: many tracepoint
648 providers can exist within a tracepoint provider package.
650 tracepoint provider package::
651 One or more tracepoint providers compiled as an object file or as
655 An LTTng tracing domain.
657 Always use the complete _tracing domain_ term, not _domain_ alone,
658 unless _tracing domain_ has been used in the few preceding sentences.
661 The Unix group in which a user can be to be allowed to trace the
664 Do not use _`tracing` group_, as the name of the tracing
665 group is configurable.
668 An LTTng tracing session.
670 Always use the complete _tracing session_ term, not _session_ alone.
673 Unix operating system or philosophy.
678 Absolute reference of a real-time clock.
680 Use the term as a proper noun: do not precede it with _the_.
682 Do not use _Epoch_ alone.
685 Timestamp represented as the number of seconds since Unix epoch.
688 According to Wikipedia: List of actions or event steps, typically
689 defining the interactions between a role and a system, to
695 An application running in user space, as opposed to a Linux kernel
698 Do not use _user space application_, as this is redundant.