Skip to content

Latest commit

 

History

History
707 lines (564 loc) · 18.2 KB

CONTRIBUTING.adoc

File metadata and controls

707 lines (564 loc) · 18.2 KB
Raw

The LTTng Documentation: Contributor’s guide

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

The LTTng Documentation exists to make the 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 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 Terminology 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 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 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:

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 Principles, 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.

    Example 1. Using the man macro.
    See man:lttng-ust(3) for more details about ...

  • 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.

    Example 2. 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.

    Example 3. 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.

    Example 4. 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.

    Example 5. 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.

    Example 6. 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.

Example 7. 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.
Example 8. 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.

Example 9. Using a non-breaking space between a quantity and its unit.
The size of this file is 1039{nbsp}bytes.
Example 10. 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.

Example 11. 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:

  • 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 "$ " to indicate that a regular Unix user should run it. Start a command line with "# " to indicate that a priviledged Unix user should run it.

    Example 12. Using a terminal box.
    [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.

    Example 13. Using a source code box.
    [source,c]
----
#include <stdio.h>

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 Pygments.

    Always indent source code examples with 4 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 opt macro. Otherwise use simple backticks.

  • Always follow the option name by the option word.

Example 14. Using a command-line option.
You can use the `lttng` tool's opt:lttng(1):--group option to specify a
custom tracing group.

In terminal boxes, always put = between the option name and its argument, if any.

Example 15. 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.

[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.

Example 16. 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.

Example 17. Section heading describing a feature introduced in LTTng 2.5.
[role="since-2.5"]
[[tracef]]
==== Use `tracef()`

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.