Confirmed users
497
edits
Javascript Profiling: Difference between revisions
Note that this API plan has been set aside.
No edit summary |
(Note that this API plan has been set aside.) |
||
| (5 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
Note: the API described here has been set aside; it will not become part of the Mozilla platform. We're going to use the [https://developer.mozilla.org/en-US/docs/Performance/Profiling_with_the_Built-in_Profiler SPS profiler] as our profiling back end. | |||
= Profiling API = | = Profiling API = | ||
| Line 18: | Line 20: | ||
A maximum number of samples can be specified as well, but the default is unlimited (0). If the maximum number of samples is reached, then the sample storage is treated as a ring buffer, discarding the oldest samples. | A maximum number of samples can be specified as well, but the default is unlimited (0). If the maximum number of samples is reached, then the sample storage is treated as a ring buffer, discarding the oldest samples. | ||
If some other Profiler object is profiling the runtime, then | If some other Profiler object is profiling the runtime, then the other profiler is forcibly stopped. Eventually a call to stop() must be paired with this call to cease data collection. | ||
<dt>isProfiling() | <dt>isProfiling() | ||
<dd>Returns whether profiling is | <dd>Returns whether profiling is active for this Profiler instance | ||
<dt>frame() | <dt>frame() | ||
<dd>Fetches an object to represent the current stack trace to be later returned via results(). This object can have any properties attached to it and will persist across different invocations of frame() so long as the same backtrace is present each time. All information specified here will later be available via results() with the full backtrace listed. By default this returns an empty object with no properties. If the | <dd>Fetches an object to represent the current stack trace to be later returned via results(). This object can have any properties attached to it and will persist across different invocations of frame() so long as the same backtrace is present each time. All information specified here will later be available via results() with the full backtrace listed. By default this returns an empty object with no properties. If the profiler is not active or has been forcibly stopped, then an error is thrown. | ||
<dt>results() | <dt>results() | ||
<dd>Returns all profile information | <dd>Returns all profile information gathered. The data returned is all that is collected between the last invocation of reset() and all the sample data. | ||
<dt>samples() | |||
<dd>Returns all profiling samples gathered. The data returned is all that is collected between the last invocation of reset() and now. If profiling is turned on, it is disabled for the duration of this function. | |||
<dt>reset() | <dt>reset() | ||
<dd>Resets all information | <dd>Resets all information that is stored. This includes samples and also frame() information. | ||
<dt>stop() | <dt>stop() | ||
<dd>Ceases profiling on the runtime. If | <dd>Ceases profiling on the runtime. If this profiler is not active or has been forcibly stopped, an error is thrown. | ||
</dl> | </dl> | ||
| Line 134: | Line 138: | ||
<dt>selfCount | <dt>selfCount | ||
<dd>This is an integer value like "samples," but instead only counts the time spent in the function itself. When a sample is taken and a function is currently running (it's the top of the stack), it's selfCount is increased. | <dd>This is an integer value like "samples," but instead only counts the time spent in the function itself. When a sample is taken and a function is currently running (it's the top of the stack), it's selfCount is increased. | ||
</dl> | |||
=== The return of <tt>.samples()</tt> === | |||
The samples() method of a Profiler returns a list of sample objects which describe a sample taken at a particular time. Each object has the following structure: | |||
{ | |||
micros: 100, | |||
weight: 2, | |||
stack: [ | |||
{ | |||
function: { line: 20, file: '...' }, | |||
site: { line: 30, file: '...' } | |||
}, | |||
... | |||
] | |||
} | |||
Each sample's field are as follows: | |||
<dl> | |||
<dt>micros | |||
<dd>This is the time at which the sample was taken (in microseconds). | |||
<dt>weight | |||
<dd>Due to the way sampling is currently implemented, time spent in native C++ functions prevent samples from being taken. For this reason, the time is attributed to the next sample. Hence this weight indicates how many samples were deferred to this stack trace. | |||
<dt>stack | |||
<dd>This will be a non-empty array with the stack trace at the time of the sample. The first function is the top of the stack and each subsequent function called the previous function. The 'function' field describes where the function was defined, and the 'site' field describes where the function is currently executing. | |||
</dl> | </dl> | ||