Refactor: lttng-ctl: follow terminology of the tracker documentation
This commit harmonizes the process attribute tracker API and
serialization formats (save/restore and MI) with the documentation
with regards to the terminology used.
The message of the parent commit adjusting the manual pages of the
lttng-track and lttng-untrack commands details those terminology
changes and their rationale.
Some problems with the API introduced during the 2.12 development
cycle are also adressed:
Type safety:
- The process attribute tracker is made type safe with regards
to the platform's native types to express process
attributes. Where the original API casted all integral values to
integers, this change introduces accessors for all process
attribute types (pid_t, uid_t, gid_t). This makes it easier to
use the API safely and without producing warnings in user's
code.
Another benefit of adopting this explicit type-safe approach is
that is will make it easier to add new attributes which are not
expressible (or non-ambiguously expressible) using `int` and
`string` types (e.g. tracking a virtual PID within a given
namespace).
Ambiguity of INCLUDE_ALL, EXCLUDE_ALL, and INCLUDE_SET states:
- The original tracker API has a notion of 'enabled' pid_tracker
which is confusing to users:
- enable = 0: everything is tracked,
- enable = 1: a list of tracked pids is provided, which may be
empty.
- pid '-1' is *special* and tracks or untracks everything.
This was replaced with a 'special' opaque value meaning 'ALL'
which, while being clearer, was still confusing and hard to
document.
The revised API explicitly expresses the notion of a tracking
policy (`enum lttng_tracking_policy`). When that policy is set
to `LTTNG_TRACKING_POLICY_INCLUDE_SET`, the inclusion set can
be queried and/or mutated.
On top of being clearer, this aligns more closely with the
internal lttng-sessiond daemon API which gets rid of a lot
of code to handle those special cases. The resulting code is
more verbose, but a lot easier to understand.
Moreover, the types introduced (e.g. lttng_process_attr_values)
are meant to be re-used if a new
`LTTNG_TRACKING_POLICY_EXCLUDE_SET` tracking policy is added in
the future.
Documentation:
- The revised API includes a complete documentation. It documents
the API usage, but also adds implementation notes such explicitly
mentionning when/where user names and group names are resolved.
Client:
- While making the changes to use this new API, some error messages
are clarified (or added). The resulting output when listing the
trackers was also changed to be more compact.
The CLI output now also makes use of the terminology used in
the documentation for all commands interacting with process
attribute trackers.
It is now also possible to specify multiple process attribute
trackers along with the --all option for the lttng-track and
lttng-untrack command. For instance: `lttng tracker --userspace
--vpid --vuid --all` is now allowed.
The same process attribute tracker can also be specified more than
once in a command, as follows:
`lttng track --userspace --vpid 43,11 --vpid 55,77`
Since the serialization had been changed during the 2.12 cycle, I
changed them further to use the API's terminology in the element
names.
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: I5f0ea2849eb024ea6944b2ee7dbadfd893cc0be4
43 files changed:
This page took 0.030957 seconds and 5 git commands to generate.