[ltt-dev] [RFC] lttng-tools command line interface

[ltt-dev] [RFC] lttng-tools command line interface

[Mathieu Desnoyers]

Hi,

I'm currently discussing with David Goulet about the lttng command line
UI, and here is what we are coming up with:

We plan to go for a git-alike UI:

  lttng command [options]

Where command can be one of the following, and the options are
per-command:

(note: in the description below, options between [ ] are implied by
default)

* Basic options

  -v, --verbose                # Verbose mode
  -q, --quiet                  # Quiet mode
      --help                   # Show help
      --group NAME             # Unix tracing group name. (default: tracing)
      --no-sessiond            # Don't spawn a session daemon
      --sessiond-path          # Session daemon full path
  help/--help/-h               # list LTTng commands

* List interfaces:

lttng list [--help]        # show list options
lttng list --events        # list all available instrumentation
lttng list --kernel        # list kernel instrumentation
lttng list --pid n         # list userspace app instrumentation by pid
lttng list command_name    # list userspace app instrumentation by command
lttng list --app           # list traceable user-space applications/pids
lttng list --sessions      # list tracing sessions

* Show version

lttng version [--help]     # show lttng-tools version and version options
lttng version --kernel     # show kernel lttng version
lttng version --pid n      # show kernel lttng version
lttng version command_name # show lttng versions for app by command

* Tracing session control

lttng create [--session name] # create a tracing session
     [--output path]          # optionally specify the output path 
     [--name name]            # optional session name (default provided)

---> This command prints
     "Working directory of created session is /path/to/name. Change your"
     "current working directory to interact with this session."

---> All the following commands use the current working directory
     .lttng/config file to keep track of the session on which actions
     should be applied.

lttng destroy [--session name] # teardown a tracing session
lttng start [--session name]   # start tracing for a session
lttng stop [--session name]    # stop tracing for a session


(note in manpage (warning) about --all and cmd_name:
"WARNING: this may noticeably slow down your system!")
lttng add-channel name --kernel [options]
lttng add-channel name --userspace [--all/--pid n/cmd_name] [options]
  available options:
  --discard (default)
  --overwrite
  --subbuf_size
  --num_subbuf
  --switch_timer_interval
  --read_timer_interval

lttng config --kernel --channel name
lttng config --channel name [--all/--pid n/cmd_name]

(note: no channel name specified creates a "default" channel)
lttng add-event name --kernel [--channel name]
lttng add-event name --userspace [--channel name] [--all/--pid n/cmd_name]
  available options, either:
  --tracepoint (default)
  --marker
  --kprobe address
  --function
  (support list of names: name1,name2,name3... all with the same
   options)
lttng enable-event name --kernel [--channel name]
lttng disable-event name --kernel [--channel name]
lttng enable-event name --userspace [--channel name] [--all/--pid n/cmd_name]
lttng disable-event name --userspace [--channel name] [--all/--pid n/cmd_name]

lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options]
lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options]

Comments are immensely welcome!

Thanks,

Mathieu

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com

[ltt-dev] [RFC] lttng-tools command line interface

[Mathieu Desnoyers]

* Mathieu Desnoyers (mathieu.desnoyers at efficios.com) wrote:
> Hi,
> 
> I'm currently discussing with David Goulet about the lttng command line
> UI, and here is what we are coming up with:
> 
> We plan to go for a git-alike UI:
> 
>   lttng command [options]
> 
> Where command can be one of the following, and the options are
> per-command:
> 
> (note: in the description below, options between [ ] are implied by
> default)

This note is actually inaccurate: the elements below between [ ] are
actually optional, not "implied by default" as stated above.

Mathieu

> 
> * Basic options
> 
>   -v, --verbose                # Verbose mode
>   -q, --quiet                  # Quiet mode
>       --help                   # Show help
>       --group NAME             # Unix tracing group name. (default: tracing)
>       --no-sessiond            # Don't spawn a session daemon
>       --sessiond-path          # Session daemon full path
>   help/--help/-h               # list LTTng commands
> 
> * List interfaces:
> 
> lttng list [--help]        # show list options
> lttng list --events        # list all available instrumentation
> lttng list --kernel        # list kernel instrumentation
> lttng list --pid n         # list userspace app instrumentation by pid
> lttng list command_name    # list userspace app instrumentation by command
> lttng list --app           # list traceable user-space applications/pids
> lttng list --sessions      # list tracing sessions
> 
> * Show version
> 
> lttng version [--help]     # show lttng-tools version and version options
> lttng version --kernel     # show kernel lttng version
> lttng version --pid n      # show kernel lttng version
> lttng version command_name # show lttng versions for app by command
> 
> * Tracing session control
> 
> lttng create [--session name] # create a tracing session
>      [--output path]          # optionally specify the output path 
>      [--name name]            # optional session name (default provided)
> 
> ---> This command prints
>      "Working directory of created session is /path/to/name. Change your"
>      "current working directory to interact with this session."
> 
> ---> All the following commands use the current working directory
>      .lttng/config file to keep track of the session on which actions
>      should be applied.
> 
> lttng destroy [--session name] # teardown a tracing session
> lttng start [--session name]   # start tracing for a session
> lttng stop [--session name]    # stop tracing for a session
> 
> 
> (note in manpage (warning) about --all and cmd_name:
> "WARNING: this may noticeably slow down your system!")
> lttng add-channel name --kernel [options]
> lttng add-channel name --userspace [--all/--pid n/cmd_name] [options]
>   available options:
>   --discard (default)
>   --overwrite
>   --subbuf_size
>   --num_subbuf
>   --switch_timer_interval
>   --read_timer_interval
> 
> lttng config --kernel --channel name
> lttng config --channel name [--all/--pid n/cmd_name]
> 
> (note: no channel name specified creates a "default" channel)
> lttng add-event name --kernel [--channel name]
> lttng add-event name --userspace [--channel name] [--all/--pid n/cmd_name]
>   available options, either:
>   --tracepoint (default)
>   --marker
>   --kprobe address
>   --function
>   (support list of names: name1,name2,name3... all with the same
>    options)
> lttng enable-event name --kernel [--channel name]
> lttng disable-event name --kernel [--channel name]
> lttng enable-event name --userspace [--channel name] [--all/--pid n/cmd_name]
> lttng disable-event name --userspace [--channel name] [--all/--pid n/cmd_name]
> 
> lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options]
> lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options]
> 
> Comments are immensely welcome!
> 
> Thanks,
> 
> Mathieu
> 
> -- 
> Mathieu Desnoyers
> Operating System Efficiency R&D Consultant
> EfficiOS Inc.
> http://www.efficios.com
> 
> _______________________________________________
> ltt-dev mailing list
> ltt-dev at lists.casi.polymtl.ca
> http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev
> 

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com

[ltt-dev] [RFC] lttng-tools command line interface

[Alexandre Montplaisir]

Very nice!


Some dumb questions:

On 11-06-07 07:08 PM, Mathieu Desnoyers wrote:
> ... the elements below between [ ] are
> actually optional, not "implied by default" as stated above.
>

> * Tracing session control
>
> lttng create [--session name] # create a tracing session
>       [--output path]          # optionally specify the output path
>       [--name name]            # optional session name (default provided)
>
> --->  This command prints
>       "Working directory of created session is /path/to/name. Change your"
>       "current working directory to interact with this session."

Is this what is printed if only "lttng create" with no parameters is 
typed in?
If yes, what is the default session name?
If not, I guess it prints the same as "lttng create --help" ?

>
> --->  All the following commands use the current working directory
>       .lttng/config file to keep track of the session on which actions
>       should be applied.

Yup, Git-alike  ;)

>
> lttng destroy [--session name] # teardown a tracing session
> lttng start [--session name]   # start tracing for a session
> lttng stop [--session name]    # stop tracing for a session

Is "--session" needed here, or would just "lttng destroy mysession" be 
allowed/wanted too?
? la "git push origin master", which does not require any --options for 
mandatory parameters, only extras.

>
> lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options]
> lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options]

I guess you have plans for short options too? like,
-k, --kernel
-u, --userspace
-e, --event
etc.

> Comments are immensely welcome!
>
> Thanks,
>
> Mathieu
>

Looks great! Can't wait to try it!

-- 
Alexandre Montplaisir
DORSAL lab,
?cole Polytechnique de Montr?al

[ltt-dev] [RFC] lttng-tools command line interface

[Stefan Hajnoczi]

On Wed, Jun 8, 2011 at 12:08 AM, Mathieu Desnoyers
<mathieu.desnoyers at efficios.com> wrote:
> * Tracing session control
>
> lttng create [--session name] # create a tracing session
> ? ? [--output path] ? ? ? ? ?# optionally specify the output path
> ? ? [--name name] ? ? ? ? ? ?# optional session name (default provided)

What is the difference between --session <name> and --name <name>?

Stefan

[ltt-dev] [RFC] lttng-tools command line interface

[Mathieu Desnoyers]

* Alexandre Montplaisir (alexandre.montplaisir at polymtl.ca) wrote:
> Very nice!
>
>
> Some dumb questions:
>
> On 11-06-07 07:08 PM, Mathieu Desnoyers wrote:
>> ... the elements below between [ ] are
>> actually optional, not "implied by default" as stated above.
>>
>
>> * Tracing session control
>>
>> lttng create [--session name] # create a tracing session
>>       [--output path]          # optionally specify the output path
>>       [--name name]            # optional session name (default provided)
>>
>> --->  This command prints
>>       "Working directory of created session is /path/to/name. Change your"
>>       "current working directory to interact with this session."
>
> Is this what is printed if only "lttng create" with no parameters is  
> typed in?

This is what is printed with or without parameters.

> If yes, what is the default session name?

Maybe David has ideas on this ? I'm thinking along:
trace-$(date)

> If not, I guess it prints the same as "lttng create --help" ?
>
>>
>> --->  All the following commands use the current working directory
>>       .lttng/config file to keep track of the session on which actions
>>       should be applied.
>
> Yup, Git-alike  ;)
>
>>
>> lttng destroy [--session name] # teardown a tracing session
>> lttng start [--session name]   # start tracing for a session
>> lttng stop [--session name]    # stop tracing for a session
>
> Is "--session" needed here, or would just "lttng destroy mysession" be  
> allowed/wanted too?

good point, will add.


> ? la "git push origin master", which does not require any --options for  
> mandatory parameters, only extras.
>
>>
>> lttng add-context name --kernel [--event name] [--channel name] --type context_type [context options]
>> lttng add-context name --userspace [--event name] [--channel name] [--all/--pid n/cmd_name] --type context_type [context options]
>
> I guess you have plans for short options too? like,
> -k, --kernel
> -u, --userspace
> -e, --event
> etc.

Yes, we wanted to get the long options right first, and let David figure
out the shortcuts ;)

>
>> Comments are immensely welcome!
>>
>> Thanks,
>>
>> Mathieu
>>
>
> Looks great! Can't wait to try it!

Me too !

Thanks for the feedback,

Mathieu

>
> -- 
> Alexandre Montplaisir
> DORSAL lab,
> ?cole Polytechnique de Montr?al
>

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com

[ltt-dev] [RFC] lttng-tools command line interface

[Mathieu Desnoyers]

* Stefan Hajnoczi (stefanha at gmail.com) wrote:
> On Wed, Jun 8, 2011 at 12:08 AM, Mathieu Desnoyers
> <mathieu.desnoyers at efficios.com> wrote:
> > * Tracing session control
> >
> > lttng create [--session name] # create a tracing session
> > ? ? [--output path] ? ? ? ? ?# optionally specify the output path
> > ? ? [--name name] ? ? ? ? ? ?# optional session name (default provided)
> 
> What is the difference between --session <name> and --name <name>?

They are basically the same. I'll juste leave:

lttng create [--session] name [--output path]

Sounds ok ?

Mathieu

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com