Browser profiling provides visibility into how your application behaves in your users' browsers, helping you understand root causes behind unresponsive applications at page load or during the page life cycle. Use profiling data alongside RUM insights to identify which code executes during a Long Animation Frame (LoAF) and how JavaScript execution and rendering tasks impact user-perceived performance.

To get started, enable browser profiling in your RUM SDK configuration. After enabling it, click on a profiled event sample to see detailed profiling data.

Setup

Step 1 - Set up RUM

To start collecting data, set up RUM Browser Monitoring.

Step 2 - Configure the profiling sampling rate

1. Initialize the RUM SDK and configure profilingSampleRate, which determines the percentage of sessions that are profiled (for example, 25% means profiling runs on 25 out of 100 sessions).

   Copy

   import { datadogRum } from '@datadog/browser-rum'
   
   datadogRum.init({
     clientToken: '<CLIENT_TOKEN>',
     applicationId: '<APPLICATION_ID>',
     site: 'datadoghq.com',
     //  service: 'my-web-application',
     //  env: 'production',
     //  version: '1.0.0',
     profilingSampleRate: 25,
     trackLongTasks: true,
     trackUserInteractions: true,
   })
   

2. Configure your web servers to serve HTML pages with the HTTP response header Document-Policy: js-profiling:

   Copy

       app.get("/", (request, response) => {
           … 
           response.set("Document-Policy", "js-profiling");
           …
       });
   

3. Set up Cross-Origin Resource Sharing (CORS) if needed.

   This step is required only if your JavaScript files are served from a different origin than your HTML. For example, if your HTML is served from cdn.com and JavaScript files from static.cdn.com, you must enable CORS to make JavaScript files visible to the profiler. For more information, see the Browser profiling and CORS section.

   To enable CORS:

   • Add a crossorigin="anonymous" attribute to <script/> tags

   • Make sure that JavaScript response includes the Access-Control-Allow-Origin: * HTTP header (or the proper origin value)

     Copy

     app.get("/", (request, response) => {
         … 
         response.header("Access-Control-Allow-Origin", "*");
         response.header("Access-Control-Allow-Headers",
         …
     });
     

Explore profiling

Within the Sessions Explorer

Profiling data is captured on long tasks and rolls up to actions, views, vitals, and sessions. Use @profiling.has_profile to filter to profiled events and understand what code ran and how it affected the user's experience. This is available for sessions, views, actions, vitals, and long tasks.

• View panel: Profiling data in a new tab.

• Long Task panel: Profiling data in the performance tab.

• Vitals panel: Profiling data in a new tab.

• Action panel: Profiling data in a new tab.

Within the Profiling page

The Profiling page, found thorugh the top bar navigation, lets you analyze profiling data across sessions in one place. Use it to spot system level patterns, compare top-consuming functions, and prioritize optimizations instead of inspecting profiled sessions one by one. The guided experience walks you through:

1. Focus on views: Choose the views you'd like to analyze.
2. Select a measurement: Pick a Core Web Vital, custom vital, or RUM action to dive into.
3. Refine your selection: Narrow to the most relevant slice of data by percentile or time range so you focus on the worst-performing or most critical segment.
4. Investigate slowest functions: Review which functions consume the most time in the aggregated profile so you can prioritize what to optimize first.
5. View the flame graph: Explore the call hierarchy to see how those functions relate and where time is spent across the stack.

Within the Optimization page

The Optimization page surfaces profiling data in several contexts:

• In the Troubleshoot section, Datadog samples long tasks across multiple views to identify your top contributing functions. Use this overview to find where JavaScript execution time is spent and which functions block the main thread, then optimize those functions to improve responsiveness.

• Within the Event Waterfall, any long task that includes profiling data is marked with a yellow profiling icon. Click one of these long task events to open a Long Task view panel with detailed profiling data. Use this panel to identify blocking functions, trace their call stacks, and understand how script execution contributes to poor responsiveness.