DevTools/OperationInstrument - Revision history

Fitzgen: /* 2. Telling the DevTools Frontend About the New Markers */ update based on moved directories

2016-01-13T21:51:59Z

2. Telling the DevTools Frontend About the New Markers: update based on moved directories

← Older revision		Revision as of 21:51, 13 January 2016
Line 55:		Line 55:
	== 2. Telling the DevTools Frontend About the New Markers ==		== 2. Telling the DevTools Frontend About the New Markers ==

	To get your new markers displayed in the performance tool's UI, edit the configuration data in '''<code>~~browser~~/~~devtools~~/performance/modules/markers.js</code>'''.		To get your new markers displayed in the performance tool's UI, edit the configuration data in '''<code>devtools/client/performance/modules/markers.js</code>'''.

	Add a property to the '''<code>TIMELINE_BLUEPRINT</code>''' object. The property key should be the <code>const char *</code> literal that you added in step 1 ("Parse HTML" in our example). The new property should be an object with the following properties:		Add a property to the '''<code>TIMELINE_BLUEPRINT</code>''' object. The property key should be the <code>const char *</code> literal that you added in step 1 ("Parse HTML" in our example). The new property should be an object with the following properties:

Victor.porof: /* Using TimelineConsumers */

2015-08-04T13:13:00Z

Using TimelineConsumers

← Older revision		Revision as of 13:13, 4 August 2015
Line 47:		Line 47:

	===== Using ''<code>TimelineConsumers</code>'' =====		===== Using ''<code>TimelineConsumers</code>'' =====
	A few static methods exist on the [https://dxr.mozilla.org/mozilla-central/source/docshell/base/timeline/TimelineConsumers.h?from=TimelineConsumers <code>TimelineConsumers</code>] class, like ''<code>AddMarkerForDocShell</code>'', ''<code>~~AddMarkerToDocShellsList~~</code>'', ''<code>~~AddMarkerToAllObservedDocShells~~</code>'' that give you fine grained control over creating the markers and what meta-data is attached to them.		A few static methods exist on the [https://dxr.mozilla.org/mozilla-central/source/docshell/base/timeline/TimelineConsumers.h?from=TimelineConsumers <code>TimelineConsumers</code>] class, like ''<code>AddMarkerForDocShell</code>'', ''<code>AddMarkerForDocShellsList</code>'', ''<code>AddMarkerForAllObservedDocShells</code>'' that give you fine grained control over creating the markers and what meta-data is attached to them.

	Example:		Example:

Victor.porof: /* Using mozilla::AutoTimelineMarker */

2015-08-03T14:30:24Z

Using mozilla::AutoTimelineMarker

← Older revision		Revision as of 14:30, 3 August 2015
Line 33:		Line 33:
	The easiest way to trace Gecko events/tasks with start and end timeline markers is to use the '''<code>mozilla::AutoTimelineMarker</code>''' RAII class. It automatically adds the start marker on construction, and adds the end marker on destruction. Don't worry too much about potential performance impact! It only actually adds the markers when the given docshell is being observed by a timeline consumer, so essentially nothing will happen if a tool to inspect those markers isn't specifically open.		The easiest way to trace Gecko events/tasks with start and end timeline markers is to use the '''<code>mozilla::AutoTimelineMarker</code>''' RAII class. It automatically adds the start marker on construction, and adds the end marker on destruction. Don't worry too much about potential performance impact! It only actually adds the markers when the given docshell is being observed by a timeline consumer, so essentially nothing will happen if a tool to inspect those markers isn't specifically open.

	This class may be used on the main thread ~~only~~ and pointer to a docshell is necessary. If the docshell is a nullptr, nothing happens and this operation fails silently.		This class may only be used on the main thread, and pointer to a docshell is necessary. If the docshell is a nullptr, nothing happens and this operation fails silently.

	Example:		Example:

Victor.porof: /* Using mozilla::AutoGlobalTimelineMarker */

2015-08-03T14:30:00Z

Using mozilla::AutoGlobalTimelineMarker

← Older revision		Revision as of 14:30, 3 August 2015
Line 40:		Line 40:

	===== Using ''<code>mozilla::AutoGlobalTimelineMarker</code>'' =====		===== Using ''<code>mozilla::AutoGlobalTimelineMarker</code>'' =====
	Similar to the previous RAII class, but doesn't expect a specific docshell, and the marker will be visible in all timeline consumers. This is useful for generic operations that don't involve a particular dochsell, or where a docshell isn't accessible. May also be used on the main thread ~~only~~.		Similar to the previous RAII class, but doesn't expect a specific docshell, and the marker will be visible in all timeline consumers. This is useful for generic operations that don't involve a particular dochsell, or where a docshell isn't accessible. May also only be used on the main thread.

	Example:		Example:

Victor.porof: Update documentation to reflect the new API

2015-08-03T10:06:44Z

Update documentation to reflect the new API

@@ Line 28: / Line 28: @@
 == 1. Adding the Instrumentation to Gecko ==
-The easiest way to trace Gecko events/tasks with start and end timeline markers is to use the '''<code>mozilla::AutoTimelineMarker</code>''' RAII class. It automatically adds the start marker on construction, and adds the end marker on destruction. Don't worry too much about potential performance impact! It only actually adds the markers when the given docshell is being recorded.
+Depending on the required fine level of control, there's a couple of ways to do this, and more coming soon. Currently, markers may only be added from the main thread, with plans to support them everywhere in the near future (see ''<code>otmt-markers</code>'' [https://bugzilla.mozilla.org/show_bug.cgi?id=1183219 bug 1183219]).
- --- a/dom/base/nsContentUtils.cpp
+===== Using ''<code>mozilla::AutoTimelineMarker</code>'' =====
- +++ b/dom/base/nsContentUtils.cpp
+The easiest way to trace Gecko events/tasks with start and end timeline markers is to use the '''<code>mozilla::AutoTimelineMarker</code>''' RAII class. It automatically adds the start marker on construction, and adds the end marker on destruction. Don't worry too much about potential performance impact! It only actually adds the markers when the given docshell is being observed by a timeline consumer, so essentially nothing will happen if a tool to inspect those markers isn't specifically open.
-Alternatively, you can use [https://dxr.mozilla.org/mozilla-central/search?q=nsDocShell%3A%3AAddProfileTimelineMarker <code>nsDocShell::AddProfilerTimelineMarker</code>] method to manually add start and end marker pairs.
+This class may be used on the main thread only and pointer to a docshell is necessary. If the docshell is a nullptr, nothing happens and this operation fails silently.
 == 2. Telling the DevTools Frontend About the New Markers ==

Fitzgen: /* 2. Telling the DevTools Frontend About the New Markers */ fix path again

2015-06-02T01:09:26Z

2. Telling the DevTools Frontend About the New Markers: fix path again

← Older revision		Revision as of 01:09, 2 June 2015
Line 56:		Line 56:
	== 2. Telling the DevTools Frontend About the New Markers ==		== 2. Telling the DevTools Frontend About the New Markers ==

	To get your new markers displayed in the performance tool's UI, edit the configuration data in '''<code>browser/devtools/performance/modules/~~global~~.js</code>'''.		To get your new markers displayed in the performance tool's UI, edit the configuration data in '''<code>browser/devtools/performance/modules/markers.js</code>'''.

	Add a property to the '''<code>TIMELINE_BLUEPRINT</code>''' object. The property key should be the <code>const char *</code> literal that you added in step 1 ("Parse HTML" in our example). The new property should be an object with the following properties:		Add a property to the '''<code>TIMELINE_BLUEPRINT</code>''' object. The property key should be the <code>const char *</code> literal that you added in step 1 ("Parse HTML" in our example). The new property should be an object with the following properties:

Fitzgen: /* 2. Telling the DevTools Frontend About the New Markers */ fix path

2015-06-01T23:52:12Z

2. Telling the DevTools Frontend About the New Markers: fix path

← Older revision		Revision as of 23:52, 1 June 2015
Line 56:		Line 56:
	== 2. Telling the DevTools Frontend About the New Markers ==		== 2. Telling the DevTools Frontend About the New Markers ==

	To get your new markers displayed in the performance tool's UI, edit the configuration data in '''<code>browser/devtools/~~shared~~/~~timeline~~/global.js</code>'''.		To get your new markers displayed in the performance tool's UI, edit the configuration data in '''<code>browser/devtools/performance/modules/global.js</code>'''.

	Add a property to the '''<code>TIMELINE_BLUEPRINT</code>''' object. The property key should be the <code>const char *</code> literal that you added in step 1 ("Parse HTML" in our example). The new property should be an object with the following properties:		Add a property to the '''<code>TIMELINE_BLUEPRINT</code>''' object. The property key should be the <code>const char *</code> literal that you added in step 1 ("Parse HTML" in our example). The new property should be an object with the following properties:

Fitzgen: /* 2. Telling the DevTools Frontend About the New Markers */ add suggested reviewers

2015-04-27T22:12:09Z

2. Telling the DevTools Frontend About the New Markers: add suggested reviewers

← Older revision		Revision as of 22:12, 27 April 2015
Line 92:		Line 92:
	timeline.label.domevent=DOM Event		timeline.label.domevent=DOM Event
	timeline.label.consoleTime=Console		timeline.label.consoleTime=Console

			Any of the people [[DevTools/GetInvolved#Communication\|listed here under "Performance"]] are good candidates to review the devtools config changes.

	= Adding Custom Metadata to Markers =		= Adding Custom Metadata to Markers =

Fitzgen: /* Recording Markers in a Different Thread */ link bug for different threads

2015-04-09T22:13:13Z

Recording Markers in a Different Thread: link bug for different threads

← Older revision		Revision as of 22:13, 9 April 2015
Line 101:		Line 101:
	= Recording Markers in a Different Thread =		= Recording Markers in a Different Thread =

	For now, it's not supported. Only operations in the main thread are instrumented.		For now, it's not supported. Only operations in the main thread are instrumented. Follow https://bugzilla.mozilla.org/show_bug.cgi?id=1152988 to watch for support for markers from different threads.

	~~'''Notes from Tom~~:~~'''~~

	~~First, right now when a marker object is created, it acquires the time~~
	~~from the docshell. In docshell~~/~~base~~/~~TimelineMarker~~.~~cpp:~~

	~~TimelineMarker::TimelineMarker(nsDocShell* aDocShell, const char* aName,~~
	~~TracingMetadata aMetaData)~~
	[...]
	~~aDocShell->Now(&mTime);~~

	~~Now, I think nsDocShell::Now is actually thread-safe. However, I would probably move the logic into TimelineMarker itself and avoid the need~~ to ~~have a docshell at TimelineMarker creation. The code was written this way mostly~~ for ~~historical reasons, but also perhaps to make sure that the timeline epoch is dealt with in a single place.~~

	~~At this point you could make a new TimelineMarker object on any thread.~~

	So then the next step is to ship it to the main thread. Basically I'd make a new nsIRunnable that holds the TimelineMarker object, and use NS_DispatchToMainThread. This runnable would call nsDocShell::AddProfileTimelineMarker when it ran.

	This last step is the trickiest -- you have to pick which docshell to notify. I don't know of a generic way to do this; it's been the trickiest part of the patches I worked on. ('''Note from Paul''': depending on the type of thread, we might register these markers at the global level. For example, it doesn't make sense to attach markers from ~~the compositor thread to a docshell. It's not the case to network~~ threads ~~though).~~

	~~Because we add the start and stop-markers to the docshell separately, it's simple to add a start marker from one thread and an end marker from another thread; or whatever you like~~.

Fitzgen: What is a good candidate for tracing?

2015-04-09T22:03:02Z

What is a good candidate for tracing?

← Older revision		Revision as of 22:03, 9 April 2015
Line 17:		Line 17:

	'''You can contribute to Operation Instrument by adding more instrumentation!'''		'''You can contribute to Operation Instrument by adding more instrumentation!'''

			What is a good candidate for tracing? Any single operation that can take more than a millisecond of time is a good rule of thumb. Parsing HTML is a good example because it can easily take tens of milliseconds or even longer on really big HTML snippets. Flattening a JS rope string is not as good an example, because while it may take up a lot of time in aggregate over a period of time, each individual flattening should be much faster than a millisecond.

	= Tutorial: Instrumenting New Operations =		= Tutorial: Instrumenting New Operations =