VTune CLI usage, scripting, exit codes

[jviktorin]

Hello,

I am trying to use VTune from command line. However, the documentation is quite incomplete. Especially, the exit codes... sometimes I get 1, sometimes 2 or even 3 for various commands. I am trying to achieve the following:

PID=`start_application_to_analyze &`

vtune -collect -target-pid $PID -r $RESULTS_DIR -duration unlimited &

while ! vtune -command status -r $RESULTS_DIR; do

    sleep 1

done

signal_application_to_start_jobs $PID

sleep 10

vtune -command stop -r $RESULTS_DIR

process $RESULTS_DIR

This is just an example, the real code I am working in is written in Python for our CI. When running this manually, it seems like it works as expected. But in CI, the vtune -command status and vtune -command stop sometimes exit with some non-zero error codes and the test fails for no obvious reason. I spent quite a lot of time to investigate what's going on, but it is hard as there are many race conditions around. Can you please clarify the exact behaviour of those commands?

Another point, I've noticed that vtune has issues with special characters in path to (what I call in the example above) RESULTS_DIR. Is it documented somewhere? Is it possible to remove such strange restriction from the analyzer in the future releases?

Is it possible to create the RESULTS_DIR in advance by some command? Because it introduces the egg-and-chicken problem. I start vtune -collect in background and then test by vtune -command status whether it is running. But if the directory RESULTS_DIR does not exist, it fails... Or... can I detect whether the vtune -collect is up and running in some other way?

[VaradJ_Intel]

Hi,

Thank you for posting in Intel Communities.

We tried executing the above code manually but it didn't work for us.

Please can you answer the following questions:

1. Which documentation are you following?

2. Which version of VTune are you using?

3. What kind of application are you trying to profile using VTune?

4. What are you trying to do in your above sample code?

5. What are the error codes that you are getting?

6. Please can you share a sample reproducer code of your application?

7. Please can you share the details of your O.S?

Thank you.

[jviktorin]

We tried executing the above code manually but it didn't work for us.

The code was not intended to be executed, it is more a kind of a pseudo code.

Please can you answer the following questions:

1. Which documentation are you following?

https://www.intel.com/content/www/us/en/develop/documentation/vtune-help/top/command-line-interface.html

$ vtune -help

2. Which version of VTune are you using?

2022.1.0 and 2022.2.0

3. What kind of application are you trying to profile using VTune?

Proprietary DPDK application.

4. What are you trying to do in your above sample code?

Start an application to be profiled. Wait until the application starts (in idle mode). Start vtune attached to the process. Wait until vtune is up and ready to do its job (it does not start immediately). Generate high load of the profiled application (generating high amounts of network traffic) and probably notify vtune to start profiling. Stop vtune, stop the application, evaluate results. The goal is to do this automatically by CI regularly.

We use other profilers as well and they are hidden behind our internal python APIs. We want to integrate vtune there. Thus, I need to understand, what is the exact behaviour of the vtune CLI.

5. What are the error codes that you are getting?

Exit (return) codes of vtune I could see: 1, 2, 3. But, I'd like to understand, what exit codes it gives under which situations like you can find for most utilities in the appropriate man pages.

6. Please can you share a sample reproducer code of your application?

This is not tied to any particular code. You can try e.g. DPDK testpmd for this.

7. Please can you share the details of your O.S?

CentOS 7, Oracle Linux 8.5.

[VaradJ_Intel]

Hi,

Thank you for providing the details.

We are working with the engineering team to get the details about the exit codes.

Meanwhile please could you let us know if you are using "-Dc_args=-DRTE_ETHDEV_PROFILE_WITH_VTUNE" option for building DPDK?

Thank You.

[jviktorin]

Hello,

no, we do not use RTE_ETHDEV_PROFILE_WITH_VTUNE. Anyway, I do not understand what is the purpose of this flag. It is very purely documented and on the first look, it seems to be nearly useless. It just turns on few empty functions, nothing that should bother me as I do not profile DPDK internals... But, I suppose I am wrong and I'd be happy to learn about the magic behind.

[VaradJ_Intel]

Hi,

Thank you for providing all the details.

1. Following are the details of the exit codes.

     0 = success on all fronts = zero application exit code and no regression detected

     1 = user error

     2 = internal tool error

     4 = non-zero application exit code

2. For the issue of the special characters in the path:

In shell script '$' represents a variable. So you need to assign some path to the variable RESULTS_DIR.

Eg.: RESULTS_DIR= /home/abcd/results

and then you can use it in the script.

3. Is it possible to create the RESULTS_DIR in advance by some command?

Yes, you can create a result directory in advance and then you can store all the results there.

You can refer the following links for it

https://www.intel.com/content/www/us/en/develop/documentation/vtune-help/top/command-line-interface/command-line-interface-reference/result-dir.html

https://www.intel.com/content/www/us/en/develop/documentation/vtune-help/top/command-line-interface/running-command-line-analysis/configuring-analysis-options-from-the-command-line/specify-result-directory-from-command-line.html#specify-result-directory-from-command-line

4. Can I detect whether the vtune -collect is up and running in some other way?

Yes you can use echo in your script to know is the vtune -collect is running

Eg.: echo "$(vtune -collect hotspots $path -r $RESULT_DIR)" 

5. We do not use RTE_ETHDEV_PROFILE_WITH_VTUNE. Anyway, I do not understand what is the purpose of this flag:

You can refer the following link for the details of the RTE_ETHDEV_PROFILE_WITH_VTUNE flag.

https://doc.dpdk.org/guides/prog_guide/profile_app.html#profiling-with-vtune

Thank You.

[VaradJ_Intel]

Hi,

We haven't heard back from you. Could you please give us an update?

Thank You.

[VaradJ_Intel]

Hi,

We assume that your issue is resolved. If you need any additional information, please post a new question as this thread will no longer be monitored by Intel.

Thank You.