From f4ce16bbd1694d08f7e1b6614a4390e7fcfd086a Mon Sep 17 00:00:00 2001
From: Ivan Molodetskikh <yalterz@gmail.com>
Date: Sun, 19 Nov 2023 08:55:04 +0400
Subject: [PATCH] Document trace span naming

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3402>
---
 HACKING.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/HACKING.md b/HACKING.md
index 2123579dc..7a2e67e73 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -349,4 +349,46 @@ click_action_clicked_cb (ClutterClickAction *click_action,
 }
 ```
 
+## Trace Span Naming
+
+Trace spans should be named in C++ style, i.e.
+`Namespace::Class::method(args)`. For example:
+
+```c
+static void
+meta_wayland_surface_commit (MetaWaylandSurface *surface)
+{
+  /* ... */
+
+  COGL_TRACE_BEGIN_SCOPED (MetaWaylandSurfaceCommit,
+                           "Meta::WaylandSurface::commit()");
+
+  /* ... */
+}
+```
+
+This is to facilitate automatic name shrinking in profilers that will cut out
+the least important parts of the name (args, then namespaces in order, then
+class) to fit the name on screen when zoomed-out.
+
+If you need to annotate multiple spans within a function, you can append their
+name to the function name, delimited by a `#` sign. For example:
+
+```c
+void
+meta_thing_do_stuff (MetaThing *thing)
+{
+  COGL_TRACE_BEGIN_SCOPED (OneThing, "Meta::Thing::do_stuff#one_thing()");
+  /* Code that does one thing that takes time */
+  COGL_TRACE_END (OneThing);
+
+  COGL_TRACE_BEGIN_SCOPED (OtherThing, "Meta::Thing::do_stuff#other_thing()");
+  /* Code that does other thing that takes time */
+  COGL_TRACE_END (OtherThing);
+}
+```
+
+Keeping in the entire method name helps in profiler views that don't show
+parent-child relationships, i.e. a global span statistics view.
+
 [gnome-coding-style]: https://developer.gnome.org/documentation/guidelines/programming/coding-style.html