doc/proposals/0002-lttng-command-line-UI.txt

   1
   2 ******** DEPRECATED ************
   3 * Kept for historical purposes *
   4 ******** DEPRECATED ************
   5
   6 lttng-tools command line interface
   7
   8 (Note: as of June 8th, 2011, this document is at [RFC] stage.)
   9
  10 This document describes the "lttng" command line interface.
  11
  12 Authors:
  13 David Goulet <david.goulet@polymtl.ca>
  14 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  15
  16 We plan to go for a git-alike UI:
  17
  18   lttng command [options]
  19
  20 Where command can be one of the following, and the options are
  21 per-command:
  22
  23 (note: in this description, options between [ ] are optional)
  24
  25 * Basic options
  26
  27   -v, --verbose                # Verbose mode
  28   -q, --quiet                  # Quiet mode
  29       --help                   # Show help
  30       --group NAME             # Unix tracing group name. (default: tracing)
  31       --no-sessiond            # Don't spawn a session daemon
  32       --sessiond-path          # Session daemon full path
  33   help/--help/-h               # list LTTng commands
  34
  35 * List interfaces:
  36
  37 lttng list [--help]        # show list options
  38 lttng list --events        # list all available instrumentation
  39 lttng list --kernel        # list kernel instrumentation
  40 lttng list --pid n         # list userspace app instrumentation by pid
  41 lttng list command_name    # list userspace app instrumentation by command
  42 lttng list --app           # list traceable user-space applications/pids
  43 lttng list --sessions      # list tracing sessions
  44
  45 * Show version
  46
  47 lttng version [--help]     # show lttng-tools version and version options
  48 lttng version --kernel     # show kernel lttng version
  49 lttng version --pid n      # show kernel lttng version
  50 lttng version command_name # show lttng versions for app by command
  51
  52 * Tracing session control
  53
  54 lttng create [--session] name # create a tracing session (default name provided)
  55              [--output path]  # optionally specify the output path
  56
  57 ---> This command prints
  58      "Working directory of created session is /path/to/name. Change your"
  59      "current working directory to interact with this session."
  60
  61 ---> All the following commands use the current working directory
  62      .lttng/config file to keep track of the session on which actions
  63      should be applied.
  64
  65 lttng destroy [--session] name # teardown a tracing session
  66 lttng start [--session] name   # start tracing for a session
  67 lttng stop [--session] name    # stop tracing for a session
  68
  69
  70 (note in manpage (warning) about --all and cmd_name:
  71 "WARNING: this may noticeably slow down your system!")
  72 lttng add-channel name --kernel [options]
  73 lttng add-channel name --userspace [--all/--pid n/cmd_name] [options]
  74   available options:
  75   --discard (default)
  76   --overwrite
  77   --subbuf_size
  78   --num_subbuf
  79   --switch_timer_interval
  80   --read_timer_interval
  81
  82 lttng config --kernel --channel name
  83 lttng config --channel name [--all/--pid n/cmd_name]
  84
  85 (note: no channel name specified creates a "default" channel)
  86 lttng add-event name --kernel [--channel name]
  87 lttng add-event name --userspace [--channel name] [--all/--pid n/cmd_name]
  88   available options, either:
  89   --tracepoint (default)
  90   --marker
  91   --kprobe address
  92   --function
  93   (support list of names: name1,name2,name3... all with the same
  94    options)
  95 lttng enable-event name --kernel [--channel name]
  96 lttng disable-event name --kernel [--channel name]
  97 lttng enable-event name --userspace [--channel name] [--all/--pid n/cmd_name]
  98 lttng disable-event name --userspace [--channel name] [--all/--pid n/cmd_name]
  99
 100 lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options]
 101 lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options]
 102
 103 lttng consume [PATH] --continue --snapshot --stop