API Documentation for: 1.0.1
Show:

Profiler Class

Namespace: Canteen\Profiler

The Profiler is used to analyze your application in order to determine where you could use the most optimization. The profiler class is where all interaction with the Profiler takes place. You use it to create step nodes and render the output.

Constructor

Profiler

(
  • [parser=null]
)

Parameters:

  • [parser=null] Parser optional

    Optional to pass in existing Parser

Methods

addDuration

(
  • time
)

Add node duration to the {@link Profiler::$childDurations} variable

Parameters:

  • time Number

    duration of the child node in microseconds

addQueryDuration

(
  • time
)
Number

Increment the total query time

This method is used by the {@link ProfilerGhostNode} to increment the total query time for the page execution. This method should never be called in userland. There is zero need to.

Parameters:

  • time Number

    amount of time the query took to execute in microseconds.

Returns:

Number:

Current amount of time (in microseconds) used to execute sql queries.

calculateThreshold

() protected

Calculate the time cut-off for a trivial step. Utilizes the {@link Profiler::$trivialThreshold} value to determine how fast a step must be to be regarded "trivial"

disable

()

Disable the profiler

enable

()

Enable the profiler

end

(
  • nodeName
  • nuke
)
Boolean

End a step by name, or end all steps in the current tree.

Parameters:

  • nodeName String

    ends the first-found step with this name. (Note: a warning is generated if it's not the current step, because this is probably unintentional!)

  • nuke Boolean

    denotes whether you are intentionally attempting to terminate the entire step-stack. If true, the warning mentioned is not generated.

Returns:

Boolean:

|ProfilerNode|ProfilerGhostNode returns null if you ended the top-level step node, or the parent to the ended node, or a ghost node if the profiler is disabled.

getGlobalDuration

() Number

Get the global script duration

Returns:

Number:

Duration of the script (in milliseconds, 1 significant digit)

getGlobalStart

() Number

Get the global start time

Returns:

Number:

Start time of the script from unix epoch (milliseconds, 1 significant digit)

getMemUsage

(
  • [unit='']
)

Get the global memory usage in KB

Parameters:

  • [unit=''] String optional

    a metric prefix to force the unit of bytes used (B, K, M, G)

getTotalQueryTime

() Number

Get the total amount of query time

Returns:

Number:

Total time used to execute sql queries (milliseconds, 1 significant digit)

isEnabled

() Boolean

Check to see if the profiler is enabled

Returns:

Boolean:

True if profiler is enabled, false if disabled

isTrivial

(
  • node
)
Boolean

Determines if a node is trivial

Parameters:

Returns:

Boolean:

True if a node is trivial, false if not

render

(
  • [showDepth=-1]
)
String

Render the profiler output

Parameters:

  • [showDepth=-1] Int optional

    the depth of the step tree to traverse when rendering the profiler output. -1 to render the entire tree

Returns:

String:

The render of the profiler to include on your page

setTrivialThreshold

(
  • threshold
)

Set the Percentile Boundary Threshold. This is used to set the percentile boundary for when a node is considered trivial or not. By default, .75 is used. This translates to the fastest 25% of nodes being regarded "trivial". This is a sliding scale, so you will always see some output, regardless of how fast your application runs.

Parameters:

  • threshold Number

    the threshold to use as the percentile boundary

sqlEnd

()

Stop profiling the current SQL call

sqlStart

(
  • query
)
ProfilerSQLNode | ProfilerGhostNode

Start a new sql query

This method is used to tell the profiler to track an sql query. These are treated differently than step nodes

Parameters:

  • query String

    the query that you are running (used in the output of the profiler so you can view the query run)

Returns:

ProfilerSQLNode | ProfilerGhostNode:

returns an instance of the {@link ProfilerGhostNode} if profiler is enabled, or {@link ProfilerGhostNode} if disabled

start

(
  • nodeName
)
ProfilerNode | ProfilerGhostNode

Start a new step. This is the most-called method of the profiler.
It initializes and returns a new step node.

Parameters:

  • nodeName Sstring

    name/identifier for your step. is used later in the output to identify this step

Returns:

ProfilerNode | ProfilerGhostNode:

returns an instance of a {@link ProfilerNode} if the profiler is enabled, or a {@link ProfilerGhostNode} if it's disabled

Properties

childDurations

Array protected

Global tracker for step times. Keeps track of how long each node took to execute. This is used to determine what is a "trivial" node, and what is not.

currentNode

ProfilerNode protected

Tracks the current step node.

depthCount

Int protected

Tracks the current tree depth

enabled

Boolean protected

Used to identify when the profiler has been enabled. If false no profiling data is stored, in order to reduce the overhead of running the profiler

ghostNode

ProfilerGhostNode protected

A lightweight shell node used to return when the profiler is disabled.

globalDuration

Number protected

Total time script took to run

globalEnd

Number protected

Time the profiler 'ends'. This is populated just before rendering output (see {@link Profiler::render()})

globalStart

Number protected

Time the profiler was included. This is used to calculate time-from-start values for all methods as well as total running time.

init

Boolean protected

Used to insure that the {@link init} method is only called once.

parser

Parser

The parser instance

profilerKey

String protected

Used to identify when some methods are accessed internally versus when they're used externally (as an api or so)

sqlProfile

ProfilerSQLNode protected

Tracks the current SQL note

topNodes

Array protected

List of all top-level step nodes

totalQueryTime

Number protected

Total amount of time used in SQL queries

trivialThreshold

Number protected

Percentile boundary for trivial execution times

trivialThresholdMS

Number protected

Execution time cut off value for trivial/non-trivial nodes