Understanding Timelines Profiler/Premium/Enterprise

Note

This section describes how to read the timeline of a profile. You can also visualize a profile as a call graph.

The timeline representation of a profile is a great way to analyze the wall-clock time of the most important function calls, which are represented as event blocks.

Like for the call-graph, Blackfire filters unimportant calls to only display the most significant ones. Blackfire also automatically understands which libraries you are using and groups similar calls as metrics that show up in the left pane.

  • Hovering on a metric emphasizes related blocks and displays resource consumption information about them;
  • Hovering on a block displays more information about resource consumption.
/docs/blackfire-timeline.png

Memory Consumption

The global memory usage is displayed in the navigation panel as a light blue graph. It represents the growing peak memory enveloppe. A sudden increase can give you a hint on which function calls consume more memory.

Note

On PHP profiles, the memory graph is an always-growing-graph. As it represents the peak memory, you can never see it decreasing, even if you manually clear your application memory.

Timeline Threshold

The threshold timeline metric highlights one or several event blocks in the Timeline view. It is designed to draw your attention on something that Blackfire considers significant.

The Threshold Value

The timeline threshold is a value computed when a profile is triggered. When you ask for a profile with a Blackfire client, e.g. with Blackfire browser extension, it first fires a pre-flight request that will not be profiled. The duration of this request is taken as a reference in order to calculate the threshold value.

The threshold value is calculated as 1% of the duration of the pre-flight request.

This value is displayed in the metadata panel of your profile that you can view by hovering on your profile name.

/docs/timeline-threshold.png

This value is a reference for Blackfire in order to detect significant events for you.

Significant Events

Considering the threshold value, significant events are function calls that are worth paying attention to, an event being usually considered significant when its exclusive wall-time exceeds the threshold value.

Custom Metrics Premium/Enterprise

The timeline only displays relevant metrics that are configured and curated by the Blackfire team.

But you can also add more information by creating your own custom metrics ready for the timeline.

Markers

Markers allow you to visualize cue-points you explicitly define in your code. Call \BlackfireProbe::addMarker($markerName) to define a marker:

/docs/blackfire-marker.png

Note

\BlackfireProbe::addMarker() is production safe. When no profile is requested, this function call operates as a no-op instruction.