Implement Chromium tracing in SDK and some benchmark code under tests

.gitignore

@@ -32,4 +32,5 @@ lib/
 *.exe
 livekit.log
 web/
+*trace.json
 compile_commands.json

CMakeLists.txt

@@ -359,6 +359,12 @@ add_library(livekit SHARED
   src/remote_video_track.cpp
   src/video_utils.cpp
   src/video_utils.h
+  # Tracing support (Chrome trace format)
+  src/trace/event_tracer.cpp
+  src/trace/event_tracer.h
+  src/trace/event_tracer_internal.h
+  src/trace/trace_event.h
+  src/trace/tracing.cpp
 )
 if(WIN32)
   set_target_properties(livekit PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS ON)
@@ -373,6 +379,7 @@ target_include_directories(livekit
     $<INSTALL_INTERFACE:include>
   PRIVATE
     ${LIVEKIT_ROOT_DIR}/src
+    ${LIVEKIT_ROOT_DIR}/src/trace
     ${RUST_ROOT}/livekit-ffi/include
     ${PROTO_BINARY_DIR}
 )

README.md

@@ -327,6 +327,42 @@ and a **ROS2 bridge** that maps `LogLevel` to `RCLCPP_*` macros.
 
 ---
 
+## Tracing
+
+The SDK includes built-in support for [Chromium tracing](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool/), allowing you to capture detailed performance traces for debugging and optimization.
+
+### Basic Usage
+
+```cpp
+#include <livekit/livekit.h>
+
+// Start tracing to a file
+livekit::startTracing("trace.json");
+
+// ... run your application ...
+
+// Stop tracing and flush to file
+livekit::stopTracing();
+```
+
+### Filtering by Category
+
+You can optionally filter which categories to trace:
+
+```cpp
+// Trace only specific categories (supports wildcards)
+livekit::startTracing("trace.json", {"livekit.*", "webrtc.*"});
+```
+
+### Viewing Traces
+
+Open the generated trace file in one of these viewers:
+
+1. **Chrome**: Navigate to `chrome://tracing` and click "Load" to open the trace file
+2. **Perfetto**: Go to https://ui.perfetto.dev and drag-drop your trace file
+
+---
+
 ## 🧪 Integration & Stress Tests
 
 The SDK includes integration and stress tests using Google Test (gtest).

include/livekit/livekit.h

@@ -33,6 +33,7 @@
 #include "room.h"
 #include "room_delegate.h"
 #include "room_event_types.h"
+#include "tracing.h"
 #include "track_publication.h"
 #include "video_frame.h"
 #include "video_source.h"

include/livekit/tracing.h

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace livekit {
+
+/**
+ * Start tracing and write events to a file.
+ *
+ * Events are written to the file asynchronously by a background thread.
+ * The file is written in Chrome trace format (JSON), viewable in:
+ *   - Chrome: chrome://tracing
+ *   - Perfetto: https://ui.perfetto.dev
+ *
+ * @param trace_file_path Path to the output trace file (e.g., "trace.json")
+ * @param categories Categories to enable (empty = all categories).
+ *                   Supports wildcards: "livekit.*" matches all livekit
+ * categories.
+ * @return true if tracing was started, false if already running or file error
+ */
+bool startTracing(const std::string &trace_file_path,
+                  const std::vector<std::string> &categories = {});
+
+/**
+ * Stop tracing and flush remaining events to file.
+ *
+ * This blocks until all pending events are written and the file is closed.
+ * After stopping, the trace file is complete and ready for analysis.
+ */
+void stopTracing();
+
+/**
+ * Check if tracing is currently active.
+ *
+ * @return true if tracing is running
+ */
+bool isTracingEnabled();
+
+} // namespace livekit

src/room.cpp

@@ -36,6 +36,7 @@
 #include "livekit_ffi.h"
 #include "room.pb.h"
 #include "room_proto_converter.h"
+#include "trace/trace_event.h"
 #include "track.pb.h"
 #include "track_proto_converter.h"
 #include <functional>
@@ -107,6 +108,8 @@ void Room::setDelegate(RoomDelegate *delegate) {
 
 bool Room::Connect(const std::string &url, const std::string &token,
                    const RoomOptions &options) {
+  TRACE_EVENT0("livekit", "Room::Connect");
+
   {
     std::lock_guard<std::mutex> g(lock_);
     if (connection_state_ != ConnectionState::Disconnected) {

src/tests/CMakeLists.txt

@@ -24,17 +24,28 @@ FetchContent_MakeAvailable(googletest)
 enable_testing()
 include(GoogleTest)
 
+# ============================================================================
+# Benchmark Utilities (shared by all test types)
+# ============================================================================
+
+set(BENCHMARK_UTILS_SOURCES
+  "${CMAKE_CURRENT_SOURCE_DIR}/benchmark/benchmark_utils.cpp"
+  "${CMAKE_CURRENT_SOURCE_DIR}/benchmark/benchmark_utils.h"
+)
+
 # ============================================================================
 # Unit Tests
 # ============================================================================
 
+# Collect all unit test sources
 file(GLOB UNIT_TEST_SOURCES
   "${CMAKE_CURRENT_SOURCE_DIR}/unit/*.cpp"
 )
 
 if(UNIT_TEST_SOURCES)
   add_executable(livekit_unit_tests
     ${UNIT_TEST_SOURCES}
+    ${BENCHMARK_UTILS_SOURCES}
   )
 
   target_link_libraries(livekit_unit_tests
@@ -49,6 +60,8 @@ if(UNIT_TEST_SOURCES)
     PRIVATE
       ${LIVEKIT_ROOT_DIR}/include
       ${LIVEKIT_ROOT_DIR}/src
+      ${LIVEKIT_ROOT_DIR}/src/trace
+      ${CMAKE_CURRENT_SOURCE_DIR}/benchmark
   )
 
   target_compile_definitions(livekit_unit_tests
@@ -59,6 +72,7 @@ if(UNIT_TEST_SOURCES)
       $<$<PLATFORM_ID:Windows>:_USE_MATH_DEFINES>
   )
 
+  # Copy shared libraries to test executable directory
   if(WIN32)
     add_custom_command(TARGET livekit_unit_tests POST_BUILD
       COMMAND ${CMAKE_COMMAND} -E copy_if_different
@@ -91,6 +105,7 @@ if(UNIT_TEST_SOURCES)
     )
   endif()
 
+  # Register tests with CTest
   gtest_discover_tests(livekit_unit_tests
     WORKING_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}
     DISCOVERY_MODE PRE_TEST
@@ -111,6 +126,7 @@ file(GLOB INTEGRATION_TEST_SOURCES
 if(INTEGRATION_TEST_SOURCES)
   add_executable(livekit_integration_tests
     ${INTEGRATION_TEST_SOURCES}
+    ${BENCHMARK_UTILS_SOURCES}
   )
 
   # On Windows, protobuf default-instance symbols (constinit globals) are not
@@ -133,6 +149,7 @@ if(INTEGRATION_TEST_SOURCES)
     PRIVATE
       ${LIVEKIT_ROOT_DIR}/include
       ${LIVEKIT_ROOT_DIR}/src
+      ${CMAKE_CURRENT_SOURCE_DIR}/benchmark
       ${LIVEKIT_BINARY_DIR}/generated
       ${Protobuf_INCLUDE_DIRS}
   )
@@ -207,6 +224,7 @@ file(GLOB STRESS_TEST_SOURCES
 if(STRESS_TEST_SOURCES)
   add_executable(livekit_stress_tests
     ${STRESS_TEST_SOURCES}
+    ${BENCHMARK_UTILS_SOURCES}
   )
 
   target_link_libraries(livekit_stress_tests
@@ -220,6 +238,7 @@ if(STRESS_TEST_SOURCES)
     PRIVATE
       ${LIVEKIT_ROOT_DIR}/include
       ${LIVEKIT_ROOT_DIR}/src
+      ${CMAKE_CURRENT_SOURCE_DIR}/benchmark
   )
 
   target_compile_definitions(livekit_stress_tests