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

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804