refcol: add JSON trace output mode to the ITT API reference collector

docs/src/ref_collector.rst

@@ -59,14 +59,6 @@ library you built above (adjust the path to your build directory).
     export INTEL_LIBITTNOTIFY64=<build_dir>/libittnotify_refcol.so
 
 
-**On FreeBSD**
-
-
-.. code-block:: bash
-
-    setenv INTEL_LIBITTNOTIFY64 <build_dir>/libittnotify_refcol.so
-
-
 **On Windows**
 
 
@@ -78,7 +70,7 @@ library you built above (adjust the path to your build directory).
 Log File Location
 -----------------
 
-By default, log files are saved in the system temporary directory. Each run
+By default, log files are saved in the current working directory. Each run
 creates a file named ``libittnotify_refcol_<timestamp>.log``. To change the
 location, use the ``INTEL_LIBITTNOTIFY_LOG_DIR`` environment variable:
 
@@ -91,14 +83,6 @@ location, use the ``INTEL_LIBITTNOTIFY_LOG_DIR`` environment variable:
     export INTEL_LIBITTNOTIFY_LOG_DIR=<log_dir>
 
 
-**On FreeBSD**
-
-
-.. code-block:: bash
-
-    setenv INTEL_LIBITTNOTIFY_LOG_DIR <log_dir>
-
-
 **On Windows**
 
 
@@ -121,3 +105,32 @@ functions with different log levels that take `printf` format for logging:
     LOG_FUNC_CALL_ERROR(const char *msg_format, ...);
     LOG_FUNC_CALL_FATAL(const char *msg_format, ...);
 
+
+Experimental: JSON trace generation
+------------------------------------
+
+In addition to the default text log, the collector can produce a trace in
+JSON format (Perfetto). This mode is experimental and is disabled by default.
+
+To enable it, set the ``EXP_LIBITTNOTIFY_GEN_JSON`` environment variable to ``1``:
+
+**On Linux**
+
+
+.. code-block:: bash
+
+    export EXP_LIBITTNOTIFY_GEN_JSON=1
+
+
+**On Windows**
+
+
+.. code-block:: bat
+
+    set EXP_LIBITTNOTIFY_GEN_JSON=1
+
+
+When enabled, the collector writes a ``libittnotify_refcol_<timestamp>.json``
+file (instead of the text log) into the log directory. The file can be opened
+directly in https://ui.perfetto.dev.
+

src/ittnotify_refcol/README.md

@@ -42,19 +42,13 @@ library you built above (adjust the path to your build directory).
 export INTEL_LIBITTNOTIFY64=<build_dir>/libittnotify_refcol.so
 ```
 
-**On FreeBSD**
-
-```
-setenv INTEL_LIBITTNOTIFY64 <build_dir>/libittnotify_refcol.so
-```
-
 **On Windows**
 
 ```
 set INTEL_LIBITTNOTIFY64=<build_dir>\libittnotify_refcol.dll
 ```
 
-By default, log files are saved in the system temporary directory. To change
+By default, log files are saved in the current working directory. To change
 the location, use the `INTEL_LIBITTNOTIFY_LOG_DIR` environment variable:
 
 **On Linux**
@@ -63,11 +57,6 @@ the location, use the `INTEL_LIBITTNOTIFY_LOG_DIR` environment variable:
 export INTEL_LIBITTNOTIFY_LOG_DIR=<log_dir>
 ```
 
-**On FreeBSD**
-```
-setenv INTEL_LIBITTNOTIFY_LOG_DIR <log_dir>
-```
-
 **On Windows**
 ```
 set INTEL_LIBITTNOTIFY_LOG_DIR=<log_dir>
@@ -83,3 +72,27 @@ LOG_FUNC_CALL_WARN(const char *msg_format, ...);
 LOG_FUNC_CALL_ERROR(const char *msg_format, ...);
 LOG_FUNC_CALL_FATAL(const char *msg_format, ...);
 ```
+
+## Experimental: JSON trace generation
+
+In addition to the default text log, the collector can produce a trace in
+JSON format (Perfetto).
+This mode is experimental and is disabled by default.
+
+To enable it, set the `EXP_LIBITTNOTIFY_GEN_JSON` environment variable to `1`:
+
+**On Linux**
+
+```
+export EXP_LIBITTNOTIFY_GEN_JSON=1
+```
+
+**On Windows**
+
+```
+set EXP_LIBITTNOTIFY_GEN_JSON=1
+```
+
+When enabled, the collector writes a `libittnotify_refcol_<timestamp>.json` file
+(instead of the text log) into the log directory. The file can be opened
+directly in <https://ui.perfetto.dev>.