doc/dev/lttng-cli.txt

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