1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
# Elevated Tracing Service
[TOC]
## About
The elevated tracing service is a Windows service that consumes system-wide ETW
events and produces corresponding perfetto trace events.
## Installation
The tracing service is not registered for use by default. It is supported only
on per-machine (system-level) installs of Chrome. The service can be installed
manually by running one of the following commands (depending on which channel of
Chrome is installed) from an elevated cmd prompt:
- `"%ProgramFiles%\Google\Chrome Dev\Application\W.X.Y.Z\Installer\setup.exe" --chrome-dev --system-level --enable-system-tracing`
- `"%ProgramFiles%\Google\Chrome Beta\Application\W.X.Y.Z\Installer\setup.exe" --chrome-beta --system-level --enable-system-tracing`
- `"%ProgramFiles%\Google\Chrome\Application\W.X.Y.Z\Installer\setup.exe" --system-level --enable-system-tracing`
In each case, replace `W.X.Y.Z` with the true version installed. Installation
persists across Chrome browser updates, so this command need only be run once on
a given computer. The service can be uninstalled by running the same command,
but with `--disable-system-tracing` in place of `--enable-system-tracing`.
When the service is registered and the `WindowsSystemTracing` feature is enabled
(e.g., via `--enable-features=WindowsSystemTracing` on the command line), Chrome
will start the elevated tracing service alongside the browser's tracing service
utility process (e.g., the first time a trace is recorded via
https://ui.perfetto.dev). The service will remain running until either the
browser process or the browser's tracing service utility process terminates.
### For developers
Developers can enable the tracing service for a local build by running the
following command from an elevated cmd prompt: `out\Default\setup.exe
--developer --enable-system-tracing`. As above, use `--developer
--disable-system-tracing` to uninstall the service.
*** note
**Caution:** This will likely break tracing for a normal installation of the
same browser (e.g., stable Google Chrome if running a branded build), and may be
overwritten by an update of the same browser.
***
## Process lifecycle
The service process is started automatically when Chrome creates an instance of
the `SystemTracingSession` COM class. Clients are refused an instance of the
class if one is already active in the service. The service terminates when
either the active instance is destroyed (on account of its client releasing all
references) or if the client process terminates. Chrome is expected to hold a
reference to the session instance for as long as ETW trace events are desired.
## Session activation
A session becomes active via a multi-step negotiation.
1. Chrome creates an instance of `SystemTracingSession`.
2. Chrome creates a named mojo channel to establish a connection with the
service and passes its name to the session's `AcceptInvitation()` method.
3. The service begins monitoring the client (Chrome) for termination, connects
to the named channel to accept the invitation from it, and returns its PID to
the client.
4. Chrome sends a mojo invitation with an initial message pipe (named `0`) over
the channel to the service.
5. The service takes its end of the message pipe from the invitation, wraps it
in a `PendingReceiver<tracing::mojom::TracedProcess>`, and passes it to the
service's `tracing::TracedProcess` instance.
6. Chrome wraps its end of the initial message pipe in a `PendingRemote<...>`
and passes it to the perfetto tracing service running in a utility process.
|
