MozillaWiki

Javascript Profiling: Difference between revisions

Page Discussion

Javascript Profiling (view source)

Revision as of 19:58, 19 September 2012

2,582 bytes added ,  19 September 2012
Note that this API plan has been set aside.
No edit summary
(Note that this API plan has been set aside.)
 
(8 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 7: Line 9:
== The Profiler object ==
== The Profiler object ==


There will be a global <tt>Profiler</tt> object available to instantiate to begin profiling other runtimes. For each of the methods below, if an optional 'obj' parameter is taken, that is the specification of what runtime to modify profiling of. If the object is specified, then the object's runtime is used. Otherwise if no object is specified, the current runtime is used. The <tt>Profiler</tt> object has the following methods:
There will be a global <tt>Profiler</tt> object available to instantiate to begin profiling the runtime in which the profiler was created in. The <tt>Profiler</tt> object has the following methods:


<dl>
<dl>
Line 13: Line 15:
<dd>The constructor takes no arguments
<dd>The constructor takes no arguments


<dt>start([obj, [sample_rate, [max_samples]]])
<dt>start([sample_rate, [max_samples]])
<dd>Begins profiling. All arguments are optional. If no object is specified, then the current runtime of execution will be profile. Otherwise the specified object's runtime will be profiled. If the object's runtime (or the current runtime if obj isn't provided) is already being profiled by this Profiler instance, an error is thrown.
<dd>Begins profiling. All arguments are optional. The sample rate is the time between samples of the call stack specified in microseconds (defaults to 1000 = 1ms). The sample rate is mostly a guideline as the platform being run might not guarantee the granularity of timing. Samples will not happen more frequently than the specified rate, but may occur more infrequently.
 
The sample rate is the time between samples of the call stack specified in microseconds (defaults to 1000 = 1ms). The sample rate is mostly a guideline as the platform being run might not guarantee the granularity of timing. Samples will not happen more frequently than the specified rate, but may occur more infrequently.


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 specified runtime, then an error is thrown if the sample rate or maximum sample count is different. Eventually a call to stopProfiling() must be paired with this call to cease data collection.
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([obj])
<dt>isProfiling()
<dd>Returns whether profiling is turned on for the specified runtime
<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 current runtime is not being profiled, then an error is thrown.
<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([obj])
<dt>results()
<dd>Returns all profile information for the specified object's runtime. The data returned is all that is collected between the last invocation of reset() and all the profile data.
<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>reset([obj])
<dt>samples()
<dd>Resets all information known about the specified runtime. This includes samples and also frame() information. Throws an error if the runtime in question isn't being profiled.
<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>stop([obj])
<dt>reset()
<dd>Ceases profiling on the specified runtime. If the runtime in question isn't being profiled, an error is thrown.
<dd>Resets all information that is stored. This includes samples and also frame() information.
<dt>stop()
<dd>Ceases profiling on the runtime. If this profiler is not active or has been forcibly stopped, an error is thrown.


</dl>
</dl>
Line 70: Line 72:
  {                                                                   
  {                                                                   
   samples: 624,                                                       
   samples: 624,                                                       
  gcSamples: 1,                                                     
  micros: 12421,                                                     
   children: [                                                       
   children: [                                                       
     {                                                               
     {                                                               
Line 110: Line 114:
=== Profiled Statistics ===
=== Profiled Statistics ===


Some internal events are profiled when profiling is turned on, and they are kept track of in the following fields of the corresponding <tt>Profiler.Frame</tt> instance.
At the root level of the results is the following information:


<dl>
<dl>
<dt>samples
<dd>The total number of samples that were taken while the profiler was running.
<dt>gcSamples
<dd>This is the total number of samples which were taken where GC activity was happening, but no other JS code was running.
<dt>micros
<dd>This is the number of microseconds for which the profiler was running. If the results were generated when the profiler was stopped, then this is the amount of time between the start/stop. If the profiler is still running, then this is the amount of time from the start of the profiler to when the results() method was called.
</dl>
Each child then has the following profile statistics:
<dl>
<dt>function
<dd>This is the function in which the sample was taken. It contains information about the function's name/file/line definition
<dt>site
<dd>This is the actual site of execution at which the sample was taken. For example if function a calls function b and a sample were then taken, the site of b would be the line at which the sample was taken inside b, and the site of a would be the line of the function call to b.
<dt>data
<dd>If the frame() method was invoked, then this represents the corresponding data which was attached to the frame information.
<dt>samples
<dt>samples
<dd>This is an integer value of the number of ticks while this function's frame was on the stack. This is useful when counting total time spent in a function. It should be true that: <tt>samples = selfCount + children.sum('samples')</tt>
<dd>This is an integer value of the number of ticks while this function's frame was on the stack. This is useful when counting total time spent in a function. It should be true that: <tt>samples = selfCount + children.sum('samples')</tt>
<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>


Jimb
Confirmed users
497

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/446851...472070"