“Increment map value” trigger action API

Collaboration diagram for “Increment map value” trigger action API:

Enumerations
enum	lttng_key_template_status { LTTNG_KEY_TEMPLATE_STATUS_OK , LTTNG_KEY_TEMPLATE_STATUS_ERROR , LTTNG_KEY_TEMPLATE_STATUS_INVALID }
	Return type of key template API functions. More...

Functions
struct lttng_action *	lttng_action_increment_map_value_create (void)
	Creates an initial “increment map value” trigger action.
enum lttng_action_status	lttng_action_increment_map_value_get_key_template (const struct lttng_action *action, const struct lttng_key_template **key_template)
	Sets *key_template to the key template of the “increment map value” trigger action action.
enum lttng_action_status	lttng_action_increment_map_value_get_target_channel_name (const struct lttng_action *action, const char **channel_name)
	Sets *channel_name to the target map channel name of the “increment map value” trigger action action.
enum lttng_action_status	lttng_action_increment_map_value_get_target_channel_type (const struct lttng_action *action, enum lttng_map_channel_type *type)
	Sets *type to the target map channel type of the “increment map value” trigger action action.
enum lttng_action_status	lttng_action_increment_map_value_get_target_session_name (const struct lttng_action *action, const char **session_name)
	Sets *session_name to the target recording session name of the “increment map value” trigger action action.
enum lttng_action_status	lttng_action_increment_map_value_set_key_template (struct lttng_action *action, const struct lttng_key_template *key_template)
	Sets the key template of the “increment map value” trigger action action to a copy of key_template.
enum lttng_action_status	lttng_action_increment_map_value_set_target_channel_name (struct lttng_action *action, const char *channel_name)
	Sets the target map channel name of the “increment map value” trigger action action to channel_name.
enum lttng_action_status	lttng_action_increment_map_value_set_target_channel_type (struct lttng_action *action, enum lttng_map_channel_type type)
	Sets the target map channel type of the “increment map value” trigger action action to type.
enum lttng_action_status	lttng_action_increment_map_value_set_target_session_name (struct lttng_action *action, const char *session_name)
	Sets the target recording session name of the “increment map value” trigger action action to session_name.
struct lttng_key_template *	lttng_key_template_create_from_string (const char *template_string)
	Creates a key template from the template string template_string.
void	lttng_key_template_destroy (struct lttng_key_template *key_template)
	Destroys the key template key_template.
enum lttng_key_template_status	lttng_key_template_to_string (const struct lttng_key_template *key_template, char **template_string)
	Renders the key template key_template back to its template string form.

Detailed Description

An “increment map value” trigger action adds 1 to one specific value, in one specific map of one specific map group of a target map channel, when its containing trigger fires.

When the containing trigger's condition isn't an “event rule matches” condition, the target map channel type must be LTTNG_MAP_CHANNEL_TYPE_USER (LTTng increments a counter within the shared user space map, as there's no Linux kernel instrumentation point executor in that case) and the key template must be literal (it must contain no placeholder).

When LTTng executes this action, it selects:

A map group (within the target map channel)

Based on the owner ID of the executor of the instrumentation point:

Kernel

The single, system-wide group.

User space

The group matching the buffer ownership model (per user or per process), the Unix user or process ID, and the effective value type which the value type of the channel resolves to for the bitness of the executing application.

A map (within the selected map group)

Based on the partitioning of the channel: as of LTTng-tools 16.2, by the ID of the CPU which executes the instrumentation point.

The entry index, within the selected map

The index which the target map channel associates to the effective map key of the action.

The effective key is the result of expanding the key template of the action.

A key template is an opaque object which you build from a template string with lttng_key_template_create_from_string(), set with lttng_action_increment_map_value_set_key_template(), and render back to its template string form if needed with lttng_key_template_to_string().

Within the template string, LTTng substitutes the following placeholders (only available when the condition of the containing trigger is an “event rule matches” condition whose event rule doesn't have the type LTTNG_EVENT_RULE_TYPE_JUL_LOGGING, LTTNG_EVENT_RULE_TYPE_LOG4J_LOGGING, LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING, or LTTNG_EVENT_RULE_TYPE_PYTHON_LOGGING):

Placeholder	Substituted with
{event_name}	Effective name of the event which made the trigger fire (see the event name condition of a recording event rule). For example, canadian_tire:money_redeemed (user space tracepoint), sched_switch (Linux kernel tracepoint), openat (Linux kernel system call), or ca.provigo.checkout.ScannerLogger (Java or Python logger name).
{provider_name}	Name of the LTTng tracepoint provider of the event which made the trigger fire. For example, canadian_tire (user space tracepoint canadian_tire:money_redeemed) or sched (Linux kernel tracepoint sched_switch).

LTTng uses any other text in the template string as is. To include a literal { or } character in the effective key, use {{ or }} in the template string (similar to {fmt} and Python's f-string syntax).

The target map channel must exist when LTTng is ready to execute the action; otherwise, LTTng does nothing.

LTTng only increments the map value when the target recording session is active (started). While the target recording session is inactive (stopped), this action does nothing.

The update policy of the target map channel controls how LTTng increments map values when multiple “increment map value” actions which target the same recording session and map channel produce the same effective key (for example, multiple “event rule matches” triggers matching the same event).

An “increment map value” trigger action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.

Unlike the other trigger action types, an “increment map value” action may execute out of order within its containing action list: when the list contains at least one “increment map value” action, LTTng doesn't guarantee the execution order of the “increment map value” action(s) relative to all the actions of the list, including other “increment map value” actions.

To create a valid “increment map value” trigger action:

1. Create the initial trigger action with lttng_action_increment_map_value_create().
2. Set the target recording session name with lttng_action_increment_map_value_set_target_session_name().
3. Set the target map channel name with lttng_action_increment_map_value_set_target_channel_name().
4. Set the target map channel type (LTTNG_MAP_CHANNEL_TYPE_KERNEL or LTTNG_MAP_CHANNEL_TYPE_USER) with lttng_action_increment_map_value_set_target_channel_type().
5. Build a key template with lttng_key_template_create_from_string() and set it with lttng_action_increment_map_value_set_key_template().

Get the corresponding properties with lttng_action_increment_map_value_get_target_session_name(), lttng_action_increment_map_value_get_target_channel_name(), lttng_action_increment_map_value_get_target_channel_type(), and lttng_action_increment_map_value_get_key_template().

Enumeration Type Documentation

lttng_key_template_status

enum lttng_key_template_status

Return type of key template API functions.

Enumerator
LTTNG_KEY_TEMPLATE_STATUS_OK	Success.
LTTNG_KEY_TEMPLATE_STATUS_ERROR	Error.
LTTNG_KEY_TEMPLATE_STATUS_INVALID	Unsatisfied precondition.

Function Documentation

lttng_action_increment_map_value_create()

struct lttng_action * lttng_action_increment_map_value_create ( void  )

extern

Creates an initial “increment map value” trigger action.

On success, the returned trigger action isn't valid yet; you must set, with the corresponding setters:

• The target recording session name.
• The target map channel name.
• The target map channel type (LTTNG_MAP_CHANNEL_TYPE_KERNEL or LTTNG_MAP_CHANNEL_TYPE_USER).
• The key template.

Returns

Trigger action with the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE on success, or NULL on error.

Destroy the returned trigger action with lttng_action_destroy().

lttng_action_increment_map_value_get_key_template()

enum lttng_action_status lttng_action_increment_map_value_get_key_template ( const struct lttng_action *  action, const struct lttng_key_template **  key_template  )

extern

Sets *key_template to the key template of the “increment map value” trigger action action.

Parameters

[in]	action	“Increment map value” trigger action of which to get the key template.
[out]	key_template	On success, this function sets *key_template to the key template of action. action owns *key_template, which remains valid until the next setter call with action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_UNSET	The key template of action is not set.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• key_template is not NULL.

See also

lttng_action_increment_map_value_set_key_template() – Set the key template of an “increment map value” trigger action.

lttng_key_template_to_string() – Render a key template back to its string form.

lttng_action_increment_map_value_get_target_channel_name()

enum lttng_action_status lttng_action_increment_map_value_get_target_channel_name ( const struct lttng_action *  action, const char **  channel_name  )

extern

Sets *channel_name to the target map channel name of the “increment map value” trigger action action.

Parameters

[in]	action	“Increment map value” trigger action of which to get the target map channel name.
[out]	channel_name	On success, this function sets *channel_name to the target map channel name of action. action owns *channel_name, which remains valid until the next setter call with action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_UNSET	The target map channel name of action is not set.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• channel_name is not NULL.

See also

lttng_action_increment_map_value_set_target_channel_name() – Set the target map channel name of an “increment map value” trigger action.

lttng_action_increment_map_value_get_target_channel_type()

enum lttng_action_status lttng_action_increment_map_value_get_target_channel_type ( const struct lttng_action *  action, enum lttng_map_channel_type *  type  )

extern

Sets *type to the target map channel type of the “increment map value” trigger action action.

Parameters

[in]	action	“Increment map value” trigger action of which to get the target map channel type.
[out]	type	On success, this function sets *type to the target map channel type of action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_UNSET	The target map channel type of action is not set.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• type is not NULL.

See also

lttng_action_increment_map_value_set_target_channel_type() – Set the target map channel type of an “increment map value” trigger action.

lttng_action_increment_map_value_get_target_session_name()

enum lttng_action_status lttng_action_increment_map_value_get_target_session_name ( const struct lttng_action *  action, const char **  session_name  )

extern

Sets *session_name to the target recording session name of the “increment map value” trigger action action.

Parameters

[in]	action	“Increment map value” trigger action of which to get the target recording session name.
[out]	session_name	On success, this function sets *session_name to the target recording session name of action. action owns *session_name, which remains valid until the next setter call with action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_UNSET	The target recording session name of action is not set.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• session_name is not NULL.

See also

lttng_action_increment_map_value_set_target_session_name() – Set the target recording session name of an “increment map value” trigger action.

lttng_action_increment_map_value_set_key_template()

enum lttng_action_status lttng_action_increment_map_value_set_key_template ( struct lttng_action *  action, const struct lttng_key_template *  key_template  )

extern

Sets the key template of the “increment map value” trigger action action to a copy of key_template.

See api_trigger_action_incr_map_val_key_template for details.

Build a key template from a template string with lttng_key_template_create_from_string().

Parameters

[in]	action	“Increment map value” trigger action of which to set the key template.
[in]	key_template	Key template to copy into action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_ACTION_STATUS_ERROR	Memory error.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• key_template is not NULL.

See also

lttng_action_increment_map_value_get_key_template() – Get the key template of an “increment map value” trigger action.

lttng_key_template_create_from_string() – Build a key template from a template string.

lttng_action_increment_map_value_set_target_channel_name()

enum lttng_action_status lttng_action_increment_map_value_set_target_channel_name ( struct lttng_action *  action, const char *  channel_name  )

extern

Sets the target map channel name of the “increment map value” trigger action action to channel_name.

LTTng finds the target map channel by name, within the target recording session, when it executes action.

Parameters

[in]	action	“Increment map value” trigger action of which to set the target map channel name.
[in]	channel_name	Target map channel name of action (copied).

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_ACTION_STATUS_ERROR	Memory error.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• channel_name is not NULL.

See also

lttng_action_increment_map_value_get_target_channel_name() – Get the target map channel name of an “increment map value” trigger action.

lttng_action_increment_map_value_set_target_channel_type()

enum lttng_action_status lttng_action_increment_map_value_set_target_channel_type ( struct lttng_action *  action, enum lttng_map_channel_type  type  )

extern

Sets the target map channel type of the “increment map value” trigger action action to type.

The target type selects which tracer owns the target map channel: a given map channel name may exist as both a Linux kernel and a user space map channel within the target recording session, therefore the type disambiguates the lookup LTTng performs when it executes action.

Parameters

[in]	action	“Increment map value” trigger action of which to set the target map channel type.
[in]	type	Target map channel type of action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.

See also

lttng_action_increment_map_value_get_target_channel_type() – Get the target map channel type of an “increment map value” trigger action.

lttng_action_increment_map_value_set_target_session_name()

enum lttng_action_status lttng_action_increment_map_value_set_target_session_name ( struct lttng_action *  action, const char *  session_name  )

extern

Sets the target recording session name of the “increment map value” trigger action action to session_name.

LTTng finds the recording session which contains the target map channel by name when it executes action.

Parameters

[in]	action	“Increment map value” trigger action of which to set the target recording session name.
[in]	session_name	Target recording session name of action (copied).

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_ACTION_STATUS_ERROR	Memory error.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_INCREMENT_MAP_VALUE.
• session_name is not NULL.

See also

lttng_action_increment_map_value_get_target_session_name() – Get the target recording session name of an “increment map value” trigger action.

lttng_key_template_create_from_string()

struct lttng_key_template * lttng_key_template_create_from_string ( const char *  template_string )

extern

Creates a key template from the template string template_string.

The syntax of template_string is similar to {fmt} and Python's f-string.

See the key template documentation for the grammar of template_string and the available placeholders.

Parameters

[in]

template_string

Template string to parse.

Returns

Key template parsed from template_string on success, or NULL on memory error.

Destroy the returned key template with lttng_key_template_destroy().

Precondition

• template_string is not NULL.
• template_string isn't empty.
• template_string doesn't end while a placeholder is open.
• template_string only references available placeholder names.

See also

lttng_key_template_to_string() – Render a key template back to its string form.

lttng_key_template_destroy()

void lttng_key_template_destroy ( struct lttng_key_template *  key_template )

extern

Destroys the key template key_template.

Parameters

[in]

key_template

Key template to destroy. May be NULL.

lttng_key_template_to_string()

enum lttng_key_template_status lttng_key_template_to_string ( const struct lttng_key_template *  key_template, char **  template_string  )

extern

Renders the key template key_template back to its template string form.

The returned string round-trips through lttng_key_template_create_from_string(): parsing it yields a key template equivalent to key_template. That being said, the returned string isn't necessarily identical to the template string which produced key_template: this function renders each placeholder in a canonical form. For example, an original { event_name } renders back as {event_name}.

Parameters

[in]	key_template	Key template to render.
[out]	template_string	On success, this function sets *template_string to a newly-allocated, NUL-terminated string holding the template string form of key_template. The caller owns *template_string and must release it with free().

Return values

LTTNG_KEY_TEMPLATE_STATUS_OK	Success.
LTTNG_KEY_TEMPLATE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_KEY_TEMPLATE_STATUS_ERROR	Memory error.

Precondition

• key_template is not NULL.
• template_string is not NULL.

See also

lttng_key_template_create_from_string() – Parse a template string into a key template.