Docs: add docsify support Looks nicer Change-Id: I707772e47e3e8441f93af1e9ba14a4c266f080b3
diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..71b864e --- /dev/null +++ b/docs/README.md
@@ -0,0 +1,113 @@ +# Perfetto - Performance instrumentation and tracing + +Perfetto is an open-source project for performance instrumentation and tracing +of Linux/Android/Chrome platforms and user-space apps. +It consists of: + +**A portable, high efficiency, user-space tracing library** +designed for tracing of multi-process systems, based on zero-alloc zero-copy +zero-syscall (on fast-paths) writing of protobufs over shared memory. + +**OS-wide Linux/Android probes for platform debugging** +* Kernel tracing: a daemon that converts Kernel [Ftrace][ftrace] events into + API-stable protobufs, on device, with low overhead. +* I/O tracing +* Many new probes coming soon: heap profiling, perf sampling, syscall tracing. + +**Web-based frontend** +A UI for inspection and analysis of traces (coming soon). + +**Batch processing of traces** +A python / C++ (TBD) library for trace-based metrics (coming soon). + + + + +Goals +----- +Perfetto is building the next-gen unified tracing ecosystem for: +- Android platform tracing ([Systrace][systrace]) +- Chrome platform tracing ([chrome://tracing][chrome-tracing]) +- App-defined user-space tracing (including support for non-Android apps). + +The goal is to create an open, portable and developer friendly tracing ecosystem +for app and platform performance debugging. + +Key features +------------ +**Designed for production** +Perfetto's tracing library and daemons are designed for use in production. +Privilege isolation is a key design goal: +* The interface for writing trace events are decoupled from the interface for + read-back and control and can be subjected to different ACLs. +* Despite being based on shared memory, Perfetto is designed to prevent + cross-talk between data sources, even in case of arbitrary code execution + (memory is shared point-to-point, memory is never shared between processes). +* Perfetto daemons are designed following to the principle of least privilege, + in order to allow strong sandboxing (via SELinux on Android). + +See [docs/security-model.md](docs/security-model.md) for more details. + +**Long traces** +Pefetto aims at supporting hours-long / O(100GB) traces, both in terms of +recording backend and UI frontend. + +**Interoperability** +Perfetto traces (output) and configuration (input) consists of protobuf +messages, in order to allow interoperability with several languages. + +See [docs/trace-format.md](docs/trace-format.md) for more details. + +**Composability** +As Perfetto is designed both for OS-level tracing and app-level tracing, its +design allows to compose several instances of the Perfetto tracing library, +allowing to nest multiple layers of tracing and drive then with the same +frontend. This allows powerful blending of app-specific and OS-wide trace +events. +See [docs/multi-layer-tracing.md](docs/multi-layer-tracing.md) for more details. + +**Portability** +The only dependencies of Perfetto's tracing libraries are C++11 and [Protobuf lite][protobuf] (plus google-test, google-benchmark, libprotobuf-full for testing). + +**Extensibility** +Perfetto allows third parties to defined their own protobufs for: +* [(input) Configuration](/protos/perfetto/config/data_source_config.proto#52) +* [(output) Trace packets](/protos/perfetto/trace/trace_packet.proto#36) + +Allowing apps to define their own strongly-typed input and output schema. +See [docs/trace-format.md](docs/trace-format.md) for more details. + + +Docs +---- +* [Contributing](docs/contributing.md) +* [Build instructions](docs/build-instructions.md) +* [Running tests](docs/testing.md) +* [Running Perfetto](docs/running.md) +* [Capturing long traces](docs/long-traces.md) +* [Trace processor](docs/trace-processor.md) +* [Key concepts and architecture](docs/architecture.md) +* [Life of a tracing session](docs/life-of-a-tracing-session.md) +* [Ftrace interop](docs/ftrace.md) +* [Performance benchmarks](docs/benchmarks.md) +* [Trace config](docs/trace-config.md) +* [Trace format](docs/trace-format.md) +* [Multi-layer tracing](docs/multi-layer-tracing.md) +* [Security model](docs/security-model.md) +* [Embedding Perfetto in your own project](docs/embedder-guide.md) +* [ProtoZero internals](docs/protozero.md) +* [IPC internals](docs/ipc.md) + + +Bugs +---- +* For bugs affecting Android or the tracing internals use the internal +bug tracker ([go/perfetto-bugs](http://goto.google.com/perfetto-bugs)). +* For bugs affecting Chrome use http://crbug.com, Component:Speed>Tracing +label:Perfetto. + + +[ftrace]: https://www.kernel.org/doc/Documentation/trace/ftrace.txt +[systrace]: https://developer.android.com/studio/command-line/systrace.html +[chrome-tracing]: https://www.chromium.org/developers/how-tos/trace-event-profiling-tool +[protobuf]: https://developers.google.com/protocol-buffers/
diff --git a/docs/_coverpage.md b/docs/_coverpage.md new file mode 100644 index 0000000..1daeeca --- /dev/null +++ b/docs/_coverpage.md
@@ -0,0 +1,13 @@ +# Perfetto + + + +> Performance instrumentation and tracing for Android, Linux and Chrome + +* Open-source project for platform tracing. +* Trace processing and analysis. +* Web-based trace viewer UI. + +[Docs](#perfetto-performance-instrumentation-and-tracing) +[Sources](https://android.googlesource.com/platform/external/perfetto/) +[Trace viewer UI](https://ui.perfetto.dev) \ No newline at end of file
diff --git a/docs/embedder-guide.md b/docs/embedder-guide.md index 9ff1cf4..226e086 100644 --- a/docs/embedder-guide.md +++ b/docs/embedder-guide.md
@@ -1,4 +1,4 @@ -# Embedding Perfetto in your own project +# Embedding Perfetto in another project *** note **This doc is WIP**, stay tuned
diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..490e7b8 --- /dev/null +++ b/docs/index.html
@@ -0,0 +1,38 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <title>Perfetto - Docs</title> + <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> + <meta name="description" content="Description"> + <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"> + <link href="//fonts.googleapis.com/css?family=Exo" rel="stylesheet"> + <link rel="stylesheet" href="//unpkg.com/docsify-themeable/dist/css/theme-simple.css"> + <style> + :root { + --base-font-size: 18px; + --base-font-family: 'Exo', sans-serif; + --theme-hue: 210; + --cover-max-width: 90vw; + } + </style> +</head> +<body> + <div id="app"></div> + <script> + window.$docsify = { + name: 'Perfetto', + repo: 'https://android.googlesource.com/platform/external/perfetto/', + coverpage: true, + loadSidebar: 'toc.md', + themeable: { + } + } + </script> + <script src="//unpkg.com/docsify/lib/docsify.min.js"></script> + <script src="//unpkg.com/docsify-themeable"></script> + <script src="//unpkg.com/docsify-copy-code"></script> + <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script> + +</body> +</html>
diff --git a/docs/running.md b/docs/running.md index df98a8a..564283e 100644 --- a/docs/running.md +++ b/docs/running.md
@@ -21,7 +21,7 @@ ------------------------------------------------------------- A convenience script allows to run Perfetto daemons (`traced`, `traced_probes`) and the command line client (`perfetto`) in a tmux-based terminal: -``` +```bash CONFIG=ftrace.cfg OUT=out/default ./tools/tmux ``` @@ -34,12 +34,12 @@ Make sure that Perfetto daemons (`traced` / `traced_probes`) are running. They are enabled by default on Pixel and Pixel 2 (walleye, taimen, marlin, sailfish). On other devices start them manually by doing: -``` +```bash adb shell setprop persist.traced.enable 1 ``` If this works you will see something like this in the logs: -``` +```bash $ adb logcat -s perfetto perfetto: service.cc:45 Started traced, listening on /dev/socket/traced_producer /dev/socket/traced_consumer perfetto: probes.cc:25 Starting /system/bin/traced_probes service @@ -48,7 +48,7 @@ At which point you can grab a trace by doing: -``` +```bash $ adb shell perfetto --config :test --out /data/misc/perfetto-traces/trace ```
diff --git a/docs/toc.md b/docs/toc.md new file mode 100644 index 0000000..3ae46e3 --- /dev/null +++ b/docs/toc.md
@@ -0,0 +1,21 @@ +* Development workflow + * [Contributing](contributing.md) + * [Build instructions](build-instructions.md) + * [Running tests](testing.md) +* On-device tracer + * [Running Perfetto](running.md) + * [Capturing long traces](long-traces.md) + * [Advanced trace config](trace-config.md) +* Trace analysis + * [Trace processor](trace-processor.md) +* Architectural docs + * [Key concepts](architecture.md) + * [Life of a tracing session](life-of-a-tracing-session.md) + * [Ftrace interop](ftrace.md) + * [Performance benchmarks](benchmarks.md) + * [Trace format](trace-format.md) + * [Multi-layer tracing](multi-layer-tracing.md) + * [Security model](security-model.md) + * [Embedding Perfetto](embedder-guide.md) + * [ProtoZero internals](protozero.md) + * [IPC internals](ipc.md) \ No newline at end of file
diff --git a/docs/trace-config.md b/docs/trace-config.md index 0c5f7ba..e6b2294 100644 --- a/docs/trace-config.md +++ b/docs/trace-config.md
@@ -31,7 +31,7 @@ Specifying a custom trace config -------------------------------- -``` +```bash cat > /tmp/config.txpb <<EOF # This is a text-encoded protobuf for /protos/perfetto/config/trace_config.proto duration_ms: 10000