From: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Date: Tue, 17 Mar 2020 20:14:30 +0000 (-0400)
Subject: Refactor: lttng-ctl: follow terminology of the tracker documentation
X-Git-Tag: v2.13.0-rc1~715
X-Git-Url: https://git.lttng.org/?a=commitdiff_plain;h=159b042f34366d0fde5dcd73b4231c558922a664;hp=159b042f34366d0fde5dcd73b4231c558922a664;p=lttng-tools.git

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