| 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] |
| 97 | |
| 98 | lttng consume [PATH] --continue --snapshot --stop |