Configuring an Activity (vtl)Configuring an Activity (vtl)This information applies to the command-line interface (vtl) only.
To start data collection with vtl, you should first create an Activity using the activity command:
vtl activity [<name>]
[-d | -duration <#>]
[-master <name>]
{-c | -collector <type>[,name][-o | -options "<options>"][-of | -options-from-file <filename>]}
[-app | -app-to-launch <path>[,<args>[,<dir>]]]
[-moi | -module-of-interest <options>]
Command-line example:
>vtl activity -d 30 -c sampling -c callgraph -master sampling -app ./vtunedemo -moi ./vtunedemo
This creates an Activity that collects sampling and then call graph data for the vtunedemo application. The Activity duration is 30 seconds.
You can assign a name to your Activity by specifying the <name> parameter. The VTune(TM) Performance Analyzer also assigns a shortcut name to each Activity, for instance: a1 for Activity1. Use the show command to view the project contents and shortcut names of the Activities.
To run/query/view a particular Activity, you can specify the name you assigned to this Activity or the shortcut form of its internal name: [a]number. Use the shortcut form to distinguish different Activities to which you assigned identical names.
Enter the number of seconds <#> that you want the Activity to run and collect data. The duration value includes any delay time specified for a collector. By default, the duration is 20 seconds but if there is an Application to Launch associated with the Activity, the default duration is 0.
To proceed with data collection until the application terminates, specify an Activity duration value that is larger than or corresponds to the amount of time you estimate your application will run.
To continue data collection until you manually stop it, enter 0. This setting runs the Activity infinitely.
To stop data collection manually, use the ActivityController tool.
You can change the default Activity duration using the global-options command. However, this setting is only effective if no application is launched.
Command-line example:
>vtl global-options activity-duration="50"
Use the -master option to set the selected data collector as the master data collector. Choosing one data collector to be the master is useful when there are multiple data collectors in the Activity, and there is a way to correlate the collected data. The name of the collector is either the name specified with the -collector (or -c) option or the type of the collector, if no name is specified.
The master data collector correlates the data collected by all the data collectors, thereby ensuring that all the data collectors collect data at the same time. For example, during an Activity run, if the master data collector pauses its data collection on its own, the other running data collectors also pause data collection. In addition, if the master collector requires multiple runs, it can cause the other data collectors to also run multiple times.
NoteNot all data collectors can be master data collectors. To find out whether the collector you are using is master or not, enter: vtl query -a <activity_name>.
The -start-paused option may not be supported by all data collectors. Use it to set data collectors to start in paused mode. This option is useful if you want to control data collection through the Pause/Resume Activity action within the ActivityController. If you specify this option and run the Activity, data collection begins only after you use the Pause/Resume action again.
Specify the data collector in the Activity with the -collector (or -c) option. If you specify incompatible collectors (for example, sampling and call graph collectors) for the same Activity, the VTune analyzer will run the data collectors one after the other.
NoteThe VTune analyzer enables you to configure a collector manually or using options saved to a file.
TipTo view information on available data collectors, use the query command as follows: vtl query -lc.
The -app-to-launch (or -app) option enables you to specify the application to tune. It is relevant only for data collectors specifically focused on application-centric performance tuning. The data collectors use the application profile to collect more detailed information on the application during the analysis. The type of collected information depends on the data collector you are running.
Depending on the data collector, an application to launch can be required, optional, or unsupported.
The specified application is automatically launched when you run the Activity.
If your application uses multiple command-line arguments, specify the arguments as follows: -app <application_name>,"<arguments>".
Command-line example:
>vtl activity -c sampling -app myecho,"-q -x fred -foo" -o "-sm tbs" run
In general, modules of interest enable some data collectors to do more focused data collection on these modules. To add a module of interest, use the -module-of-interest (or -moi) option and specify the full module name as the argument.
Specify the name of the application to launch as the module of interest (see the exceptions for the script mode).