Implement Chromium tracing in SDK and some benchmark code under tests by xianshijing-lk · Pull Request #85 · livekit/client-sdk-cpp

xianshijing-lk · 2026-04-03T21:17:50Z

Summary

Add Chrome trace format implementation with background file writer for performance profiling
Add benchmark utilities for analyzing trace files in tests
Add comprehensive unit tests for tracing system

Description

This PR introduces a tracing infrastructure based on Chrome's trace event format, enabling performance profiling and latency measurement across the LiveKit C++ SDK.

Tracing Implementation

The tracing system provides:

Background file writer: Events are queued and written asynchronously by a dedicated thread, minimizing latency impact on the main code path
Chrome trace format: Output is compatible with chrome://tracing and https://ui.perfetto.dev for visualization
Category filtering: Support for enabling specific trace categories with wildcard matching (e.g., livekit.*)
Cross-platform support: Works on Windows, macOS, and Linux

See tests traces examples in the screen shoot

Public API (include/livekit/tracing.h):
bool startTracing(const std::string& trace_file_path,
const std::vectorstd::string& categories = {});
void stopTracing();
bool isTracingEnabled();

Benchmark Utilities

New utilities in src/tests/benchmark/ for test instrumentation:

Trace file parsing: Load and parse Chrome trace JSON files
Duration calculation: Pair begin/end events (scoped B/E and async S/F)
Statistics: Calculate min, max, avg, p50, p95, p99 percentiles
BenchmarkSession: RAII wrapper for managing trace sessions in tests
TracedStressStats: Thread-safe statistics collector for stress tests

Unit Tests

17 unit tests covering:

Tracing lifecycle (start/stop, error handling)
Event writing (scoped, async, with arguments)
Category filtering and wildcard matching
Trace file parsing and analysis
Multiple sessions and thread safety

Test Plan

Unit tests pass on macOS: ./build.sh release-tests && ./build-release/bin/livekit_unit_tests
Unit tests pass on Linux: ./build.sh release-tests
Unit tests pass on Windows: build.cmd release-tests
Verify trace output opens in chrome://tracing or Perfetto UI

Tracing

stephen-derosa

Thanks for implementing this looks great! Definitely double check copyright year on new files.

Also, I ran the utests locally but i wasn't able to find the trace jsons. I would have thought they'd be in /tmp/ based on this line but i dont see them there or in my client-sdk-cpp repo

stephen-derosa · 2026-04-06T17:07:28Z

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2024 LiveKit


Good catch, done with changing it to 2026 on all the relevant files.

still says 2024?

Sorry, I missed this file, now it should be fixed.

xianshijing-lk · 2026-04-13T19:40:52Z

Thanks for implementing this looks great! Definitely double check copyright year on new files.

Also, I ran the utests locally but i wasn't able to find the trace jsons. I would have thought they'd be in /tmp/ based on this line but i dont see them there or in my client-sdk-cpp repo

It is under the folder where you run the tests.

For instance, if you are running the tests like ./build-release/bin/livekit_integration_tests, it will be in your repo root folder, and I git ignore them to avoid corrupting the workspace.

…hmark_foundation

xianshijing-lk · 2026-04-14T16:01:08Z

@stephen-derosa could you please take another look ?

stephen-derosa

will applications have the ability to turn tracing on? if so, will there be an associated tracing example?

In general looks good to me! One comment about date and one about including in livekit.h

stephen-derosa · 2026-04-14T21:36:29Z

 #include "room.h"
 #include "room_delegate.h"
 #include "room_event_types.h"
+#include "tracing.h"


what is the reason for including this here if it doesnt get used?

looks like its private?
https://github.com/livekit/client-sdk-cpp/pull/85/changes#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aR382

The APIs at tracing.h is public:
bool startTracing(const std::string &trace_file_path,
const std::vectorstd::string &categories = {});
void stopTracing();
bool isTracingEnabled();

Developers can start / stop tracing based on their needs, by default it is stopped.

stephen-derosa · 2026-04-14T21:36:53Z

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2024 LiveKit


still says 2024?

stephen-derosa · 2026-04-14T21:39:42Z

great this should be useful in the cpp throughput tests

xianshijing-lk · 2026-04-14T22:13:15Z

will applications have the ability to turn tracing on? if so, will there be an associated tracing example?

In general looks good to me! One comment about date and one about including in livekit.h

Yes, that public interface is at tracing.h, they can call startTracing(const std::string &trace_file_path); to turn the tracing on.

All the tests now enable the tracing, and also it has its own unit tests.
If you want, I can update our examples to turn on the tracing. And I don't see the needs to have a dedicated example for tracing, as it is a debugging feature for our SDK.

stephen-derosa · 2026-04-14T22:24:00Z

will applications have the ability to turn tracing on? if so, will there be an associated tracing example?
In general looks good to me! One comment about date and one about including in livekit.h

Yes, that public interface is at tracing.h, they can call startTracing(const std::string &trace_file_path); to turn the tracing on.

All the tests now enable the tracing, and also it has its own unit tests. If you want, I can update our examples to turn on the tracing. And I don't see the needs to have a dedicated example for tracing, as it is a debugging feature for our SDK.

no need to add an example then, maybe just a comment somewhere saying "to turn tracing on..."

xianshijing-lk · 2026-04-14T23:07:57Z

will applications have the ability to turn tracing on? if so, will there be an associated tracing example?
In general looks good to me! One comment about date and one about including in livekit.h

Yes, that public interface is at tracing.h, they can call startTracing(const std::string &trace_file_path); to turn the tracing on.
All the tests now enable the tracing, and also it has its own unit tests. If you want, I can update our examples to turn on the tracing. And I don't see the needs to have a dedicated example for tracing, as it is a debugging feature for our SDK.

no need to add an example then, maybe just a comment somewhere saying "to turn tracing on..."

Sounds good. I added a section in README.md to explain how to start / stop tracing.

BTW, I can't add the tracing to examples since we need to make a release first before changing the examples, otherwise things will break there.

…hmark_foundation

Implement Chromium tracing in SDK and some benchmark code under tests

57247c9

xianshijing-lk requested a review from stephen-derosa April 3, 2026 21:17

stephen-derosa reviewed Apr 6, 2026

View reviewed changes

Comment thread src/room.cpp

fix the license year

d9f591b

Merge branch 'main' into sxian/CLT-2717/add_chromium_tracing_and_benc…

73c93ba

…hmark_foundation

fix the windows build

a212358

xianshijing-lk requested a review from stephen-derosa April 14, 2026 20:12

stephen-derosa reviewed Apr 14, 2026

View reviewed changes

fix the year of copyright

8bf6e7f

stephen-derosa approved these changes Apr 14, 2026

View reviewed changes

added section in the readme

c7696d7

xianshijing-lk added 7 commits April 14, 2026 16:11

Merge branch 'main' into sxian/CLT-2717/add_chromium_tracing_and_benc…

a0fe327

…hmark_foundation

fix the rebase problem

8bbcc07

added the missing spdlog

90395bd

fix the build

c8aa3f3

another try to fix the windows build

3b798c0

recover some CMakelists.txt changes that get removed from rebasing

ba917fb

fix windows temp path

8d4caf9

xianshijing-lk merged commit 65b3869 into main Apr 16, 2026
13 of 14 checks passed

xianshijing-lk deleted the sxian/CLT-2717/add_chromium_tracing_and_benchmark_foundation branch April 16, 2026 02:22

Conversation

xianshijing-lk commented Apr 3, 2026

Uh oh!

stephen-derosa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xianshijing-lk commented Apr 13, 2026

Uh oh!

xianshijing-lk commented Apr 14, 2026

Uh oh!

stephen-derosa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xianshijing-lk commented Apr 14, 2026

Uh oh!

stephen-derosa commented Apr 14, 2026

Uh oh!

xianshijing-lk commented Apr 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants