$
lttng add-map-channel --type=kernel my-counters
lttng-add-map-channel — Add a map channel to an LTTng recording session
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]
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:
CHANNEL non-option argument
CHANNEL.
CHANNEL non-option argument
Automatically generated by the session daemon.
The map channel to add belongs to:
--session=SESSION option
The recording session named SESSION.
--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.
See lttng(1) for GENERAL OPTIONS.
--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, 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.
--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.
-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.
Success
Command error
Undefined command
Fatal error
Command warning (something went wrong during the command)
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 to learn more.
$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)).
/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.
Example: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: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-countersExample: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-countersExample: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: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'
Mailing list for support and
development: lttng-dev@lists.lttng.org
IRC channel: #lttng on irc.oftc.net
This program is part of the LTTng-tools project.
LTTng-tools is distributed under the
GNU General
Public License version 2. See the
LICENSE file
for details.
Special thanks to Michel Dagenais and the DORSAL laboratory at École Polytechnique de Montréal for the LTTng journey.
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases.