RFC - Triggers in lttng-tools

Author: David Goulet <dgoulet@efficios.com>

Version:
    - v0.1: 11/04/2013
        * Initial proposal

Motivation
----------

The main idea of triggers is for the user to be able to set an action on a
session triggered by a certain event of the system. To illustrace the concept,
here is an example that we will actually propose.

Let say an application is being traced and on core dump, we would like to
automatically snapshot the session and proceed to analysis later on.

The idea would be to set a "trigger" named OnAnyCoreDump for the session. Any
coredump detected using /proc/sys/kernel/core_pattern will send a notification
to the session daemon and trigger the user defined action.

Proposed Solution
-----------------

First, a trigger command is needed and goes as followed.

    $ lttng trigger [OPTIONS] <WHAT> <ACTION>

    OPTIONS:
        -s, --session NAME

For the example showed in the Motivation section, the <WHAT> is OnAnyCoreDump
and the <ACTION> is to take a snapshot of the session where this trigger is
set.

    $ lttng trigger -s mysession OnAnyCoreDump snapshot

Using a provided lttng helper program so the system can notify the session
daemon, a new notification socket is needed. A Unix named socket is proposed.

    LTTNG_RUN_DIR/notify-lttng-sessiond

In order to use the notify socket, the message protocol is detailed as
followed.

enum lttcomm_sessiond_notify_cmd {
    LTTCOMM_NOTIFY_TRIGGER_ONANYCOREDUMP = 1,
};

struct lttcomm_sessiond_notify_header {
    uint32_t cmd;   /* A lttcomm_sessiond_notify_cmd value. */
    uint32_t msg_size;
};

struct lttcomm_sessiond_notify_onanycoredump {
    uint32_t pid;
    uint32_t uid;
    uint32_t gid;
    char exec_name[NAME_MAX];
    char hostname[255]; /* RFC 1035 specify this max size of bytes */
};

Public API
----------

enum lttng_trigger_type {
    LTTNG_TRIGGER_TYPE_ONANYCOREDUMP = 1,
};

enum lttng_trigger_action {
    LTTNG_TRIGGER_ACTION_SNAPSHOT = 1,
    LTTNG_TRIGGER_ACTION_STOP     = 2,
};

struct lttng_trigger_onanycoredump {
    pid_t pid;
    uid_t uid;
    gid_t gid;
    char exec_name[NAME_MAX];
    char hostname[255]; /* RFC 1035 specify this max size of bytes */
};

/*
 * Set a trigger on a specific session using the given handle. For now, we
 * don't allow options to an action so opts and nb_opt are ignored.
 *
 * On success return 0 or else a negative LTTNG_ERR* code.
 */
int lttng_trigger_set(struct lttng_handle *handle,
                      enum lttng_trigger_type type,
                      enum lttng_trigger_action action,
                      const void *opts,
                      size_t nb_opt);

/*
 * Fireup a trigger of the given type. If socket_path is defined, the
 * liblttng-ctl will use it or else use the default using the UID of the
 * caller.
 *
 * Return 0 on success or else a negative LTTNG_ERR* code.
 */
int lttng_trigger(enum lttng_trigger_type type,
                  char *socket_path,
                  const void *opts,
                  size_t nb_opt);

As an example, to set a onanycoredump trigger and then fire it up.

lttng_trigger_set(handle, LTTNG_TRIGGER_TYPE_ONANYCOREDUMP,
            LTTNG_TRIGGER_ACTION_SNAPSHOT, NULL, 0);

Now to fire it up by being let say in a small program set in
/proc/.../core_pattern.

struct lttng_trigger_onanycoredump lto = {
    .pid = 42,
    .uid = 1000,
    .gid = 1000,
    .exec_name = "apache2",
    .hostname = "A_HOST_NAME",
};

lttng_trigger(LTTNG_TRIGGER_TYPE_ONANYCOREDUMP,
        "/home/auser/.lttng/notify-lttng-sessiond", &lto, sizeof(lto));