docs: format several docs
Change-Id: I7e808501b26f37ec226d854190cecff21433d828
diff --git a/docs/concepts/config.md b/docs/concepts/config.md
index c4326e6..1badce4 100644
--- a/docs/concepts/config.md
+++ b/docs/concepts/config.md
@@ -4,11 +4,12 @@
in Perfetto all tracing data sources are idle by default and record data only
when instructed to do so.
-Data sources record data only when one (or more) tracing sessions are active.
-A tracing session is started by invoking the `perfetto` cmdline client and
-passing a config (see QuickStart guide for
+Data sources record data only when one (or more) tracing sessions are active. A
+tracing session is started by invoking the `perfetto` cmdline client and passing
+a config (see QuickStart guide for
[Android](/docs/quickstart/android-tracing.md),
-[Linux](/docs/quickstart/linux-tracing.md), or [Chrome on desktop](/docs/quickstart/chrome-tracing.md)).
+[Linux](/docs/quickstart/linux-tracing.md), or
+[Chrome on desktop](/docs/quickstart/chrome-tracing.md)).
A simple trace config looks like this:
@@ -31,7 +32,7 @@
}
}
-````
+```
And is used as follows:
@@ -43,7 +44,7 @@
[`/test/configs/`](/test/configs/).
NOTE: If you are tracing on Android using adb and experiencing problems, see
- [the Android section](#android) below.
+[the Android section](#android) below.
## TraceConfig
@@ -51,38 +52,40 @@
([reference docs](/docs/reference/trace-config-proto.autogen)) that defines:
1. The general behavior of the whole tracing system, e.g.:
- * The max duration of the trace.
- * The number of in-memory buffers and their size.
- * The max size of the output trace file.
+
+ - The max duration of the trace.
+ - The number of in-memory buffers and their size.
+ - The max size of the output trace file.
2. Which data sources to enable and their configuration, e.g.:
- * For the [kernel tracing data source](/docs/data-sources/cpu-scheduling.md)
- , which ftrace events to enable.
- * For the [heap profiler](/docs/data-sources/native-heap-profiler.md), the
- target process name and sampling rate.
-
- See the _data sources_ section of the docs for details on how to
- configure the data sources bundled with Perfetto.
-3. The `{data source} x {buffer}` mappings: which buffer each data
- source should write into (see [buffers section](#buffers) below).
+ - For the [kernel tracing data source](/docs/data-sources/cpu-scheduling.md)
+ , which ftrace events to enable.
+ - For the [heap profiler](/docs/data-sources/native-heap-profiler.md), the
+ target process name and sampling rate.
-The tracing service (`traced`) acts as a configuration dispatcher: it receives
-a config from the `perfetto` cmdline client (or any other
+ See the _data sources_ section of the docs for details on how to configure
+ the data sources bundled with Perfetto.
+
+3. The `{data source} x {buffer}` mappings: which buffer each data source should
+ write into (see [buffers section](#buffers) below).
+
+The tracing service (`traced`) acts as a configuration dispatcher: it receives a
+config from the `perfetto` cmdline client (or any other
[Consumer](/docs/concepts/service-model.md#consumer)) and forwards parts of the
config to the various [Producers](/docs/concepts/service-model.md#producer)
connected.
When a tracing session is started by a consumer, the tracing service will:
-* Read the outer section of the TraceConfig (e.g. `duration_ms`, `buffers`) and
+- Read the outer section of the TraceConfig (e.g. `duration_ms`, `buffers`) and
use that to determine its own behavior.
-* Read the list of data sources in the `data_sources` section. For each data
+- Read the list of data sources in the `data_sources` section. For each data
source listed in the config, if a corresponding name (`"linux.ftrace"` in the
example below) was registered, the service will ask the producer process to
- start that data source, passing it the raw bytes of the
- [`DataSourceConfig` subsection][dss] verbatim to the data source (See
- backward/forward compat section below).
+ start that data source, passing it the raw bytes of the [`DataSourceConfig`
+ subsection][dss] verbatim to the data source (See backward/forward compat
+ section below).
@@ -109,10 +112,10 @@
Each buffer has a fill policy which is either:
-* RING_BUFFER (default): the buffer behaves like a ring buffer and writes when
+- RING_BUFFER (default): the buffer behaves like a ring buffer and writes when
full will wrap over and replace the oldest trace data in the buffer.
-* DISCARD: the buffer stops accepting data once full. Further write attempts are
+- DISCARD: the buffer stops accepting data once full. Further write attempts are
dropped.
WARNING: DISCARD can have unexpected side-effect with data sources that commit
@@ -121,36 +124,34 @@
A trace config must define at least one buffer to be valid. In the simplest case
all data sources will write their trace data into the same buffer.
- While this is
-fine for most basic cases, it can be problematic in cases where different data
-sources write at significantly different rates.
+While this is fine for most basic cases, it can be problematic in cases where
+different data sources write at significantly different rates.
For instance, imagine a trace config that enables both:
-1. The kernel scheduler tracer. On a typical Android phone this records
- ~10000 events/second, writing ~1 MB/s of trace data into the buffer.
+1. The kernel scheduler tracer. On a typical Android phone this records ~10000
+ events/second, writing ~1 MB/s of trace data into the buffer.
2. Memory stat polling. This data source writes the contents of /proc/meminfo
- into the trace buffer and is configured to poll every 5 seconds, writing
- ~100 KB per poll interval.
+ into the trace buffer and is configured to poll every 5 seconds, writing ~100
+ KB per poll interval.
If both data sources are configured to write into the same buffer and such
buffer is set to 4MB, most traces will contain only one memory snapshot. There
are very good chances that most traces won't contain any memory snapshot at all,
-even if the 2nd data sources was working perfectly.
-This is because during the 5 s. polling interval, the scheduler data source can
-end up filling the whole buffer, pushing the memory snapshot data out of the
-buffer.
+even if the 2nd data sources was working perfectly. This is because during the 5
+s. polling interval, the scheduler data source can end up filling the whole
+buffer, pushing the memory snapshot data out of the buffer.
## Dynamic buffer mapping
-Data-source <> buffer mappings are dynamic in Perfetto.
-In the simplest case a tracing session can define only one buffer. By default,
-all data sources will record data into that one buffer.
+Data-source <> buffer mappings are dynamic in Perfetto. In the simplest case a
+tracing session can define only one buffer. By default, all data sources will
+record data into that one buffer.
In cases like the example above, it might be preferable separating these data
-sources into different buffers.
-This can be achieved with the `target_buffer` field of the TraceConfig.
+sources into different buffers. This can be achieved with the `target_buffer`
+field of the TraceConfig.
@@ -189,11 +190,11 @@
#### Text format
-It is the preferred format for human-driven workflows and exploration. It
-allows to pass directly the text file in the PBTX (ProtoBuf TeXtual
-representation) syntax, for the schema defined in the
-[trace_config.proto](/protos/perfetto/config/trace_config.proto)
-(see [reference docs](/docs/reference/trace-config-proto.autogen))
+It is the preferred format for human-driven workflows and exploration. It allows
+to pass directly the text file in the PBTX (ProtoBuf TeXtual representation)
+syntax, for the schema defined in the
+[trace_config.proto](/protos/perfetto/config/trace_config.proto) (see
+[reference docs](/docs/reference/trace-config-proto.autogen))
When using this mode pass the `--txt` flag to `perfetto` to indicate the config
should be interpreted as a PBTX file:
@@ -212,10 +213,9 @@
#### Binary format
It is the preferred format for machine-to-machine (M2M) interaction. It involves
-passing the protobuf-encoded binary of the TraceConfig message.
-This can be obtained passing the PBTX in input to the protobuf's `protoc`
-compiler (which can be downloaded
-[here](https://github.com/protocolbuffers/protobuf/releases)).
+passing the protobuf-encoded binary of the TraceConfig message. This can be
+obtained passing the PBTX in input to the protobuf's `protoc` compiler (which
+can be downloaded [here](https://github.com/protocolbuffers/protobuf/releases)).
```bash
cd ~/code/perfetto # external/perfetto in the Android tree.
@@ -236,9 +236,9 @@
By default Perfetto keeps the full trace buffer(s) in memory and writes it into
the destination file (the `-o` cmdline argument) only at the end of the tracing
-session. This is to reduce the perf-intrusiveness of the tracing system.
-This, however, limits the max size of the trace to the physical memory size of
-the device, which is often too limiting.
+session. This is to reduce the perf-intrusiveness of the tracing system. This,
+however, limits the max size of the trace to the physical memory size of the
+device, which is often too limiting.
In some cases (e.g., benchmarks, hard to repro cases) it is desirable to capture
traces that are way larger than that, at the cost of extra I/O overhead.
@@ -246,29 +246,26 @@
To achieve that, Perfetto allows to periodically write the trace buffers into
the target file (or stdout) using the following TraceConfig fields:
-* `write_into_file (bool)`:
-When true periodically drains the trace buffers into the output
-file. When this option is enabled, the userspace buffers need to be just
-big enough to hold tracing data between two write periods.
-The buffer sizing depends on the activity of the device.
-The data rate of a typical trace is ~1-4 MB/s. So a 16MB in-memory buffer can
-hold for up write periods of ~4 seconds before starting to lose data.
+- `write_into_file (bool)`: When true periodically drains the trace buffers into
+ the output file. When this option is enabled, the userspace buffers need to be
+ just big enough to hold tracing data between two write periods. The buffer
+ sizing depends on the activity of the device. The data rate of a typical trace
+ is ~1-4 MB/s. So a 16MB in-memory buffer can hold for up write periods of ~4
+ seconds before starting to lose data.
-* `file_write_period_ms (uint32)`:
-Overrides the default drain period (5s). Shorter periods require a smaller
-userspace buffer but increase the performance intrusiveness of tracing. If
-the period given is less than 100ms, the tracing service will use a period
-of 100ms.
+- `file_write_period_ms (uint32)`: Overrides the default drain period (5s).
+ Shorter periods require a smaller userspace buffer but increase the
+ performance intrusiveness of tracing. If the period given is less than 100ms,
+ the tracing service will use a period of 100ms.
-* `max_file_size_bytes (uint64)`:
-If set, stops the tracing session after N bytes have been written. Used to
-cap the size of the trace.
+- `max_file_size_bytes (uint64)`: If set, stops the tracing session after N
+ bytes have been written. Used to cap the size of the trace.
For a complete example of a working trace config in long-tracing mode see
[`/test/configs/long_trace.cfg`](/test/configs/long_trace.cfg).
Summary: to capture a long trace just set `write_into_file:true`, set a long
- `duration_ms` and use an in-memory buffer size of 32MB or more.
+`duration_ms` and use an in-memory buffer size of 32MB or more.
## Data-source specific config
@@ -276,7 +273,8 @@
data-source-specific behaviors. At the proto schema level, this is defined in
the `DataSourceConfig` section of `TraceConfig`:
-From [data_source_config.proto](/protos/perfetto/config/data_source_config.proto):
+From
+[data_source_config.proto](/protos/perfetto/config/data_source_config.proto):
```protobuf
message TraceConfig {
@@ -312,42 +310,43 @@
implements data sources.
#### A note on backwards/forward compatibility
+
The tracing service will route the raw binary blob of the `DataSourceConfig`
message to the data sources with a matching name, without attempting to decode
and re-encode it. If the `DataSourceConfig` section of the trace config contains
a new field that didn't exist at the time when the service was built, the
-service will still pass the `DataSourceConfig` through to the data source.
-This allows to introduced new data sources without needing the service to
-know anything about them upfront.
+service will still pass the `DataSourceConfig` through to the data source. This
+allows to introduced new data sources without needing the service to know
+anything about them upfront.
TODO: we are aware of the fact that today extending the `DataSourceConfig` with
a custom proto requires changing the `data_source_config.proto` in the Perfetto
-repo, which is unideal for external projects. The long-term plan is to reserve
-a range of fields for non-upstream extensions and provide generic templated
+repo, which is unideal for external projects. The long-term plan is to reserve a
+range of fields for non-upstream extensions and provide generic templated
accessors for client code. Until then, we accept patches upstream to introduce
ad-hoc configurations for your own data sources.
## Multi-process data sources
Some data sources are singletons. E.g., in the case of scheduler tracing that
-Perfetto ships on Android, there is only data source for the whole system,
-owned by the `traced_probes` service.
+Perfetto ships on Android, there is only data source for the whole system, owned
+by the `traced_probes` service.
However, in the general case multiple processes can advertise the same data
source. This is the case, for instance, when using the
[Perfetto SDK](/docs/instrumentation/tracing-sdk.md) for userspace
instrumentation.
-If this happens, when starting a tracing session that specifies that data
-source in the trace config, Perfetto by default will ask all processes that
-advertise that data source to start it.
+If this happens, when starting a tracing session that specifies that data source
+in the trace config, Perfetto by default will ask all processes that advertise
+that data source to start it.
In some cases it might be desirable to further limit the enabling of the data
source to a specific process (or set of processes). That is possible through the
`producer_name_filter` and `producer_name_regex_filter`.
NOTE: the typical Perfetto run-time model is: one process == one Perfetto
- Producer; one Producer typically hosts multiple data sources.
+Producer; one Producer typically hosts multiple data sources.
When those filters are set, the Perfetto tracing service will activate the data
source only in the subset of producers matching the filter.
@@ -380,8 +379,8 @@
which is based on triggers. The overall idea is to declare in the trace config
itself:
-* A set of triggers, which are just free-form strings.
-* Whether a given trigger should cause the trace to be started or stopped, and
+- A set of triggers, which are just free-form strings.
+- Whether a given trigger should cause the trace to be started or stopped, and
the start/stop delay.
Why using triggers? Why can't one just start perfetto or kill(SIGTERM) it when
@@ -393,12 +392,12 @@
Triggers offer a way to unprivileged apps to control, in a limited fashion, the
lifecycle of a tracing session. The conceptual model is:
-* The privileged Consumer (see
- [_Service model_](/docs/concepts/service-model.md)), i.e. the entity
- that is normally authorized to start tracing (e.g., adb shell in Android),
- declares upfront what are the possible trigger names for the trace and what
- they will do.
-* Unprivileged entities (any random app process) can activate those triggers.
+- The privileged Consumer (see
+ [_Service model_](/docs/concepts/service-model.md)), i.e. the entity that is
+ normally authorized to start tracing (e.g., adb shell in Android), declares
+ upfront what are the possible trigger names for the trace and what they will
+ do.
+- Unprivileged entities (any random app process) can activate those triggers.
Unprivileged entities don't get a say on what the triggers will do, they only
communicate that an event happened.
@@ -417,12 +416,13 @@
Start triggers allow activating a tracing session only after some significant
event has happened. Passing a trace config that has `START_TRACING` trigger
-causes the tracing session to stay idle (i.e. not recording any data) until either
-the trigger is hit or the `trigger_timeout_ms` timeout is hit.
+causes the tracing session to stay idle (i.e. not recording any data) until
+either the trigger is hit or the `trigger_timeout_ms` timeout is hit.
`trace_duration_ms` and triggered traces can not be used at the same time.
Example config:
+
```protobuf
# If the "myapp_is_slow" is hit, the trace starts recording data and will be
# stopped after 5s.
@@ -450,12 +450,13 @@
signal.
This can be used to use perfetto in flight-recorder mode. By starting a trace
-with buffers configured in `RING_BUFFER` mode and `STOP_TRACING` triggers,
-the trace will be recorded in a loop and finalized when the culprit event is
+with buffers configured in `RING_BUFFER` mode and `STOP_TRACING` triggers, the
+trace will be recorded in a loop and finalized when the culprit event is
detected. This is key for events where the root cause is in the recent past
(e.g., the app detects a slow scroll or a missing frame).
Example config:
+
```protobuf
# If no trigger is hit, the trace will end after 30s.
trigger_timeout_ms: 30000
@@ -478,21 +479,20 @@
On Android, there are some caveats around using `adb shell`
-* Ctrl+C, which normally causes a graceful termination of the trace, is not
+- Ctrl+C, which normally causes a graceful termination of the trace, is not
propagated by ADB when using `adb shell perfetto` but only when using an
interactive PTY-based session via `adb shell`.
-* On non-rooted devices before Android 12, the config can only be passed as
+- On non-rooted devices before Android 12, the config can only be passed as
`cat config | adb shell perfetto -c -` (-: stdin) because of over-restrictive
SELinux rules. Since Android 12 `/data/misc/perfetto-configs` can be used for
storing configs.
-* On devices before Android 10, adb cannot directly pull
+- On devices before Android 10, adb cannot directly pull
`/data/misc/perfetto-traces`. Use
`adb shell cat /data/misc/perfetto-traces/trace > trace` to work around.
-* When capturing longer traces, e.g. in the context of benchmarks or CI, use
+- When capturing longer traces, e.g. in the context of benchmarks or CI, use
`PID=$(perfetto --background)` and then `kill $PID` to stop.
-
## Other resources
-* [TraceConfig Reference](/docs/reference/trace-config-proto.autogen)
-* [Buffers and dataflow](/docs/concepts/buffers.md)
+- [TraceConfig Reference](/docs/reference/trace-config-proto.autogen)
+- [Buffers and dataflow](/docs/concepts/buffers.md)
diff --git a/docs/data-sources/syscalls.md b/docs/data-sources/syscalls.md
index 3e6156d..8e769e8 100644
--- a/docs/data-sources/syscalls.md
+++ b/docs/data-sources/syscalls.md
@@ -15,13 +15,13 @@
At the UI level system calls are shown inlined with the per-thread slice tracks:
-
+
## SQL
At the SQL level, syscalls are no different than any other userspace slice
event. They get interleaved in the per-thread slice stack and can be easily
-filtered by looking for the 'sys_' prefix:
+filtered by looking for the 'sys\_' prefix:
```sql
select ts, dur, t.name as thread, s.name, depth from slices as s
@@ -30,14 +30,14 @@
where s.name like 'sys_%'
```
-ts | dur | thread | name
----|-----|--------|------
-856325324372751 | 439867648 | s.nexuslauncher | sys_epoll_pwait
-856325324376970 | 990 | FpsThrottlerThr | sys_recvfrom
-856325324378376 | 2657 | surfaceflinger | sys_ioctl
-856325324419574 | 1250 | android.anim.lf | sys_recvfrom
-856325324428168 | 27344 | android.anim.lf | sys_ioctl
-856325324451345 | 573 | FpsThrottlerThr | sys_getuid
+| ts | dur | thread | name |
+| --------------- | --------- | --------------- | --------------- |
+| 856325324372751 | 439867648 | s.nexuslauncher | sys_epoll_pwait |
+| 856325324376970 | 990 | FpsThrottlerThr | sys_recvfrom |
+| 856325324378376 | 2657 | surfaceflinger | sys_ioctl |
+| 856325324419574 | 1250 | android.anim.lf | sys_recvfrom |
+| 856325324428168 | 27344 | android.anim.lf | sys_ioctl |
+| 856325324451345 | 573 | FpsThrottlerThr | sys_getuid |
## TraceConfig
diff --git a/docs/instrumentation/tracing-sdk.md b/docs/instrumentation/tracing-sdk.md
index a77d363..a3b7c85a 100644
--- a/docs/instrumentation/tracing-sdk.md
+++ b/docs/instrumentation/tracing-sdk.md
@@ -5,27 +5,26 @@
When using the Tracing SDK there are two main aspects to consider:
-1. Whether you are interested only in tracing events coming from your own app
- or want to collect full-stack traces that overlay app trace events with
- system trace events like scheduler traces, syscalls or any other Perfetto
- data source.
+1. Whether you are interested only in tracing events coming from your own app or
+ want to collect full-stack traces that overlay app trace events with system
+ trace events like scheduler traces, syscalls or any other Perfetto data
+ source.
2. For app-specific tracing, whether you need to trace simple types of timeline
- events (e.g., slices, counters) or need to define complex data sources with a
- custom strongly-typed schema (e.g., for dumping the state of a subsystem of
- your app into the trace).
+ events (e.g., slices, counters) or need to define complex data sources with a
+ custom strongly-typed schema (e.g., for dumping the state of a subsystem of
+ your app into the trace).
For Android-only instrumentation, the advice is to keep using the existing
-[android.os.Trace (SDK)][atrace-sdk] / [ATrace_* (NDK)][atrace-ndk] if they
+[android.os.Trace (SDK)][atrace-sdk] / [ATrace\_\* (NDK)][atrace-ndk] if they
are sufficient for your use cases. Atrace-based instrumentation is fully
-supported in Perfetto.
-See the [Data Sources -> Android System -> Atrace Instrumentation][atrace-ds]
-for details.
+supported in Perfetto. See the [Data Sources -> Android System -> Atrace
+Instrumentation][atrace-ds] for details.
## Getting started
-TIP: The code from these examples is also available [in the
-repository](/examples/sdk/README.md).
+TIP: The code from these examples is also available
+[in the repository](/examples/sdk/README.md).
To start using the Client API, first check out the latest SDK release:
@@ -105,9 +104,8 @@
Track events are the suggested option when dealing with app-specific tracing as
they take care of a number of subtleties (e.g., thread safety, flushing, string
-interning).
-Track events are time bounded events (e.g., slices, counter) based on simple
-`TRACE_EVENT` annotation tags in the codebase, like this:
+interning). Track events are time bounded events (e.g., slices, counter) based
+on simple `TRACE_EVENT` annotation tags in the codebase, like this:
```c++
#include <perfetto.h>
@@ -167,15 +165,14 @@
### Custom data sources
For most uses, track events are the most straightforward way of instrumenting
-apps for tracing. However, in some rare circumstances they are not
-flexible enough, e.g., when the data doesn't fit the notion of a track or is
-high volume enough that it needs a strongly typed schema to minimize the size of
-each event. In this case, you can implement a *custom data source* for
-Perfetto.
+apps for tracing. However, in some rare circumstances they are not flexible
+enough, e.g., when the data doesn't fit the notion of a track or is high volume
+enough that it needs a strongly typed schema to minimize the size of each event.
+In this case, you can implement a _custom data source_ for Perfetto.
Unlike track events, when working with custom data sources, you will also need
-corresponding changes in [trace processor](/docs/analysis/trace-processor.md)
-to enable importing your data format.
+corresponding changes in [trace processor](/docs/analysis/trace-processor.md) to
+enable importing your data format.
A custom data source is a subclass of `perfetto::DataSource`. Perfetto will
automatically create one instance of the class for each tracing session it is
@@ -248,9 +245,9 @@
```
If necessary the `Trace()` method can access the custom data source state
-(`my_custom_state` in the example above). Doing so, will take a mutex to
-ensure data source isn't destroyed (e.g., because of stopping tracing) while
-the `Trace()` method is called on another thread. For example:
+(`my_custom_state` in the example above). Doing so, will take a mutex to ensure
+data source isn't destroyed (e.g., because of stopping tracing) while the
+`Trace()` method is called on another thread. For example:
```C++
CustomDataSource::Trace([](CustomDataSource::TraceContext ctx) {
@@ -261,9 +258,9 @@
## In-process vs System mode
-The two modes are not mutually exclusive. An app can be configured to work
-in both modes and respond both to in-process tracing requests and system
-tracing requests. Both modes generate the same trace file format.
+The two modes are not mutually exclusive. An app can be configured to work in
+both modes and respond both to in-process tracing requests and system tracing
+requests. Both modes generate the same trace file format.
### In-process mode
@@ -275,8 +272,8 @@
`TracingInitArgs.backends = perfetto::kInProcessBackend` when initializing the
SDK, see examples below.
-This mode is used to generate traces that contain only events emitted by
-the app, but not other types of events (e.g. scheduler traces).
+This mode is used to generate traces that contain only events emitted by the
+app, but not other types of events (e.g. scheduler traces).
The main advantage is that by running fully in-process, it doesn't require any
special OS privileges and the profiled process can control the lifecycle of
@@ -293,32 +290,32 @@
`TracingInitArgs.backends = perfetto::kSystemBackend` when initializing the SDK,
see examples below.
-The main advantage of this mode is that it is possible to create fused traces where
-app events are overlaid on the same timeline of OS events. This enables
+The main advantage of this mode is that it is possible to create fused traces
+where app events are overlaid on the same timeline of OS events. This enables
full-stack performance investigations, looking all the way through syscalls and
kernel scheduling events.
-The main limitation of this mode is that it requires the external `traced` daemon
-to be up and running and reachable through the UNIX socket connection.
+The main limitation of this mode is that it requires the external `traced`
+daemon to be up and running and reachable through the UNIX socket connection.
This is suggested for local debugging or lab testing scenarios where the user
(or the test harness) can control the OS deployment (e.g., sideload binaries on
Android).
When using system mode, the tracing session must be controlled from the outside,
-using the `perfetto` command-line client
-(See [reference](/docs/reference/perfetto-cli)). This is because when collecting
+using the `perfetto` command-line client (See
+[reference](/docs/reference/perfetto-cli)). This is because when collecting
system traces, tracing data producers are not allowed to read back the trace
data as it might disclose information about other processes and allow
side-channel attacks.
-* On Android 9 (Pie) and beyond, traced is shipped as part of the platform.
-* On older versions of Android, traced can be built from sources using the
- the [standalone NDK-based workflow](/docs/contributing/build-instructions.md)
- and sideloaded via adb shell.
-* On Linux and MacOS and Windows `traced` must be built and run separately. See
+- On Android 9 (Pie) and beyond, traced is shipped as part of the platform.
+- On older versions of Android, traced can be built from sources using the the
+ [standalone NDK-based workflow](/docs/contributing/build-instructions.md) and
+ sideloaded via adb shell.
+- On Linux and MacOS and Windows `traced` must be built and run separately. See
the [Linux quickstart](/docs/quickstart/linux-tracing.md) for instructions.
-* On Windows the tracing protocol works over TCP/IP (
+- On Windows the tracing protocol works over TCP/IP (
[127.0.0.1:32278](https://cs.android.com/android/platform/superproject/main/+/main:external/perfetto/src/tracing/ipc/default_socket.cc;l=75;drc=4f88a2fdfd3801c109d5e927b8206f9756288b12)
) + named shmem.
@@ -370,12 +367,12 @@
```
TIP: API methods with `Blocking` in their name will suspend the calling thread
- until the respective operation is complete. There are also asynchronous
- variants that don't have this limitation.
+until the respective operation is complete. There are also asynchronous variants
+that don't have this limitation.
-Now that tracing is active, instruct your app to perform the operation you
-want to record. After that, stop tracing and collect the
-protobuf-formatted trace data:
+Now that tracing is active, instruct your app to perform the operation you want
+to record. After that, stop tracing and collect the protobuf-formatted trace
+data:
```C++
tracing_session->StopBlocking();
@@ -388,9 +385,9 @@
output.close();
```
-To save memory with longer traces, you can also tell Perfetto to write
-directly into a file by passing a file descriptor into Setup(), remembering
-to close the file after tracing is done:
+To save memory with longer traces, you can also tell Perfetto to write directly
+into a file by passing a file descriptor into Setup(), remembering to close the
+file after tracing is done:
```C++
int fd = open("example.perfetto-trace", O_RDWR | O_CREAT | O_TRUNC, 0600);
@@ -401,8 +398,9 @@
close(fd);
```
-The resulting trace file can be directly opened in the [Perfetto
-UI](https://ui.perfetto.dev) or the [Trace Processor](/docs/analysis/trace-processor.md).
+The resulting trace file can be directly opened in the
+[Perfetto UI](https://ui.perfetto.dev) or the
+[Trace Processor](/docs/analysis/trace-processor.md).
[ipc]: /docs/design-docs/api-and-abi.md#socket-protocol
[atrace-ds]: /docs/data-sources/atrace.md
diff --git a/docs/quickstart/callstack-sampling.md b/docs/quickstart/callstack-sampling.md
index 30fd74a..f597e5c 100644
--- a/docs/quickstart/callstack-sampling.md
+++ b/docs/quickstart/callstack-sampling.md
@@ -2,12 +2,12 @@
## Prerequisites
-* [ADB](https://developer.android.com/studio/command-line/adb) installed.
-* A device running Android T+.
-* Either a debuggable (`userdebug`/`eng`) Android image, or the apps to be
- profiled need to be
- [marked as profileable or debuggable](https://developer.android.com/guide/topics/manifest/profileable-element)
- in their manifests.
+- [ADB](https://developer.android.com/studio/command-line/adb) installed.
+- A device running Android T+.
+- Either a debuggable (`userdebug`/`eng`) Android image, or the apps to be
+ profiled need to be
+ [marked as profileable or debuggable](https://developer.android.com/guide/topics/manifest/profileable-element)
+ in their manifests.
## Capture a CPU profile
@@ -130,6 +130,6 @@
`cpu_profile` will also write separate profiles for each process that it
profiled in the output directory, and those can be visualized using
-[`pprof`](https://github.com/google/pprof). You can merge them into one
-by passing all of them to pprof, e.g.
+[`pprof`](https://github.com/google/pprof). You can merge them into one by
+passing all of them to pprof, e.g.
`pprof /tmp/perf_profile-240105114948clvad/*`.
