Create a CSV File with External Data

User Guide

Intel® VTune™ Profiler User Guide

Download PDF

ID 766319

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-142D14A8-25DC-4595-910B-ED40DEC393E8

View Details

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:

Interval data with start time and end time
Samples with a set of counters

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 vtunesummary report: vtune -r <result> -R summary.

Example:phases-hostname-octagon53.csv

NOTE:

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.

Examples

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:

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.

Examples

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.

Parent topic: Import External Data

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® VTune™ Profiler User Guide

Create a CSV File with External Data

File Name

Format for Interval Values

Format for Discrete Values

Additional Requirements

See Also