Intel® VTune™ Profiler User Guide

User Guide

Contents

Create a CSV File with External Data

Intel® VTune™
Profiler
 can process and integrate performance statistics collected externally with a custom сollector or with your target application in parallel with the native
VTune
Profiler
 analysis. To achieve this, provide the collected custom data as a
csv
 file with a predefined structure and save this file to the
VTune
Profiler
 result directory.
VTune
Profiler
 can load and process the following data types:
To make the
VTune
Profiler
 interpret the custom statistics from the
csv
 file, make sure the file format meets the following requirements:

File Name

csv
 filename should specify the hostname where your custom collector gathered the data, following these format requirements:
Filename format:
[
user-defined
]-hostname-<
hostname-of-system
>.csv
Where:
  • [
    user-defined
    ]
     is an option string, for example, describing the type of data collected
  • -hostname-
     is a
    required
     text that must be specified verbatim
  • <
    hostname-of-system
    >
     is the name of the system where the data is collected. If you use a custom collector you can retrieve the hostname by using the
    VTUNE
    _HOSTNAME
     environment variable. If you create a CSV file to import into an existing result, you can either refer to the Summary window that provides the required hostname in the
    Collection and Platform Info
     section >
    Computer name
    , or check the corresponding
    vtune
    summary report:
    vtune
     -r <result> -R summary
    .
Example:
phases-hostname-octagon53.csv
If the hostname in the
csv
 file name is not specified or specified incorrectly, the
VTune
Profiler
 displays the imported data with the following limitations:
  • Event timestamps are represented in the UTC format.
  • Only global data (not attributed to specific threads/processes) are displayed.

Format for Interval Values

Interval data may be optionally bound to a thread ID.
VTune
Profiler
 represents data not bound to a particular thread (there are no TID values in the
csv
 file) as
frames
. Data bound to a thread (there are TID values in the
csv
 file) is represented as
tasks
.
For imported
interval
 values, use 5 columns, where the order of columns is important:
name,start_tsc.[QPC|CLOCK_MONOTONIC_RAW|RDTSC|UTC],end_tsc,[pid],[tid]
Column Name
Description
name
Name of an event.
start_tsc.[QPC|CLOCK_MONOTONIC_RAW|RDTSC|UTC]
Event start timestamp. This column name has a
QPC|CLOCK_MONOTONIC_RAW
,
RDTSC
 or
UTC
 suffix that indicates the type of a timestamp counter:
  • Specify
    QPC
     (
    QueryPerformanceCounter
    ) on Windows* OS if the performance counter is used and specify
    CLOCK_MONOTONIC_RAW
     on Linux* OS if
    clock_gettime(CLOCK_MONOTONIC_RAW)
     is used.
  • Specify
    RDTSC
     if the RDTSC counter is used. To obtain RDTSC:
    • For Microsoft* Compiler and Intel® Compiler, use
      _rdtsc()
       intrinsic
    • For GCC* compiler, copy the following function to your code and call it where necessary: 
    #include <stdint.h>
int64_t rdtsc()
{
    int64_t    tstamp;

#if defined(__x86_64__)
    asm(    "rdtsc\n\t"
            "shlq   $32,%%rdx\n\t"
            "or     %%rax,%%rdx\n\t"
            "movq   %%rdx,%0\n\t"
            : "=g"(tstamp)
            :
            : "rax", "rdx" );
#elif defined(__i386__)
    asm( "rdtsc\n": "=A"(tstamp) );
#else
#error NYI
#endif
    return tstamp;
}
  • Specify
    UTC
     if date and time is used. Expected format is
    YYYY-MM-DD hh:mm:ss.sssss
    , where the number of decimal digits is arbitrary.
end_tsc
Event end timestamp.
pid
Process ID, provided optionally. Absence of a value in this field does not affect how a result is imported except for extremely rare cases when the following conditions are all met:
  • Thread ID is reused by the operating system within the collection time frame.
  • Different threads with the same thread ID generate records for the
    csv
     file.
  • Timestamps are inaccurate and data may be attributed to more than one thread with the same thread ID.
You may specify this field as an empty value within the data, or skip it from both file header and data entirely.
tid
Thread ID, provided optionally. If a value is specified in this field, the interval will be interpreted as a Task; otherwise, interval will be interpreted and shown as a Frame.
You may specify this field as an empty value within the data, or skip it from both file header and data entirely.

Format for Discrete Values

You can import two types of discrete values:
  • Cumulative data type (for example, distance, hardware event count), specified with the
    .COUNT
     suffix in the
    csv
     file
  • Instantaneous data type (for example, power consumption, temperature), specified with the
    .INST
     suffix in the
    csv
     file
The following format is required:
tsc.[QPC|CLOCK_MONOTONIC_RAW|RDTSC|UTC],
CounterName1
.COUNT|INST[,
CounterName2
.COUNT|INST],[pid],[tid]
Column Name
Description
tsc.[QPC|CLOCK_MONOTONIC_RAW|RDTSC|UTC]
Event start timestamp. This column has a
QPC|CLOCK_MONOTONIC_RAW
,
RDTSC
, or
UTC
 suffix that indicates the type of a timestamp counter:
  • Specify
    QPC
     (
    QueryPerformanceCounter
    ) on Windows* OS if the performance counter is used and specify
    CLOCK_MONOTONIC_RAW
     on Linux* OS if
    clock_gettime(CLOCK_MONOTONIC_RAW)
     is used.
  • Specify
    RDTSC
     if the RDTSC counter is used. Use
    __rdtsc()
     intrinsic to obtain RDTSC on Windows. To obtain RDTSC on Linux, copy the following function to your code and call it where necessary: 
    #include <stdint.h>
int64_t rdtsc()
{
    int64_t    tstamp;

#if defined(__x86_64__)
    asm(    "rdtsc\n\t"
            "shlq   $32,%%rdx\n\t"
            "or     %%rax,%%rdx\n\t"
            "movq   %%rdx,%0\n\t"
            : "=g"(tstamp)
            :
            : "rax", "rdx" );
#elif defined(__i386__)
    asm( "rdtsc\n", "=A"(tstamp) );
#else
#error NYI
#endif
    return tstamp;
}
  • Specify
    UTC
     if date and time is used. Expected format is
    YYYY-MM-DD hh:mm:ss.sssss
    , where the number of decimal digits is arbitrary.
CounterName1
Name of the event. Each counter has a separate column.
COUNT
 suffix is used to specify a cumulative counter value.
INST
 suffix is used to specify instantaneous counter values.
pid
Process ID, provided optionally. Absence of a value in this field does not affect how a result is imported except for extremely rare cases when the following conditions are all met:
  • Thread ID is reused by the operating system within the collection time frame.
  • Different threads with the same thread ID generate records for the
    csv
     file.
  • Timestamps are inaccurate and data may be attributed to more than one thread with the same thread ID.
You may specify this field as an empty value within the data, or skip it from both file header and data entirely.
tid
Thread ID, provided optionally. If a value is specified in this field, the interval will be interpreted as a Task; otherwise, interval will be interpreted and shown as a Frame.
You may specify this field as an empty value within the data, or skip it from both file header and data entirely.

Additional Requirements

  • Make sure each
    csv
     file contains only one table. If you need to load several tables, create several
    csv
     files with one table per file.
  • Use commas as value separators.
  • Use RDTSC, UTC or performance counter (
    QueryPerformanceCounter
     on Windows OS and
    CLOCK_MONOTONIC_RAW
     on Linux OS) to specify events timestamp.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.