lttng-show-maps - Man Page

Show counter values of an LTTng recording session

Synopsis

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]

Description

The lttng show-maps command shows the current counter values of one or more map channels (see lttng-add-map-channel(1)) of:

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, 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​.0)​.

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

Aggregation

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​.0, a partition is always a CPU, but a future LTTng release may introduce other kinds of partitions​.

As of LTTng ​2​.16​.0, 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​.

Selection

Each selection option contributes to a whitelist which controls one axis of the output:

AxisSelection options
Map channel name--channel
Map channel type--type
Owner--uid, --all-uids, --pid, --all-pids, --system, --shared
CPU ID--part-id (or --cpu-id)
Key--key, --key-glob
Value--non-init-values

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 optionsSelected owners
NoneAll the owners, including the shared counters
--uid=aliceJust the counters of Unix user alice
--uid=alice --sharedJust the counters of Unix user alice and the shared counters
--sharedJust the shared counters
--all-uidsJust the counters of all the Unix users
--systemJust the Linux kernel counters
--system --sharedJust the Linux kernel and shared counters
--system --all-uidsJust the Linux kernel counters and the counters of all the Unix users

The command combines the whitelists as such:

Within a single axis

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

Across axes

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:

  • --part-id and --cpu-id have no effect on shared counter selection​.

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

For example, considering --uid=1000 and --uid=1002:

With --per=channel

The command prints one table per map channel, summing into it the counter values of both Unix users ​1000 and ​1002​.

With --per=owner

The command prints one table for Unix user ​1000 and another for Unix user ​1002, for each map channel​.

Sorting and display

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

Options

See lttng(1) for GENERAL OPTIONS​.

Recording target

-s SESSION, --session=SESSION

Show the counter values of the recording session named SESSION instead of the current recording session​.

Aggregation

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​.0, a partition is always a CPU, but a future LTTng release may introduce other kinds of partitions​.

As of LTTng ​2​.16​.0, 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​.

Selection

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​.0, 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​.0, --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​.

Sorting

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

Display

--limit=COUNT

Print the first COUNT sorted rows of each table​.

By default, the command prints all the rows of each table​.

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. ​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 ​2. ​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=10

Example ​3. ​Show the per-CPU breakdown of a specific counter of a specific map channel​.

See the --per, --channel, and --key options​.

$ lttng show-maps --channel=my-counters --per=cpu \
                  --key=myapp:my_event

Example ​4. ​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=desc

Example ​5. ​Show the per-user totals for two specific Unix users​.

See the --per and --uid options​.

$ lttng show-maps --per=owner --uid=1000 --uid=1002

Example ​6. ​Show the five least incremented counters of a specific map channel​.

See the --sort-by and --limit options​.

$ lttng show-maps --channel=my-counters --sort-by=value --limit=5

Example ​7. ​Show only the shared counters of a specific map channel​.

See the --shared and --channel options​.

$ lttng show-maps --channel=my-counters --shared

Example ​8. ​Show only the system counters of a specific kernel map channel​.

See the --system and --channel options​.

$ lttng show-maps --channel=my-counters --system

Example ​9. ​Show only the shared counters of the user space map channels​.

See the --type option​.

$ lttng show-maps --type=user --shared

Example ​10. ​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 ​11. ​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​.

See the --per, --system, and --shared options​.

$ lttng show-maps --per=owner --system --shared

Example ​12. ​Show a specific Unix user’s counters and the shared counters of a map channel, side by side​.

See the --per, --uid, and --shared options​.

$ lttng show-maps --channel=my-counters --per=owner --uid=meow \
                  --shared

Example ​13. ​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

Example ​14. ​Show the per-CPU counters of a specific process ID from CPU ​4 to CPU ​12​.

See the --pid, --per, and --cpu-id options​.

$ lttng show-maps --pid=$(pidof my-app) --per=cpu --cpu-id={4​.​.12}

Resources

Thanks

Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> 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​.

See Also

lttng(1), lttng-add-map-channel(1), lttng-add-trigger(1), lttng-export-maps(1), lttng-list(1), lttng-concepts(7)

Referenced By

lttng(1), lttng-add-map-channel(1), lttng-clear(1), lttng-concepts(7), lttng-export-maps(1), lttng-list(1), lttng-status(1).

21 April 2026 LTTng 2.16.0 LTTng Manual