The LTTng Documentation: Contributor's guide ============================================ Philippe Proulx v1.0, 26 October 2016 This guide presents the structure and conventions of the LTTng Documentation's source. Make sure you read it thoroughly before you contribute a change. [[principles]] == Principles The LTTng Documentation exists to make the https://lttng.org/[LTTng project] useable. Without such a complete documentation consolidating the various concepts, features, and procedures of LTTng-tools, LTTng-UST, and LTTng-modules, most of the project would only be useable by its authors. Why not simply read the man pages? While the LTTng man pages are complementary to the LTTng Documentation, they remain formal references: they lack the introductory quality and procedural user guides found in this documentation. The core principle of the LTTng Documentation is to make the text as cleverly organized, easy to follow, precise, and consistent as possible. This involves keeping a high level of rigor as to such things as the document's style, voice, grammar, and layout. Of course, those guidelines are not new to the technical writing realm, and it would be bold to devise a brand new manual of style for the sole existence of the LTTng Documentation when so many have already proven their value. This is why the LTTng Documentation (especially starting from version 2.7) does its best to follow the rules of the https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual of Style (4th edition)], a landmark work in its field. Of particular interest in this book are: * Chapter 1, _Microsoft style and voice_. * Chapter 6, _Procedures and technical content_. * Chapter 7, _Practical issues of style_. * Chapter 8, _Grammar_. * Chapter 9, _Punctuation_. * Chapter 11, _Acronyms and other abbreviations_. The <> section of this contributor's guide adds terms to or overrides terms of Part 2, _Usage Dictionary_. == Organization of the repository and format The Git repository of the LTTng Documentation contains all the official versions of the documentation as separate source files. Each source file is in its own +2.__x__+ directory, along with documentation resources specific to this version of LTTng. You can find common source files in the `common` directory. The source files are written in http://www.methods.co.nz/asciidoc/[AsciiDoc], a rich, lightweight markup language with all the blocks and inline elements needed to write backend-agnostic content. Although the official LTTng website uses a custom script to generate its own HTML version of the LTTng Documentation, it is possible to generate an autonomous HTML preview (see link:README.adoc[`README.adoc`]). The `asciidoc.html5.conf` AsciiDoc configuration file sets a few attributes and implements the required macros for this preview target. == Validation script Before you submit any change, make sure that the check script passes. This is a Python script which validates some elements of a specific document. You need the following dependencies to run the check script: * http://www.methods.co.nz/asciidoc/[AsciiDoc] * Python 3 * http://lxml.de/[lxml] Python 3 package * https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package Run the check script: ---- python3 tools/check.py 2.7/lttng-docs-2.7.txt ---- Replace `2.7` by the version of the document to validate in the previous command line. == Style considerations As stated in <>, the LTTng Documentation follows the Microsoft Manual of Style (4th edition). We encourage you to read this work before contributing a major change to the document. You also need to consider the following rules, often specific to the AsciiDoc format used to write the LTTng Documentation, when you edit existing content or when you create new sections. === Macros * **Man page references**: Always use the +man:__command__(__section__)+ macro when you refer to a man page. + .Using the `man` macro. ==== ---- See man:lttng-ust(3) for more details about ... ---- ==== * [[opt-macro]] **LTTng command-line options**: Starting from v2.8, always use the +opt:__command__(__section__):__option__+ macro when you refer to a command-line option described in an LTTng man page. + .Using the `opt` macro. ==== ---- You can use the opt:lttng-enable-event(1):--filter option to set the filter expression of an event rule. ---- ==== * **File names**: Always use the +path:{__path__}+ macro when you need to write a file name. + .Using the `path` macro. ==== ---- Load the configuration file path:{hello.lttng} directory by default. ---- ==== * **Directory names**: Always use the +dir:{__path__}+ macro when you need to write a directory name. + .Using the `dir` macro. ==== ---- Traces are recorded to the dir:{~/lttng-traces} directory by default. ---- ==== * **Environment variable**: Always use the +env:__VAR__+ macro when you need to write an environment variable name. +__VAR__+ must not contain the shell's `$` prefix. + .Using the `env` macro. ==== ---- You can set the env:LTTNG_UST_DEBUG environment variable to `1` to activate LTTng-UST's debug output. ---- ==== * **Command names**: Always use the +cmd:__cmd__+ macro when you need to write a command name. + .Using the `cmd` macro. ==== ---- Run cmd:lttng-sessiond as the root user. ---- ==== === Dashes Em dashes can usually be written using `--` in AsciiDoc, but sometimes the two hyphens are outputted as is, for example if the character at the left or at the right of them is a punctuation. You can avoid this by using the equivalent `—` HTML entity. .Using `--` for an em dash. ==== ---- And yet, when the car was finally delivered--nearly three months after it was ordered--she decided she no longer wanted it, leaving the dealer with an oddly equipped car that would be difficult to sell. ---- ==== .Using `—` for an em dash. ==== ---- As the frequency of recorded events increases--either because the event throughput is actually higher or because you enabled more events than usual—__event loss__ might be experienced. ---- ==== === Non-breaking spaces Always use a non-breaking space (`{nbsp}`, or HTML entity ` `) between a quantity and its unit, or when it would be unnatural to have two related words split on two lines. .Using a non-breaking space between a quantity and its unit. ==== ---- The size of this file is 1039{nbsp}bytes. ---- ==== .Using a non-breaking space to avoid an odd line break. ==== ---- This integer is displayed in base{nbsp}16. ---- ==== === Placeholders in inline code When a section of an inline code element is a placeholder, or variable, use the `+` form of the element (instead of +`+), and place `__` around the placeholder. .Using a placeholder in an inline code element. ==== ---- Name your file +something.__sys__.c+, where +__sys__+ is your system name. ---- ==== === Listing blocks There are two types of listing blocks: * [[term-box]]**Terminal boxes** are used to show commands to be entered in a terminal exclusively, that is, the output of commands must not be written in terminal boxes. A terminal box is an AsciiDoc literal block with the `term` role. + Start a command line with "+${nbsp}+" to indicate that a regular Unix user should run it. Start a command line with "+#{nbsp}+" to indicate that a priviledged Unix user should run it. + .Using a terminal box. ==== [listing] .... [role="term"] ---- $ lttng create my-session $ lttng enable-event --kernel --all ---- .... ==== + The output of a command line can be written using a simple, role-less listing block. * **Source code boxes** are used to show syntax-highlighted snippets of source code. A source code box is an AsciiDoc source code block. + .Using a source code box. ==== [listing] .... [source,c] ---- #include int main(void) { puts("Hello, World!"); return 0; } ---- .... ==== + The second attribute is the name of the programming language for proper syntax highlighting (for example, `c`, `python`, `make`, `java`). This name must be known to http://pygments.org/[Pygments]. + Always indent source code examples with 4{nbsp}spaces. In any listing block, the lines must not exceed 80 characters (prefer a maximum of 72 characters). === Command-line options When specifying command-line options: * Always use the long form of the option (with two hyphens). * **If the command which accepts this option is an LTTng program**, use the <>. Otherwise use simple backticks. * Always follow the option name by the _option_ word. .Using a command-line option. ==== ---- You can use the `lttng` tool's opt:lttng(1):--group option to specify a custom tracing group. ---- ==== In <>, always put `=` between the option name and its argument, if any. .Terminal box. ==== In this example, `provider:'sys_*'` is not the argument of the `--userspace` option: it's the first positional argument, and the `--userspace` option has no arguments. [listing] .... [role="term"] ---- $ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \ --exclude=sys_send,sys_block --loglevel=TRACE_INFO ---- .... ==== === Procedures Use an ordered list to write a procedure. If a step is optional, prepend `**Optional**:` followed by a space to the step's first sentence. Start the first sentence with a capital letter. Do not use an optional step followed by a condition; use a conditional step for this. If a step is conditional, put the condition (_If something_) in bold, followed by a comma, followed by the step itself. === External links When using a hyperlink to an LTTng repository's file or directory, link to the GitHub code browser. Make sure to link to the appropriate Git branch (usually +stable-2.__x__+). You can use the `revision` attribute in the URL. .Link to source file. ==== ---- See the file https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}] for more details about [...] ---- ==== === "Since" sections If a whole section describes a feature which was introduced in LTTng 2.1 or later, add the +since-2.__x__+ role to the section's heading, where +__x__+ is the minor version of the LTTng release which introduced the feature. .Section heading describing a feature introduced in LTTng 2.5. ==== ---- [role="since-2.5"] [[tracef]] ==== Use `tracef()` ---- ==== [[terminology]] == Terminology What follows is an official, partial list of technical terms used by the LTTng Documentation. Other forms of those terms are _not_ permitted. For example, do not write `use-case` or `filesystem`. Autotools:: The GNU Autotools. + Do not use _autotools_. Babeltrace:: The Babeltrace project, which includes the `babeltrace` command, some libraries, and Python bindings. + Use +`babeltrace`+ to refer to the actual `babeltrace` command. Babeltrace Python bindings:: The Python bindings of Babeltrace. + The plural _bindings_ is important. Bash:: The Bash shell. + Do not use _bash_. buffering scheme:: A layout of tracing buffers applied to a given channel. channel:: An LTTng channel. CLI:: Prefer expanding this acronym to _command-line interface_ in the text. clock:: A reference of time for a tracer. + Use _system time_ to refer to the date and time as seen by a user. command-line:: Adjective version of _command line_: _command-line option_, _command-line interface_. command-line interface:: An interface in which the user enters command lines to instruct the system what to do. + Prefer using _command_ or _command-line tool_ to refer to a specific command. command line:: An actual line of command entered by the user in a terminal, at a command prompt. + Write _command-line_ when used as an adjective. consumer daemon:: The LTTng consumer daemon. + Do not use _consumerd_. + Use +`lttng-consumerd`+ to refer to the consumer daemon executable. domain:: Do not use when referring to a _tracing domain_. event:: Occurrence recognised by software, emitted by a tracer when specific conditions are met, at a given time. An event _occurs_ at a specific time, after which a tracer can record its payload. event loss mode:: The mechanism by which event records of a given channel are lost (not recorded) when there is no sub-buffer space left to store them. event name:: The name of an event, which is also the name of the event record. This is different from a _tracepoint name_, which is only the name of the instrumentation point, not necessarily equal to the event name. event record:: Record, in a trace, of the payload of an event which occured. event rule:: Set of conditions which must be satisfied for one or more events to occur. The `lttng enable-event` command creates and enables _event rules_, not _events_. file system:: Contains directories, files, and links in an organized structure. + Do not use _filesystem_ or _file-system_. +`java.util.logging`+:: Even though the `--jul` command-line option is an acronym for this term, there is no such thing as _Java Util Logging_. The only correct form is the name of the Java package, +`java.util.logging`+. instrumentation:: The use of LTTng probes to make a software traceable. libc:: Do not use. + Use _the C standard library_ to refer to the standard library for the C programming language, or _glibc_ to refer to the GNU C Library specifically. log4j:: LTTng-UST supports Java logging using Apache _log4j_, not Apache Log4j 2. log level:: Level of severity of a log statement. + Do not hyphenate. kernel:: In general, do not use _kernel_ to refer to the _Linux kernel_: use the whole _Linux kernel_ term, because other operating system kernels exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng kernel modules_. Linux Trace Toolkit: next generation:: The expansion of the _LTTng_ acronym. + The colon and the lowercase _n_ and _g_ are important. LTTng-analyses:: The LTTng-analyses project. LTTng-modules:: The LTTng-modules project. LTTng-tools:: The LTTng-tools project. LTTng-UST:: The LTTng-UST project. LTTng-UST Java agent:: LTTng-UST Python agent:: An LTTng user space agent. + Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_. LTTng Documentation:: The name of this project. + Do not use _LTTng documentation_. + When referring to the project, the _the_ determiner can be lowercase: _Welcome to the LTTng Documentation!_. LTTng live:: The name of a communication protocol between Babeltrace and the relay daemon which makes it possible to see events "live", as they are received by the relay daemon. + Do not hyphenate. the +`lttng`+ tool:: the +`lttng`+ command line tool:: The `lttng` command line tool. + When _tool_ has been mentioned in the previous sentences, you can use +`lttng`+ alone. Makefile:: An input for the make tool. + Do not use _makefile_ or _make file_. man page:: Unix-style reference manual page. + Do not hyphenate. per-process buffering:: A buffering scheme in which each process has its own buffer for a given user space channel. + Do not use _per-PID buffering_. per-user buffering:: A buffering scheme in which all the processes of a user share the same buffer for a given user space channel. + Do not use _per-UID buffering_. probe:: An instrumentation point. + Prefer _tracepoint_ when referring to a user space or Linux kernel LTTng tracepoint. real-time clock:: A clock which keeps track of the current time, including eventual time corrections. + Do not use _realtime clock_ or _real time clock_. relay daemon:: The LTTng relay daemon. + Do not use _relayd_. + Use +`lttng-relayd`+ to refer to the relay daemon executable. root user:: A superuser of a Linux system. + Do not use +`root`+. session:: Do not use when referring to a _tracing session_. session daemon:: The LTTng session daemon. + Do not use _sessiond_. + Use +`lttng-sessiond`+ to refer to the session daemon executable. snapshot:: Copy of the current data of all the buffers of a given tracing session, saved as a trace. sub-buffer:: One part of an LTTng ring buffer. + Do not use _subbuffer_ since it's harder to read with the two contiguous b's. timestamp:: Time information attached to an event when it is emitted. This is not necessarily a _Unix timestamp_. + Do not use _time stamp_. trace:: As a verb: a user or a tracer can _trace_ an application. Trace Compass:: The Trace Compass project and application. + Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or _Tracecompass_. tracepoint:: An instrumentation point using the tracepoint mechanism of the Linux kernel or of LTTng-UST. + Do not use _trace point_ or _trace-point_. tracepoint definition:: The definition of a single tracepoint. tracepoint name:: The name of a _tracepoint_. + Not to be confused with an _event name_. tracepoint provider:: A set of functions providing tracepoints to an instrumented user application. + Not to be confused with a _tracepoint provider package_: many tracepoint providers can exist within a tracepoint provider package. tracepoint provider package:: One or more tracepoint providers compiled as an object file or as a shared library. tracing domain:: An LTTng tracing domain. + Always use the complete _tracing domain_ term, not _domain_ alone, unless _tracing domain_ has been used in the few preceding sentences. tracing group:: The Unix group in which a user can be to be allowed to trace the Linux kernel. + Do not use _`tracing` group_, as the name of the tracing group is configurable. tracing session:: An LTTng tracing session. + Always use the complete _tracing session_ term, not _session_ alone. Unix:: Unix operating system or philosophy. + Do not use _UNIX_. Unix epoch:: Absolute reference of a real-time clock. + Use the term as a proper noun: do not precede it with _the_. + Do not use _Epoch_ alone. Unix timestamp:: Timestamp represented as the number of seconds since Unix epoch. use case:: According to Wikipedia: List of actions or event steps, typically defining the interactions between a role and a system, to achieve a goal. + Do not hyphenate. user application:: An application running in user space, as opposed to a Linux kernel module, for example. + Do not use _user space application_, as this is redundant. user space:: User processes. + Do not hyphenate.