lttng-add-map-channel - Man Page

Add a map channel to an LTTng recording session

Synopsis

Add a Linux kernel map channel:

lttng [GENERAL OPTIONS] add-map-channel --type=kernel
      [--value-type=(signed-int-32 | signed-int-64 | signed-int-max)]
      [--max-key-count=COUNT]
      [--update-policy=(per-event | per-rule-match)]
      [--session=SESSION] [CHANNEL]

Add a user space map channel with a per-user buffer ownership model:

lttng [GENERAL OPTIONS] add-map-channel --type=user
      [--value-type=(signed-int-32 | signed-int-64 | signed-int-max)]
      [--max-key-count=COUNT]
      [--update-policy=(per-event | per-rule-match)]
      [--session=SESSION] [CHANNEL]

Add a user space map channel with a per-process buffer ownership model:

lttng [GENERAL OPTIONS] add-map-channel --type=user
      [--value-type=(signed-int-32 | signed-int-64 | signed-int-max)]
      [--max-key-count=COUNT] --buffer-ownership=process
      [--update-policy=(per-event | per-rule-match)]
      [--dead-process-policy=(drop | sum-into-shared)]
      [--session=SESSION] [CHANNEL]

Description

The lttng add-map-channel command adds a map channel to a recording session.

A map channel configures a set of per-CPU counters: named integer values, keyed by strings, which accumulate over time. The counters of a map channel are grouped into per-CPU stores known as maps. A map channel is similar to an event record channel (see lttng-enable-channel(1)), except that instead of containing ring buffers to record events, it contains maps of counters.

Map channels and event record channels are independent and may coexist within the same recording session: you don’t need a separate recording session to add a map channel alongside event record channels.

All the maps within a map channel share the same value type and maximum key count.

To populate the counters of a map, use the lttng-add-trigger(1) command to create a trigger with an “increment map value” action which targets the map channel.

The name of the map channel to add is:

With the CHANNEL non-option argument

CHANNEL.

Without the CHANNEL non-option argument

Automatically generated by the session daemon.

The map channel to add belongs to:

With the --session=SESSION option

The recording session named SESSION.

Without the --session option

The current recording session (see lttng-concepts(7) to learn more about the current recording session).

See lttng-concepts(7) to learn more about recording sessions and maps channels.

See the “Examples” section below for usage examples.

List the map channels of a given recording session with the lttng-list(1) command. Show the values of the map channels of a given recording session with the lttng-show-maps(1) command, or export them as a SQL script with the lttng-export-maps(1) command.

Options

See lttng(1) for GENERAL OPTIONS.

Map channel type

-t TYPE, --type=TYPE

Set the type of the map channel to TYPE.

TYPE is one of:

kernel: Linux kernel map channel.
user: User space map channel.

Recording target

-s SESSION, --session=SESSION: Add the map channel to the recording session named SESSION instead of the current recording session.

Map channel properties

--buffer-ownership=MODEL

Set the buffer ownership model of the map channel to MODEL.

Only available with the --type=user option: with the --type=kernel option, LTTng always allocates a single set of maps (one per CPU) for the whole system.

MODEL is one of:

process: Allocate one set of maps (one per CPU) for each instrumented process.
user (default): Allocate one set of maps (one per CPU) shared by all the instrumented processes of each Unix user.

As of LTTng 2.16.0, the default is user, but this may change in the future.

--dead-process-policy=POLICY

With the --buffer-ownership=process option, set what LTTng does with the counter values of an instrumented process when this process terminates while the map channel still exists.

POLICY is one of:

drop

Discard the maps of the terminated process: their counter values, which the process accumulated since the start of the recording session, are lost.

sum-into-shared (default)

For each map of the terminated process, add each value to the corresponding shared counter of the map channel (see lttng-concepts(7) to learn more about shared counters).

When the addition would overflow the effective value type (see the --value-type option), the result wraps around (modular arithmetic) and LTTng sets the overflow flag of the shared counter.

--max-key-count=COUNT

Set the maximum number of keys per map to COUNT.

This value directly controls the size of the underlying map buffer.

When a map is full, LTTng silently drops any new key.

Default: 4096.

--value-type=TYPE

Set the value type of the maps within the map channel to TYPE.

This sets the configured value type. The effective value type, that is, the value type which LTTng actually creates for a given instrumented application or for the Linux kernel, may differ from the configured one, following two simple rules:

A counter can’t be wider than whatever hosts it.
The host is the session daemon (see lttng-sessiond(8)) for a user space map channel and the Linux kernel for a Linux kernel map channel.
Therefore, asking for a 64-bit counter on a 32-bit host makes the channel creation fail.
The bitness of an instrumented application doesn’t affect whether LTTng creates a user space map channel, since LTTng doesn’t know it at that time; it only affects access afterwards.
A 64-bit application can access a counter of any width, whereas a 32-bit application can only access a 32-bit counter.
This access limit doesn’t apply to Linux kernel map channels, of which the session daemon reads the counters directly: a 32-bit session daemon reads a 64-bit kernel counter fine.

TYPE is one of:

signed-int-32

Use 32-bit signed integer values.

LTTng can always create such a map channel, and any instrumented application can access its counters.

signed-int-64

Use 64-bit signed integer values.

For a user space map channel, this requires a 64-bit session daemon: with a 32-bit session daemon, the channel creation fails. Instrumented 32-bit applications can’t access the counters.

For a Linux kernel map channel, this requires a 64-bit kernel: with a 32-bit kernel, the channel creation fails.

signed-int-max (default)

Use the widest signed integer values which keep the counters accessible without making the channel creation fail.

For a user space map channel, each instrumented application gets a counter of its own bitness, but never wider than the session daemon. Both 32-bit and 64-bit applications can therefore always access such a map channel, and LTTng can always create it.

For a Linux kernel map channel, this is the bitness of the session daemon, which reads the counters.

--update-policy=POLICY

Set the update policy of the map channel to POLICY, that is, how LTTng increments map values when triggers (see lttng-add-trigger(1)) with an “increment map value” action which targets this map channel fire.

Depending on POLICY, when LTTng emits an event E and multiple “event rule matches” triggers with an “increment map value” action which targets this map channel match E:

per-event (default)

LTTng increments a single map value per resulting key, regardless of how many of those triggers match E.

This is similar to how LTTng writes a single event record to a given event record channel when multiple recording event rules of the channel match the same event (see lttng-concepts(7)).

per-rule-match

LTTng performs one map value increment per matching trigger, even when several matching triggers produce the same key.

This policy only affects triggers with an “event rule matches” condition (see lttng-add-trigger(1)). For triggers with another condition type, each firing results in a single increment, regardless of POLICY.

Program information

-h, --help

Show help.

This option attempts to launch /usr/bin/man to view this manual page. Override the manual pager path with the LTTNG_MAN_BIN_PATH environment variable.

--list-options

List available command options and quit.

Exit Status

0: Success
1: Command error
2: Undefined command
3: Fatal error
4: Command warning (something went wrong during the command)

Environment

LTTNG_ABORT_ON_ERROR

Set to 1 to abort the process after the first error is encountered.

LTTNG_HOME

Path to the LTTng home directory.

Defaults to $HOME.

Useful when the Unix user running the commands has a non-writable home directory.

LTTNG_LIST_LEGACY

Set to 1 to use the legacy output format (LTTng 2.14 and earlier) for the lttng-list(1) command instead of the modern output format.

Note that the legacy output doesn’t show anything related to features introduced after LTTng 2.14.

LTTNG_MAN_BIN_PATH

Absolute path to the manual pager to use to read the LTTng command-line help (with lttng-help(1) or with the --help option) instead of /usr/bin/man.

LTTNG_NO_UTF_8

Set to 1 to NOT emit multi-byte UTF-8 sequences, even if the locale claims to support it.

LTTNG_SESSION_CONFIG_XSD_PATH

Path to the directory containing the session.xsd recording session configuration XML schema.

LTTNG_SESSIOND_PATH

Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from the lttng-create(1) command.

The --sessiond-path general option overrides this environment variable.

LTTNG_TERM_COLOR

Controls when to emit terminal SGR codes in the output.

The NO_COLOR environment variable overrides this.

One of:

auto (default): Only emit SGR codes when the standard output is connected to a color-capable terminal.
always: Always emit SGR codes.
never: Never emit SGR codes.

NO_COLOR

If set and not empty, then it’s equivalent to setting LTTNG_TERM_COLOR to never.

See NO_COLOR <https://no-color.org/> to learn more.

Files

$LTTNG_HOME/.lttngrc

Unix user’s LTTng runtime configuration.

This is where LTTng stores the name of the Unix user’s current recording session between executions of lttng(1). lttng-create(1) and lttng-set-session(1) set the current recording session.

$LTTNG_HOME/lttng-traces

Default output directory of LTTng traces in local and snapshot modes.

Override this path with the --output option of the lttng-create(1) command.

$LTTNG_HOME/.lttng

Unix user’s LTTng runtime and configuration directory.

$LTTNG_HOME/.lttng/sessions

Default directory containing the Unix user’s saved recording session configurations (see lttng-save(1) and lttng-load(1)).

/usr/local/etc/lttng/sessions

Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).

Note

$LTTNG_HOME defaults to the value of the HOME environment variable.

Examples

Example 1. Add a Linux kernel map channel named my-counters with default attributes to the current recording session.

$ lttng add-map-channel --type=kernel my-counters

Example 2. Add a user space map channel with a per-process buffer ownership model and a maximum of 8192 keys.

See the --buffer-ownership and --max-key-count options.

$ lttng add-map-channel --type=user \
                        --buffer-ownership=process \
                        --max-key-count=8192 my-counters

Example 3. Add a user space map channel with 32-bit signed integer values.

See the --value-type option.

The resulting map channel is accessible from both 32-bit and 64-bit instrumented applications.

$ lttng add-map-channel --type=user \
                        --value-type=signed-int-32 my-counters

Example 4. Add a user space map channel with an automatically generated name to a specific recording session.

See the --session option.

$ lttng add-map-channel --session=my-session --type=user

Example 5. Add a map channel and create a trigger to count events per name.

First, add the map channel:

$ lttng add-map-channel --session=my-session --type=user my-counters

Then, create a trigger to increment a map value for each event, using the event name as the map key:

$ lttng add-trigger --condition=event-rule-matches \
                    --type=user --name='*' \
                    --action=incr-map-value \
                    --session=my-session \
                    --type=user \
                    --channel=my-counters \
                    --key='{event_name}_count'

Resources

LTTng project website <https://lttng.org>
LTTng documentation <https://lttng.org/docs>
LTTng bug tracker <https://bugs.lttng.org>
Git repositories <https://git.lttng.org>
GitHub organization <https://github.com/lttng>
Continuous integration <https://ci.lttng.org/>
Mailing list <https://lists.lttng.org/> for support and development: lttng-dev@lists.lttng.org
IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
Mastodon <https://mastodon.social/@lttng>