#Performance Monitoring Overview

This overview helps you quickly build a mental model and understand common workflows for performance monitoring. It explains how the Performance API and Timing Flag work together to create a closed loop from marking to analysis: Mark → Collect → Report → Analyze.

#Mental Model and Closed-Loop Workflow

The goal of monitoring is to ensure that critical moments in your page's lifecycle can be accurately recorded, reported, and analyzed, allowing you to quickly trace issues back to the source code or specific UI locations. Centered around the Lynx rendering pipeline and standardized events, we recommend the following closed-loop workflow:

• Mark: Use a Timing Flag (__lynx_timing_flag) on critical UI nodes or key data updates to define the rendering pipelines you need to monitor. The special flag __lynx_timing_actual_fmp can additionally generate the ActualFMP metric. For details, see Marking Rendering Pipelines.
• Collect: Register a PerformanceObserver as early as possible on the front end (e.g., to listen for metric.fcp, pipeline, etc.), or consume events via asynchronous callbacks on the client side. For details, see Collecting Performance Events.
• Report: Report key metrics and events to your data platform using consistent naming and fields.
• Analyze: Analyze production data, using PipelineEntry.identifier (the Timing Flag) and event timelines to trace problems back to the corresponding modules or data flows for debugging and review.

Recommended minimum set of tracking points (for a basic production setup):

• metric: fcp (required), actual_fmp (when you need to measure the "first meaningful data paint")
• pipeline: loadBundle (for the initial screen rendering), and the pipelines associated with your critical Timing Flags.

#Feature Positioning

#Performance API

• Positioning: A standardized performance interface covering four event types: init, metric, pipeline, and resource.
• Triggering and Retrieval: PerformanceEntry objects are generated by the Lynx Engine. The front end subscribes to them via PerformanceObserver.observe([...]), and the client receives them through the onPerformanceEvent(entry) callback on an asynchronous thread.
• Typical Uses:
  • Obtaining standard metrics for initial screen rendering and key updates (FCP, ActualFMP).
  • Combining multiple events to build custom business metrics (e.g., the waiting time from the end of the initial screen rendering to the first important data update).

#Marking Lynx Pipeline

• Positioning: A unique identifier used to mark a rendering pipeline for monitoring. It triggers the generation of a PipelineEntry and can also trigger a MetricActualFmpEntry.
• Usage:
  • The recommended method is to set the __lynx_timing_flag attribute on a UI element.
  • Setting the value to __lynx_timing_actual_fmp additionally generates an ActualFMP metric event.
• Behavior and Limitations:
  • The same Timing Flag is only effective the first time it is encountered (repeated markings will not trigger the callback again).
  • It is ineffective on tags that do not have a UI node, such as <inline text/>, <block/>, and <template/>.

#Common Workflows

• Mark critical stages → Get key moments via PipelineEntry/ActualFMP → Combine with LoadBundleEntry/FCP to establish a baseline for initial rendering and updates → Report → Filter high-latency samples by different dimensions → Trace back to the component/data flow corresponding to the mark to identify the cause.
• Lazy-loaded component performance → Set a Timing Flag on important nodes and listen for the corresponding PipelineEntry → Combine with the page's loadBundle event to create an end-to-end performance profile → Optimize the resource loading and layout stages separately.