doc/proposals/0004-lttng-address-api.txt

   1 RFC - LTTng address API proposal
   2
   3 Author: David Goulet <david.goulet@efficios.com>
   4
   5 Contributors:
   6     * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   7         * Yannick Brosseau <yannick.brosseau@polymtl.ca>
   8
   9 Version:
  10     - v0.1: 31/07/2012
  11         * Initial proposal
  12
  13 Introduction
  14 -----------------
  15
  16 This document proposes the use of string URLs to the command line interface and
  17 API which will deprecate a function and propose new ones.
  18
  19 The purpose of this proposal is to support network streaming using URL string
  20 format that you can find in proposal doc/proposals/0003-network.consumer.txt,
  21 remove the lttng_uri structure from the API and integrate the URL string to the
  22 API.
  23
  24 API
  25 -----------------
  26
  27 In order not to expose the new lttng_uri structure used to identify trace
  28 location for lttng consumer, the public API will only use string address where
  29 it will be converted in a lttng_uri and sent to the session daemon.
  30
  31 [*] Create session:
  32
  33 With the introduction of the enable-consumer command used for network streaming,
  34 the create session command has been modified so the user could define a consumer
  35 location either on the network or local with the command. This change deprecates
  36 the old API function and adds a new one.
  37
  38 Deprecated:
  39 --> lttng_create_session(const char *name, const char *path);
  40
  41 Proposed:
  42 --> lttng_create_session_addr(const char *name, const char *addr,
  43                                                                 int enable_consumer);
  44
  45 The _name_ argument is the session name and _addr_ is a string representing the
  46 URL specified by the user which looks like this:
  47
  48 PROTO://[HOST|IP][:PORT][/PATH]
  49
  50 Examples:
  51
  52 * net://myhostname
  53 * net://myhostname:9888
  54 * net://myhostname/foo/bar
  55 * net://X.X.X.X:9888/foo/bar
  56
  57 The enable_consumer option will disable the use of the consumer for the tracing
  58 session. This will be useful with the to come snapshot feature. The motivation
  59 behing this flag is to offer the same options as the enable-consumer command
  60 where you can only set the URI for the consumer and not enable it.
  61
  62 [*] Consumer:
  63
  64 The current lttng_set_consumer_uri(...) call will be changed to:
  65
  66 lttng_set_consumer_addr(struct lttng_handle *handle,
  67                                 const char *addr);
  68
  69 For both functions (consumer and create), the addr will be translate to a
  70 lttng_uri in the liblttng-ctl and sent to the session daemon.
  71
  72 With all this, the lttng_uri data structure will not be exposed to the public
  73 API and the user command line interface.