// SPDX-FileCopyrightText: 2026 Philippe Proulx <pproulx@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

lttng-add-map-channel(1)
========================
:revdate: 21 April 2026


NAME
----
lttng-add-map-channel - Add a map channel to an LTTng recording session


SYNOPSIS
--------
Add a Linux kernel map channel:

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

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

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

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

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-map-channel* option:--type=**user**
      [option:--value-type=(**signed-int-32** | **signed-int-64** | **signed-int-max**)]
      [option:--max-key-count='COUNT'] option:--buffer-ownership=**process**
      [option:--update-policy=(**per-event** | **per-rule-match**)]
      [option:--dead-process-policy=(**drop** | **sum-into-shared**)]
      [option:--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
man: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 man: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 option:--session='SESSION' option::
    The recording session named 'SESSION'.

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

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

See the ``<<examples,EXAMPLES>>'' section below for usage examples.

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


include::common-lttng-cmd-options-head.txt[]


Map channel type
~~~~~~~~~~~~~~~~
option:-t 'TYPE', option:--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
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Add the map channel to the recording session named 'SESSION'
    instead of the current recording session.


Map channel properties
~~~~~~~~~~~~~~~~~~~~~~
option:--buffer-ownership='MODEL'::
    Set the buffer ownership model of the map channel to 'MODEL'.
+
Only available with the option:--type=++user++ option: with the
option:--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{nbsp}{lttng_version}, the default is `user`, but this
may change in the future.

option:--dead-process-policy='POLICY'::
    With the option:--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
    man:lttng-concepts(7) to learn more about shared counters).
+
When the addition would overflow the effective value type
(see the option:--value-type option), the result wraps around
(modular arithmetic) and LTTng sets the overflow flag of the shared
counter.
--

option:--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: +{default_map_channel_max_key_count}+.

option:--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 man: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.
--

option:--update-policy='POLICY'::
    Set the update policy of the map channel to 'POLICY', that is,
    how LTTng increments map values when triggers (see
    man:lttng-add-trigger(1)) with an ``increment map value'' action
    which targets this map channel fire.
+
Depending on 'POLICY', when LTTng emits an event{nbsp}__E__ and multiple
``event rule matches'' triggers with an ``increment map value'' action
which targets this map channel match{nbsp}__E__:
+
--
`per-event` (default)::
    LTTng increments a single map value per resulting key, regardless
    of how many of those triggers match{nbsp}__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 man: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 man:lttng-add-trigger(1)). For triggers with another
condition type, each firing results in a single increment, regardless
of 'POLICY'.


include::common-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.Add a Linux kernel map channel named `my-counters` with default attributes to the current recording session.
====
[role="term"]
----
$ lttng add-map-channel --type=kernel my-counters
----
====

.Add a user space map channel with a per-process buffer ownership model and a maximum of 8192{nbsp}keys.
====
See the option:--buffer-ownership and option:--max-key-count options.

[role="term"]
----
$ lttng add-map-channel --type=user \
                        --buffer-ownership=process \
                        --max-key-count=8192 my-counters
----
====

.Add a user space map channel with 32-bit signed integer values.
====
See the option:--value-type option.

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

[role="term"]
----
$ lttng add-map-channel --type=user \
                        --value-type=signed-int-32 my-counters
----
====

.Add a user space map channel with an automatically generated name to a specific recording session.
====
See the option:--session option.

[role="term"]
----
$ lttng add-map-channel --session=my-session --type=user
----
====

.Add a map channel and create a trigger to count events per name.
====
First, add the map channel:

[role="term"]
----
$ 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:

[role="term"]
----
$ 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'
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-add-trigger(1),
man:lttng-export-maps(1),
man:lttng-list(1),
man:lttng-show-maps(1),
man:lttng-concepts(7)
