Skip to content

Commit e8a6e76

Browse files
alexey-kireeveparshut
alexey-kireev
and
eparshut
authored
doc: add Formatted Metadata API documentation (#185)
* initial add of formatted metadata api documentation * add formatted metadata reference to task api page * small naming fix * Update docs/src/ittapi/formatted-metadata-api.rst * add documentation for formatted metadata in overlapped tasks --------- Co-authored-by: Evgeny Parshutin <eugeny.parshutin@intel.com>
1 parent ca45fef commit e8a6e76

File tree

3 files changed

+128
-0
lines changed

3 files changed

+128
-0
lines changed

‎docs/src/itt-api-reference.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ ITT API Reference
1313
ittapi/counter-api
1414
ittapi/domain-api
1515
ittapi/event-api
16+
ittapi/formatted-metadata-api
1617
ittapi/frame-api
1718
ittapi/histogram-api
1819
ittapi/load-module-api

‎docs/src/ittapi/formatted-metadata-api.rst‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _formatted-metadata-api:
2+
3+
Formatted Metadata API
4+
======================
5+
6+
7+
Use the Formatted Metadata API to attach formatted string data to tasks with efficient string
8+
formatting capabilities. This API extends the basic Metadata API by providing printf-style formatting functionality.
9+
10+
The Formatted Metadata API is a per-thread function that works in the resumed profiling state only.
11+
12+
13+
API Functions
14+
-------------
15+
16+
**To add formatted metadata to the current task, use the following primitive:**
17+
18+
.. code-block:: cpp
19+
20+
void __itt_formatted_metadata_add(const __itt_domain *domain,
21+
__itt_string_handle *format_handle,
22+
...);
23+
24+
**To add formatted metadata to an overlapped task, use the following primitive:**
25+
26+
.. code-block:: cpp
27+
28+
void __itt_formatted_metadata_add_overlapped(const __itt_domain *domain,
29+
__itt_id taskid,
30+
__itt_string_handle *format_handle,
31+
...);
32+
33+
34+
**Parameters of the primitive:**
35+
36+
+--------+------------------------------+----------------------------------------------------+
37+
| Type | Parameter | Description |
38+
+========+==============================+====================================================+
39+
| [in] | .. code-block:: cpp | Metadata domain |
40+
| | | |
41+
| | __itt_domain* domain | |
42+
+--------+------------------------------+----------------------------------------------------+
43+
| [in] | .. code-block:: cpp | Task ID (required for overlapped variant only) |
44+
| | | |
45+
| | __itt_id taskid | |
46+
+--------+------------------------------+----------------------------------------------------+
47+
| [in] | .. code-block:: cpp | String handle containing the format string with |
48+
| | | printf-style format specifiers |
49+
| | __itt_string_handle* | |
50+
| | format_handle | |
51+
+--------+------------------------------+----------------------------------------------------+
52+
| [in] | .. code-block:: cpp | Variable arguments corresponding to format |
53+
| | | specifiers in the format string |
54+
| | ... | |
55+
+--------+------------------------------+----------------------------------------------------+
56+
57+
58+
Metadata Visualization and Analysis
59+
-----------------------------------
60+
61+
Formatted metadata provides several benefits for visualization and analysis in Intel® VTune™ Profiler:
62+
63+
- **Timeline tooltips**: Metadata appears in tooltips when hovering over tasks in the timeline view,
64+
providing contextual runtime information.
65+
- **Bottom-up view grouping**: Formatted metadata can be used as a grouping criteria in the bottom-up view,
66+
allowing you to organize and analyze tasks based on their metadata values.
67+
- **Custom grouping**: Users can group tasks by their metadata values to identify patterns and performance
68+
characteristics across different execution contexts.
69+
- **Square bracket notation for format specifiers**: When you include format specifiers in square brackets
70+
(e.g., ``[%s]``) within your format string, VTune treats these as special grouping identifiers.
71+
72+
73+
Usage Guidelines
74+
----------------
75+
76+
- **Supported format specifiers:** ``%s``, ``%ls``, ``%d``, ``%u``, ``%hd``, ``%hu``, ``%ld``, ``%lu``, ``%lld``, ``%llu``, ``%f``, ``%lf``
77+
- **Regular tasks:** Use ``__itt_formatted_metadata_add`` for metadata associated with the currently running task
78+
- **Overlapped tasks:** Use ``__itt_formatted_metadata_add_overlapped`` with a specific task ID for overlapped task instances
79+
- **Limit to one metadata call per task** - making multiple calls to ``__itt_formatted_metadata_add`` for the same task may result in incorrect processing
80+
- For optimal performance, limit the frequency and size of metadata additions
81+
- Format specifiers in square brackets (e.g., ``[%s]``) create additional grouping options in VTune analysis views
82+
- Function arguments are processed during the API calls
83+
- Maximum length of a string argument is 256 symbols
84+
85+
86+
Usage Example
87+
-------------
88+
89+
.. code-block:: cpp
90+
91+
#include "ittnotify.h"
92+
93+
__itt_domain* domain = __itt_domain_create("FileProcessor");
94+
__itt_string_handle* operation_format = __itt_string_handle_create("Operation: [%s] on file %s");
95+
__itt_string_handle* performance_format = __itt_string_handle_create("Performance: %d bytes in %.2f ms");
96+
97+
void process_file(const char* filename) {
98+
__itt_task_begin(domain, __itt_null, __itt_null, __itt_string_handle_create("process_file"));
99+
100+
__itt_formatted_metadata_add(domain, operation_format, "file_processing", filename);
101+
102+
__itt_task_begin(domain, __itt_null, __itt_null, __itt_string_handle_create("read_file"));
103+
104+
int bytes_read = 1024;
105+
double read_time = 15.5;
106+
__itt_formatted_metadata_add(domain, performance_format, bytes_read, read_time);
107+
108+
__itt_task_end(domain);
109+
110+
__itt_task_begin(domain, __itt_null, __itt_null, __itt_string_handle_create("transform_data"));
111+
112+
__itt_formatted_metadata_add(domain, operation_format, "data_transform", filename);
113+
114+
__itt_task_end(domain);
115+
__itt_task_end(domain);
116+
}
117+
118+
int main() {
119+
process_file("document.txt");
120+
process_file("image.jpg");
121+
return 0;
122+
}
123+

‎docs/src/ittapi/task-api.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ A task instance represents a piece of work performed by a particular
2121
thread for a period of time. The task is defined by the bracketing of
2222
``__itt_task_begin()`` and ``__itt_task_end()`` on the same thread.
2323

24+
You can enhance task representation by adding formatted metadata to tasks using
25+
the `Formatted Metadata API <formatted-metadata-api.html>`__. This allows you to attach contextual
26+
information with printf-style formatting that appears in VTune analysis views.
27+
2428

2529
Tasks can be simple or overlapped.
2630

0 commit comments

Comments
 (0)