From f4a8ce83170031437185f721f0ceec15c18beb79 Mon Sep 17 00:00:00 2001 From: "Kireev, Alexey" Date: Tue, 23 Sep 2025 00:59:35 +0200 Subject: [PATCH 1/5] initial add of formatted metadata api documentation --- docs/src/ittapi/formatted-metadata-api.rst | 113 +++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/src/ittapi/formatted-metadata-api.rst diff --git a/docs/src/ittapi/formatted-metadata-api.rst b/docs/src/ittapi/formatted-metadata-api.rst new file mode 100644 index 0000000..d5713e1 --- /dev/null +++ b/docs/src/ittapi/formatted-metadata-api.rst @@ -0,0 +1,113 @@ +.. _formatted-metadata-api: + +Formatted Metadata API +====================== + + +Use the Formatted Metadata API to attach formatted string data to tasks with efficient string +formatting capabilities. This API extends the basic Metadata API by providing printf-style formatting functionality. + +The Formatted Metadata API is a per-thread function that works in the resumed profiling state only. + + +API Functions +------------- + +**To add formatted metadata to the current task, use the following primitive:** + +.. code-block:: cpp + + void __itt_formatted_metadata_add(const __itt_domain *domain, + __itt_string_handle *format_handle, + ...); + + +**Parameters of the primitive:** + ++--------+------------------------------+----------------------------------------------------+ +| Type | Parameter | Description | ++========+==============================+====================================================+ +| [in] | .. code-block:: cpp | Metadata domain | +| | | | +| | __itt_domain* domain | | ++--------+------------------------------+----------------------------------------------------+ +| [in] | .. code-block:: cpp | String handle containing the format string with | +| | | printf-style format specifiers | +| | __itt_string_handle* | | +| | format_handle | | ++--------+------------------------------+----------------------------------------------------+ +| [in] | .. code-block:: cpp | Variable arguments corresponding to format | +| | | specifiers in the format string | +| | ... | | ++--------+------------------------------+----------------------------------------------------+ + + +Metadata Visualization and Analysis in VTune +-------------------------------------------- + +Formatted metadata provides several benefits for visualization and analysis in Intel® VTune™ Profiler: + +- **Timeline tooltips**: Metadata appears in tooltips when hovering over tasks in the timeline view, + providing contextual runtime information. +- **Bottom-up view grouping**: Formatted metadata can be used as a grouping criteria in the bottom-up view, + allowing you to organize and analyze tasks based on their metadata values. +- **Custom grouping**: Users can group tasks by their metadata values to identify patterns and performance + characteristics across different execution contexts. +- **Square bracket notation for format specifiers**: When you include format specifiers in square brackets + (e.g., ``[%s]``) within your format string, VTune treats these as special grouping identifiers. + + +Usage Example +------------- + +.. code-block:: cpp + + #include "ittnotify.h" + + __itt_domain* domain = __itt_domain_create("FileProcessor"); + __itt_string_handle* operation_format = __itt_string_handle_create("Operation: [%s] on file %s"); + __itt_string_handle* performance_format = __itt_string_handle_create("Performance: %d bytes in %.2f ms"); + + void process_file(const char* filename) { + __itt_task_begin(domain, __itt_null, __itt_null, __itt_string_handle_create("process_file")); + + __itt_formatted_metadata_add(domain, operation_format, "file_processing", filename); + + __itt_task_begin(domain, __itt_null, __itt_null, __itt_string_handle_create("read_file")); + + int bytes_read = 1024; + double read_time = 15.5; + __itt_formatted_metadata_add(domain, performance_format, bytes_read, read_time); + + __itt_task_end(domain); + + __itt_task_begin(domain, __itt_null, __itt_null, __itt_string_handle_create("transform_data")); + + __itt_formatted_metadata_add(domain, operation_format, "data_transform", filename); + + __itt_task_end(domain); + __itt_task_end(domain); + } + + int main() { + process_file("document.txt"); + process_file("image.jpg"); + return 0; + } + + +Usage Guidelines +---------------- + +- Format strings support standard printf-style format specifiers (``%s``, ``%d``, ``%f``, etc.) +- Metadata is associated with the currently running task at the time of the API call +- **Limit to one metadata call per task** - making multiple calls to ``__itt_formatted_metadata_add`` for the same task may result in incorrect processing +- For optimal performance, limit the frequency and size of metadata additions +- Format specifiers in square brackets (e.g., ``[%s]``) create additional grouping options in VTune analysis views +- Function arguments are processed during the API calls +- Maximum length of a string argument is 256 symbols + + +.. note:: + + The Formatted Metadata API works starting with VTune 2025.7 release. \ No newline at end of file From 378915ad9b4e79af18655a0feb0b74f02c23ea88 Mon Sep 17 00:00:00 2001 From: "Kireev, Alexey" Date: Tue, 23 Sep 2025 16:33:19 +0200 Subject: [PATCH 2/5] add formatted metadata reference to task api page --- docs/src/itt-api-reference.rst | 1 + docs/src/ittapi/formatted-metadata-api.rst | 4 ---- docs/src/ittapi/task-api.rst | 4 ++++ 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/src/itt-api-reference.rst b/docs/src/itt-api-reference.rst index d65236b..7f3a367 100644 --- a/docs/src/itt-api-reference.rst +++ b/docs/src/itt-api-reference.rst @@ -13,6 +13,7 @@ ITT API Reference ittapi/counter-api ittapi/domain-api ittapi/event-api + ittapi/formatted-metadata-api ittapi/frame-api ittapi/histogram-api ittapi/load-module-api diff --git a/docs/src/ittapi/formatted-metadata-api.rst b/docs/src/ittapi/formatted-metadata-api.rst index d5713e1..a938527 100644 --- a/docs/src/ittapi/formatted-metadata-api.rst +++ b/docs/src/ittapi/formatted-metadata-api.rst @@ -107,7 +107,3 @@ Usage Guidelines - Function arguments are processed during the API calls - Maximum length of a string argument is 256 symbols - -.. note:: - - The Formatted Metadata API works starting with VTune 2025.7 release. \ No newline at end of file diff --git a/docs/src/ittapi/task-api.rst b/docs/src/ittapi/task-api.rst index a208ec8..7506bb7 100644 --- a/docs/src/ittapi/task-api.rst +++ b/docs/src/ittapi/task-api.rst @@ -21,6 +21,10 @@ A task instance represents a piece of work performed by a particular thread for a period of time. The task is defined by the bracketing of ``__itt_task_begin()`` and ``__itt_task_end()`` on the same thread. +You can enhance task representation by adding formatted metadata to tasks using +the `Formatted Metadata API `__. This allows you to attach contextual +information with printf-style formatting that appears in VTune analysis views. + Tasks can be simple or overlapped. From 5f04836afbe0debba04c07aa4c6d5dbdec7d2fcb Mon Sep 17 00:00:00 2001 From: "Kireev, Alexey" Date: Thu, 25 Sep 2025 02:24:56 +0200 Subject: [PATCH 3/5] small naming fix --- docs/src/ittapi/formatted-metadata-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/ittapi/formatted-metadata-api.rst b/docs/src/ittapi/formatted-metadata-api.rst index a938527..2cf751c 100644 --- a/docs/src/ittapi/formatted-metadata-api.rst +++ b/docs/src/ittapi/formatted-metadata-api.rst @@ -42,7 +42,7 @@ API Functions +--------+------------------------------+----------------------------------------------------+ -Metadata Visualization and Analysis in VTune +Metadata Visualization and Analysis -------------------------------------------- Formatted metadata provides several benefits for visualization and analysis in Intel® VTune™ Profiler: From 242676b4d0c6254c7efa245234d2272638971127 Mon Sep 17 00:00:00 2001 From: Alexey Kireev Date: Thu, 25 Sep 2025 11:50:50 +0200 Subject: [PATCH 4/5] Update docs/src/ittapi/formatted-metadata-api.rst Co-authored-by: Evgeny Parshutin --- docs/src/ittapi/formatted-metadata-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/ittapi/formatted-metadata-api.rst b/docs/src/ittapi/formatted-metadata-api.rst index 2cf751c..5731620 100644 --- a/docs/src/ittapi/formatted-metadata-api.rst +++ b/docs/src/ittapi/formatted-metadata-api.rst @@ -43,7 +43,7 @@ API Functions Metadata Visualization and Analysis --------------------------------------------- +----------------------------------- Formatted metadata provides several benefits for visualization and analysis in Intel® VTune™ Profiler: From 6efda738d5a26ea4a0b9e23726440ad8831840c9 Mon Sep 17 00:00:00 2001 From: "Kireev, Alexey" Date: Thu, 25 Sep 2025 15:17:10 +0200 Subject: [PATCH 5/5] add documentation for formatted metadata in overlapped tasks --- docs/src/ittapi/formatted-metadata-api.rst | 38 +++++++++++++++------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/src/ittapi/formatted-metadata-api.rst b/docs/src/ittapi/formatted-metadata-api.rst index 5731620..1e1385c 100644 --- a/docs/src/ittapi/formatted-metadata-api.rst +++ b/docs/src/ittapi/formatted-metadata-api.rst @@ -21,6 +21,15 @@ API Functions __itt_string_handle *format_handle, ...); +**To add formatted metadata to an overlapped task, use the following primitive:** + +.. code-block:: cpp + + void __itt_formatted_metadata_add_overlapped(const __itt_domain *domain, + __itt_id taskid, + __itt_string_handle *format_handle, + ...); + **Parameters of the primitive:** @@ -31,6 +40,10 @@ API Functions | | | | | | __itt_domain* domain | | +--------+------------------------------+----------------------------------------------------+ +| [in] | .. code-block:: cpp | Task ID (required for overlapped variant only) | +| | | | +| | __itt_id taskid | | ++--------+------------------------------+----------------------------------------------------+ | [in] | .. code-block:: cpp | String handle containing the format string with | | | | printf-style format specifiers | | | __itt_string_handle* | | @@ -57,6 +70,19 @@ Formatted metadata provides several benefits for visualization and analysis in I (e.g., ``[%s]``) within your format string, VTune treats these as special grouping identifiers. +Usage Guidelines +---------------- + +- **Supported format specifiers:** ``%s``, ``%ls``, ``%d``, ``%u``, ``%hd``, ``%hu``, ``%ld``, ``%lu``, ``%lld``, ``%llu``, ``%f``, ``%lf`` +- **Regular tasks:** Use ``__itt_formatted_metadata_add`` for metadata associated with the currently running task +- **Overlapped tasks:** Use ``__itt_formatted_metadata_add_overlapped`` with a specific task ID for overlapped task instances +- **Limit to one metadata call per task** - making multiple calls to ``__itt_formatted_metadata_add`` for the same task may result in incorrect processing +- For optimal performance, limit the frequency and size of metadata additions +- Format specifiers in square brackets (e.g., ``[%s]``) create additional grouping options in VTune analysis views +- Function arguments are processed during the API calls +- Maximum length of a string argument is 256 symbols + + Usage Example ------------- @@ -95,15 +121,3 @@ Usage Example return 0; } - -Usage Guidelines ----------------- - -- Format strings support standard printf-style format specifiers (``%s``, ``%d``, ``%f``, etc.) -- Metadata is associated with the currently running task at the time of the API call -- **Limit to one metadata call per task** - making multiple calls to ``__itt_formatted_metadata_add`` for the same task may result in incorrect processing -- For optimal performance, limit the frequency and size of metadata additions -- Format specifiers in square brackets (e.g., ``[%s]``) create additional grouping options in VTune analysis views -- Function arguments are processed during the API calls -- Maximum length of a string argument is 256 symbols -