Javascript Profiling: Difference between revisions

Jump to navigation Jump to search

Javascript Profiling (view source)

Revision as of 21:42, 29 June 2012

94 bytes removed ,  29 June 2012
no edit summary
No edit summary
No edit summary
Line 4: Line 4:


As an idea of what should be possible to build on top of this API, see [http://unity3d.com/support/documentation/Manual/Profiler.html Unity's profiler],
As an idea of what should be possible to build on top of this API, see [http://unity3d.com/support/documentation/Manual/Profiler.html Unity's profiler],
The profiling API is centered around profiling particular "contexts" of information. These "contexts" represent a set of scripts which are to be profiled, and will be referred to as from the root object, or "the global." This concept is similar to the [[Debugger]] API. When profiling a script, the scripts being profiled are contained to the specified global.


== The Profiler object ==
== The Profiler object ==


There will be a global <tt>Profiler</tt> object available to instantiate to begin profiling other objects. The <tt>Profiler</tt> object has the following methods:
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:


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


<dt>startProfiling(obj, [sample_rate, [max_samples]])
<dt>start([obj, [sample_rate, [max_samples]]])
<dd>Ensures that profiling has started on the specified object's runtime. The sample rate and max samples are optional parameters which can tune how the profile is collected.
<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.


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.
Line 23: Line 21:


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 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.
<dt>isProfiling(obj)
<dt>isProfiling([obj])
<dd>Returns whether profiling is turned on for the specified runtime
<dd>Returns whether profiling is turned on for the specified runtime
<dt>frame()
<dt>frame()
<dd>Fetch the current object instance representing the current stack trace of invocation for the invoking context's global. Properties can be added to this object and will be persisted across invocations of this method so long as each invocation has the same backtrace. If the invoking context's global is not being profiled by the <tt>Profiler</tt> instance, 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 current runtime is not being profiled, then an error is thrown.
<dt>info(obj)
<dt>results([obj])
<dd>Returns all profile information for the specified object's runtime. The data returned is all that is collected between the last invocation of clearInfo() and all the profile data.
<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.
<dt>clearInfo(obj)
<dt>reset([obj])
<dd>Removes all custom frame() information stored for the specified object's runtime. Also clears all profiling samples collected so far.
<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.
<dt>stopProfiling(obj)
<dt>stop([obj])
<dd>Ceases profiling on the specified runtime. This must only be called if a pairing call to startProfiling(obj) has been made.
<dd>Ceases profiling on the specified runtime. If the runtime in question isn't being profiled, an error is thrown.


</dl>
</dl>


=== The return of <tt>.info()</tt> ===
=== The return of <tt>.results()</tt> ===


The return value is an object which is a hash containing all the information. The hash can loosely be viewed as a trie. Here's some example code:
The return value is an object which is a hash containing all the information. The hash can loosely be viewed as a trie. Here's some example code:
Line 61: Line 59:
  }                                       
  }                                       
                                          
                                          
  p.startProfiling(p);                   
  p.start();                   
  foo(4000000);                           
  foo(4000000);                           
  bar(200);                               
  bar(200);                               
  p.stopProfiling(p);                  
  p.stop();
                                          
                                          
  print(JSON.stringify(p.info(p)))       
  print(JSON.stringify(p.results()))       


And the following hash would be printed:
And the following hash would be printed:


  {                                                                   
  {                                                                   
   ticks: 624,                                                       
   samples: 624,                                                       
   children: [                                                       
   children: [                                                       
     {                                                               
     {                                                               
       function: { file: 'input.js', line: 1 },                       
       function: { file: 'input.js', line: 1, name: '<top level>' },                       
       site: { file: 'input.js', line: 25 },                         
       site: { file: 'input.js', line: 25 },                         
       ticks: 624,                                                   
       samples: 624,                                                   
       children: [                                                   
       children: [                                                   
         {                                                           
         {                                                           
           function: { file: 'input.js', line: 1, name: 'foo' },     
           function: { file: 'input.js', line: 1, name: 'foo' },     
           site: { file: 'input.js', line: 7 },                       
           site: { file: 'input.js', line: 7 },                       
           ticks: 195,                                               
           samples: 195,                                               
           self: 195                                                 
           selfCount: 195                                                 
         }, {                                                         
         }, {                                                         
           function: { file: 'input.js', line: 1, name: 'foo' },     
           function: { file: 'input.js', line: 1, name: 'foo' },     
           site: { file: 'input.js', line: 11 },                     
           site: { file: 'input.js', line: 11 },                     
           ticks: 429,                                               
           samples: 429,                                               
           self: 429                                                 
           selfCount: 429                                                 
         }                                                           
         }                                                           
       ]                                                             
       ]                                                             
     }, {                                                             
     }, {                                                             
       function: { file: 'input.js', line: 1},                       
       function: { file: 'input.js', line: 1 },                       
       site: { file: 'input.js', line: 26},                           
       site: { file: 'input.js', line: 26 },                           
       children: [                                                   
       children: [                                                   
         {                                                           
         {                                                           
Line 115: Line 113:


<dl>
<dl>
<dt>ticks
<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>ticks = self + children.sum('ticks')</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>self
<dt>selfCount
<dd>This is an integer value like "ticks," 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 self count 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.
<dt>gc
<dd>This integer represents the number of times that garbage collection was invoked at the site
<dt>compile
<dd>This integer represents the number of times a function was compiled when invoked from this site.
</dl>
</dl>
Other statistics can be easily added from either JS or C++.


== Use Cases ==
== Use Cases ==
Line 133: Line 125:
=== Test Cases ===
=== Test Cases ===


The test suite would initially create a <tt>Profiler</tt> object and then start/stop profiling the current page on each call to <tt>startProfiling</tt>/<tt>stopProfiling</tt> and the information returned from <tt>info</tt> would be what is displayed. Between each test, the <tt>clearInfo</tt> method would be used to prevent pollution between runs.
The test suite would initially create a <tt>Profiler</tt> object and then start/stop profiling the current page on each call to <tt>start</tt>/<tt>stop</tt> and the information returned from <tt>results</tt> would be what is displayed. Between each test, the <tt>reset</tt> method would be used to prevent pollution between runs.


=== Extension ===
=== Extension ===


Opened on a page and creates its own <tt>Profiler</tt> object. It then profiles the current page via <tt>startProfiling</tt> (probably a button to be hit). Some time later <tt>info</tt> is used to get information about the run of profiling (again probably a button being hit) and then all of the information is sorted through and displayed in some fancy fashion.
Opened on a page and creates its own <tt>Profiler</tt> object. It then profiles the current page via <tt>start</tt> (probably a button to be hit). Some time later <tt>results</tt> is used to get information about the run of profiling (again probably a button being hit) and then all of the information is sorted through and displayed in some fancy fashion.


The page being profiled is unaware that it's being profiled, and there's nothing that it needs to do to help it along.
The page being profiled is unaware that it's being profiled, and there's nothing that it needs to do to help it along.
Acrichton
22

edits

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

Navigation menu