docs: Add documentation for TRACE_EVENT_{BEGIN,END}
Bug: https://github.com/google/perfetto/issues/39
Change-Id: I8b093b082a557b4b279e44ed78b44d446840f19cdiff --git a/docs/instrumentation/tracing-sdk.md b/docs/instrumentation/tracing-sdk.md
index f4e6bfd..049388b 100644
--- a/docs/instrumentation/tracing-sdk.md
+++ b/docs/instrumentation/tracing-sdk.md
@@ -92,7 +92,7 @@
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
-annotation tags in the codebase, like this:
+`TRACE_EVENT` annotation tags in the codebase, like this:
```c++
#include <perfetto.h>
diff --git a/docs/instrumentation/track-events.md b/docs/instrumentation/track-events.md
index 4ad67ae..1e673a0 100644
--- a/docs/instrumentation/track-events.md
+++ b/docs/instrumentation/track-events.md
@@ -83,8 +83,9 @@
#include "my_app_tracing_categories.h"
void DrawPlayer() {
- TRACE_EVENT("rendering", "DrawPlayer");
+ TRACE_EVENT("rendering", "DrawPlayer"); // Begin "DrawPlayer" slice.
...
+ // End "DrawPlayer" slice.
}
```
@@ -92,6 +93,32 @@
event will cover the time from when the `TRACE_EVENT` annotation is encountered
to the end of the block (in the example above, until the function returns).
+For events that don't follow function scoping, use `TRACE_EVENT_BEGIN` and
+`TRACE_EVENT_END`:
+
+```C++
+void LoadGame() {
+ DisplayLoadingScreen();
+
+ TRACE_EVENT_BEGIN("io", "Loading"); // Begin "Loading" slice.
+ LoadCollectibles();
+ LoadVehicles();
+ LoadPlayers();
+ TRACE_EVENT_END("io"); // End "Loading" slice.
+
+ StartGame();
+}
+```
+
+Note that you don't need to give a name for `TRACE_EVENT_END`, since it
+automatically closes the most recent event that began on the same thread. In
+other words, all events on a given thread share the same stack. This means
+that it's not recommended to have a matching pair of `TRACE_EVENT_BEGIN` and
+`TRACE_EVENT_END` markers in separate functions, since an unrelated event
+might terminate the original event unexpectedly; for events that cross
+function boundaries it's usually best to emit them on a [separate
+track](#tracks).
+
You can also supply (up to two) debug annotations together with the event.
```C++
