See the --channel option.
$
lttng show-maps --channel=my-counters
lttng-show-maps — Show counter values of an LTTng recording session
lttng [GENERAL OPTIONS] show-maps [--session=SESSION] [--channel=CHANNEL]… [--type=(user | kernel)]… [--per=(channel | owner | cpu)] [--uid=USER… |--all-uids] [--pid=PID… |--all-pids] [--shared] [--system] [--part-id=ID]… [--cpu-id=ID]… [--key=KEY]… [--key-glob=GLOB]… [--non-init-values] [--sort-by=(key | value)] [--sort-order=(asc | desc)] [--limit=COUNT]
The lttng show-maps command shows the current counter values of
one or more map channels (see lttng-add-map-channel(1)) of:
--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, map channels, and counters.
To query and aggregate the same counters flexibly, see lttng-export-maps(1) which exports them as an SQL script instead of a fixed presentation.
For each selected map channel, the command prints one or more tables which associate string keys with integral counter values (the only existing key and value types as of LTTng 2.16).
The last column of a counter table, named “Overflow?”, contains a “✔”
symbol as an overflow indicator for the corresponding row; this means at
least one update of the counter wrapped around (modular arithmetic)
because the result couldn’t be represented with the effective value type
of the map group (see the --value-type option of
lttng-add-map-channel(1)).
Under the --per=channel and --per=owner
aggregation levels, the overflow indicator symbol is the logical OR of
the overflow indicators of the raw, per-CPU or shared counter rows which
contribute to the aggregated value.
This command shows colored text when the terminal supports it.
Override the terminal coloring behaviour with the
LTTNG_TERM_COLOR and NO_COLOR environment variables.
Important:The lttng show-maps command does not provide an atomic snapshot of
the counter values: the connected session daemon (see
lttng-sessiond(8)) reads the values one by one, and LTTng tracers
may concurrently update any of them while the command runs.
Therefore, lttng show-maps does not guarantee that its output
reflects the state of the counters at a single instant.
To obtain a consistent view of the counter values, LTTng recommends to either:
Stop the recording session with the lttng-stop(1) command before
running lttng show-maps.
Disable the recording event rules (see lttng-disable-event(1)) and/or remove the triggers (see lttng-remove-trigger(1)) having an “increment map value” action which targets the map channel to inspect.
See the “EXAMPLES” section below for usage examples.
The --per option sets the aggregation level of the tables;
the command only aggregates the counters which the
selection options select (see the
“Selection” section below):
channel
Print one table per map channel, with the value for each key being the sum of the values of this key across:
All the selected owners: the whole system, Unix users, or process IDs, depending on the type and buffer ownership model of the map channel.
The shared counters when selected.
The selected CPUs of the map channel.
owner
Print one table per selected owner (the whole system, a Unix user, or a process ID) per map channel, with the value for each key being the sum of the values of this key across all the selected CPUs of the owner.
For the purpose of this command, the owner of the map channel-wide shared counters (see lttng-concepts(7)) is the LTTng session daemon itself (see lttng-sessiond(8)), since the session daemon increments those counters directly. Therefore, the shared counters, when selected, appear as their own additional table for each map channel.
cpu
part
Print one table per CPU per owner per map channel, with the value for each key being the raw, non-aggregated counter.
When selected, the shared counters appear as a single additional table per map channel, with no per-CPU breakdown.
part stands for “partition”: as of LTTng 2.16, a
partition is always a CPU, but a future LTTng release may introduce
other kinds of partitions.
As of LTTng 2.16, cpu is an alias of part, but
this may change if other kinds of partitions become available;
therefore part is the more future-proof form.
Each selection option contributes to a whitelist which controls one axis of the output:
| Axis | Selection options |
|---|---|
Map channel name | |
Map channel type | |
Owner | |
CPU ID | |
Key | |
Value |
The owner axis selects the counters of which owners the command
includes. An owner is the whole system (for a Linux kernel map channel),
a Unix user (user space map channel with the per-user buffer ownership
model), or a process ID (user space map channel with the per-process
buffer ownership model); see the --buffer-ownership option of
lttng-add-map-channel(1).
For the purpose of this command, the owner of the map channel-wide
shared counters (see lttng-concepts(7)) is the LTTng session
daemon itself (see lttng-sessiond(8)), since the session daemon
increments those counters directly. The --shared option
therefore selects an owner like the other options of this axis.
Considering the above, the options of the owner axis are:
--uid=USER (repeatable)
Select the counters of the Unix user USER (user ID or user name).
Only applies to user space map channels with the per-user buffer ownership model.
--all-uids
Select the counters of all the Unix users.
The purpose of this option is to exclude system (Linux kernel) and shared counters.
Only applies to user space map channels with the per-user buffer ownership model.
--pid=PID (repeatable)
Select the counters of the process ID PID.
Only applies to user space map channels with the per-process buffer ownership model.
--all-pids
Select the counters of all the process IDs.
The purpose of this option is to exclude system (Linux kernel) and shared counters.
Only applies to user space map channels with the per-process buffer ownership model.
--system
Select the counters of the system.
Only applies to Linux kernel map channels.
--shared
Select the shared counters.
Only applies to user space map channels.
The Unix user, process ID, and system owners have one map of counters
per CPU, therefore the CPU ID selection (see the --part-id
option) subdivides them. On the other hand, the shared counters have no
CPU, therefore the CPU ID selection doesn’t subdivide them.
By default, the whitelist of an axis contains all the entities of that axis, so that, without any selection option, the command selects every counter. As soon as you use a selection option for a given axis, the command starts an explicit whitelist for that axis and selects only the listed entities.
For the owner axis, this means that as soon as you use any of the options above, the command selects only the owners you explicitly list, for example:
| Owner axis options | Selected owners |
|---|---|
None | All the owners, including the shared counters |
| Just the counters of Unix user |
Just the counters of Unix user | |
Just the shared counters | |
Just the counters of all the Unix users | |
Just the Linux kernel counters | |
Just the Linux kernel and shared counters | |
Just the Linux kernel counters and the counters of all the Unix users |
The command combines the whitelists as such:
The command takes the logical OR of all the selections.
For example, --uid=1000 and --uid=1002 together
select the counters of the Unix users having the ID 1000 OR the
ID 1002. Likewise, --shared and --uid=1000
together select the shared counters OR the counters of the Unix user
having the ID 1000.
The command takes the logical AND.
For example, --channel=my-counters and --uid=1000
together select the counters of the Unix user having the ID 1000
within the map channel named my-counters.
That being said:
The --per aggregation level (see the
“Aggregation” section above) determines what the
command does with the selected counters:
Counters at the chosen aggregation level appear as their own tables.
Counters below the chosen aggregation level are summed into the values of the enclosing table.
Control the ordering of rows within each table with the
--sort-by and --sort-order options.
Limit the number of rows of each table to the first COUNT sorted
entries with the --limit=COUNT option.
See lttng(1) for GENERAL OPTIONS.
See the “Aggregation” section above.
--per=LEVEL
Set the aggregation level of the printed tables to LEVEL.
LEVEL is one of:
channel (default)
Print one table per map channel, with the value for each key being the sum of the values of this key across:
All the selected owners: the whole system, Unix users, or process IDs, depending on the type and buffer ownership model of the map channel.
The shared counters when selected.
The selected CPUs of the map channel.
owner
Print one table per selected owner per map channel, with the value for each key being the sum of the values of this key across all the selected CPUs of the owner.
For the purpose of this command, the owner of the map channel-wide shared counters (see lttng-concepts(7)) is the LTTng session daemon itself (see lttng-sessiond(8)), since the session daemon increments those counters directly. Therefore, the shared counters, when selected, appear as their own additional table for each map channel.
cpu
part
Print one table per CPU per owner per map channel, with the value for each key being the raw, non-aggregated counter.
When selected, the shared counters appear as a single additional table per map channel, with no per-CPU breakdown.
part stands for “partition”: as of LTTng 2.16, a
partition is always a CPU, but a future LTTng release may introduce
other kinds of partitions.
As of LTTng 2.16, cpu is an alias of part, but
this may change if other kinds of partitions become available;
therefore part is the more future-proof form.
See the “Selection” section above to learn how the command combines repeated and mixed selection options.
--all-pids
Select the counters of all the process IDs.
Only applies to user space map channels having the per-process buffer
ownership model (see the --buffer-ownership option of
lttng-add-map-channel(1)).
You cannot combine this option with --pid.
--all-uids
Select the counters of all the Unix users.
Only applies to user space map channels having the per-user buffer
ownership model (see the --buffer-ownership option of
lttng-add-map-channel(1)).
You cannot combine this option with --uid.
-c CHANNEL, --channel=CHANNEL
Select the counters of the map channel named CHANNEL.
You can repeat this option.
--cpu-id=ID
As of LTTng 2.16, this option is an alias of
--part-id, but this may change if other kinds of partitions
become available; therefore --part-id is the more
future-proof form.
No effect on the selection of shared counters.
You can repeat this option.
--key=KEY
Select the counters having the exact key KEY.
You can repeat this option.
--key-glob=GLOB
Select the counters of which the key matches the globbing
pattern GLOB.
In GLOB, the * character means “match anything”. To match a
literal * character, use \*.
You can repeat this option.
--non-init-values
Select the counters of which the value is not zero.
--part-id=ID
Select the counters of the CPU ID ID.
ID is a 0-based CPU index.
As of LTTng 2.16, --cpu-id is an alias of
this option, but this may change if other kinds of partitions
become available; therefore this option is the more future-proof
form.
No effect on the selection of shared counters.
You can repeat this option.
--pid=PID
Select the counters of the process ID PID.
Only applies to user space map channels having the per-process buffer
ownership model (see the --buffer-ownership option of
lttng-add-map-channel(1)).
You cannot combine this option with --all-pids.
You can repeat this option.
--shared
Select the shared counters (see lttng-concepts(7) to learn more).
Only applies to user space map channels.
--system
Select the counters of the system (Linux kernel).
Only applies to Linux kernel map channels.
--type=TYPE
Select the counters of the map channels of which the type is TYPE.
TYPE is one of:
kernel
Linux kernel map channels (see the --type=kernel option
of lttng-add-map-channel(1)).
user
User space map channels (see the --type=user option of
lttng-add-map-channel(1)).
You can repeat this option, for example to select both Linux kernel
and user space map channels with --type=kernel
--type=user (equivalent to not using this option at all).
--uid=USER
Select the counters of the Unix user USER.
USER is either a user ID or a user name.
The lttng command itself performs the user name resolution.
Only applies to user space map channels having the per-user buffer
ownership model (see the --buffer-ownership option of
lttng-add-map-channel(1)).
You cannot combine this option with --all-uids.
You can repeat this option.
--sort-by=COLUMN
Set the column by which the rows of each printed table are sorted
to COLUMN.
COLUMN is one of:
key (default)
Sort the rows by key, as strings.
value
Sort the rows by counter value, as integers.
--sort-order=ORDER
Set the order in which the rows of each printed table are sorted
to ORDER, depending on --sort-by.
ORDER is one of:
asc (default)
Sort the rows in ascending order.
desc
Sort the rows in descending order.
--limit=COUNT
Print the first COUNT sorted rows of each table.
By default, the command prints all the rows of each table.
-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:Show the counters of the map channel named my-counters of the current recording session.
See the --channel option.
$
lttng show-maps --channel=my-counters
Example:Show the top 10 “hottest” counters of a specific map channel.
See the --sort-by, --sort-order, and --limit
options.
$
lttng show-maps --channel=my-counters --sort-by=value \
--sort-order=desc --limit=10Example:Show the per-CPU breakdown of a specific counter of a specific map channel.
Example:Show all the counters whose keys start with sched_, sorted by descending value.
See the --key-glob, --sort-by, and --sort-order
options.
$
lttng show-maps --key-glob='sched_*' --sort-by=value \
--sort-order=descExample:Show the per-user totals for two specific Unix users.
Example:Show the five least incremented counters of a specific map channel.
Example:Show only the shared counters of a specific map channel.
Example:Show only the system counters of a specific kernel map channel.
Example:Show only the shared counters of the user space map channels.
See the --type option.
$
lttng show-maps --type=user --shared
Example:Show the per-user totals for every Unix user of a map channel.
See the --per and --all-uids options.
$
lttng show-maps --per=owner --all-uids
Example:Show the system counters of the Linux kernel map channels and the shared counters of the user space map channels of the current recording session, side by side.
Example:Show a specific Unix user’s counters and the shared counters of a map channel, side by side.
Example:Show only the counters of a specific map channel of which the value isn’t zero.
See the --non-init-values and --channel options.
$
lttng show-maps --channel=my-counters --non-init-values
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.