Observing Long Tasks with PerformanceObserver

The longtask entry type reports any block of main-thread work that ran for 50ms or longer without yielding, which is the canonical signal for input that feels stuck and frames that get skipped. This builds on PerformanceObserver API Patterns, part of Rendering Performance Metrics and Tooling, and it is the field-data foundation under the lab metric Total Blocking Time.

The 50ms Threshold

The browser considers a task “long” once it occupies the main thread for at least 50ms. The number is not arbitrary: while a task runs, the thread cannot service input, run requestAnimationFrame callbacks, or composite. Past ~50ms, the user perceives the interface as unresponsive and any animation in flight has already missed several 16.6ms frames. Anything below 50ms is not emitted as a long task at all, so the entry type is a coarse but reliable “the thread was stuck” alarm.

// Minimal reproduction: one synchronous loop that blocks for ~120ms
button.addEventListener('click', () => {
  const data = []
  for (let i = 0; i < 5_000_000; i++) {
    data.push(Math.sqrt(i) * Math.random()) // ❌ never yields — main thread frozen
  }
  render(data) // input, rAF, and compositing are all starved until this returns
})

Reading the Entry and Its Attribution

A longtask entry gives you startTime, duration, and an attribution array. The attribution does not name the exact function — that would require source-level instrumentation — but it does tell you the container responsible: the same-origin frame, an <iframe>, or an embedded ad. name is one of self, same-origin-descendant, cross-origin-descendant, and so on, which is enough to decide whether the stall is your code or a third party.

const obs = new PerformanceObserver((list) => {
  for (const task of list.getEntries()) {
    const attr = task.attribution[0] // TaskAttributionTiming
    report({
      duration: task.duration,        // ms the thread was blocked
      blockingTime: task.duration - 50, // contribution to TBT
      container: attr?.containerType,  // 'window' | 'iframe' | ...
      src: attr?.containerSrc,         // which frame, if any
    })
  }
})
obs.observe({ type: 'longtask', buffered: true }) // replay tasks fired during load

Relation to Total Blocking Time

Total Blocking Time sums, across every long task in a window, the part of each task that exceeds 50ms. A 120ms task contributes 70ms of blocking time; a 51ms task contributes 1ms. This is why one monolithic task is far worse than several short ones of the same total length: the threshold subtraction punishes long tasks super-linearly. TBT measured in the lab and the live longtask stream are two views of the same underlying main-thread occupancy, which is why long tasks correlate so tightly with the Total Blocking Time that lab tooling reports — see Automating Lighthouse CI Performance Budgets.

Debugging Trace

In a Performance recording, a long task appears as a single wide block in the Main lane with a red corner flag. The PerformanceObserver output lines up with it:

[Main Thread — click handler]
├─ Event: click .......................... 0.3ms
├─ Task (Function Call) ................. 118.0ms  ▣ LONG TASK (red flag)
│    └─ blocking time = 118 − 50 = 68ms  → added to TBT
├─ (rAF callback delayed) ................ queued, not run
└─ Composite Layers ...................... blocked until task returns
   Frame total: 118.6ms — 7 frames dropped at 60fps

PerformanceObserver longtask entry:
  { startTime: 4210.2, duration: 118, attribution: [{ containerType: 'window' }] }

The seven dropped frames are the visible symptom; the single 118ms task is the cause.

The Fix: Break Up the Task

Yield to the event loop so the browser can interleave input, rendering, and your work. The cleanest primitive is scheduler.yield() where available, falling back to chunking with setTimeout or await-ing a message-channel turn. The goal is that no synchronous slice exceeds the frame budget.

// ✅ Each chunk stays under one frame; the thread yields between chunks
button.addEventListener('click', async () => {
  const data = []
  const CHUNK = 100_000
  for (let i = 0; i < 5_000_000; i++) {
    data.push(Math.sqrt(i) * Math.random())
    if (i % CHUNK === 0) {
      // Hand the main thread back so input + compositing can run
      if ('scheduler' in window && scheduler.yield) await scheduler.yield()
      else await new Promise((r) => setTimeout(r))
    }
  }
  render(data)
})

For genuinely CPU-bound work, move the loop into a Worker so the main thread never blocks at all. Long tasks frequently hide a second, sneakier cost — a forced synchronous layout inside the loop, where reading offsetTop after a style write flushes layout on every iteration. If chunking alone does not flatten the task, profile the slice for interleaved Layout events and batch the reads and writes.

Verification Checklist

• No longtask entries fire during the click-to-render interaction.
• The Main lane shows multiple short tasks with gaps, not one wide red-flagged block.
• requestAnimationFrame callbacks run on schedule throughout the work.
• TBT in the lab run drops below the 200ms budget after chunking.

What the Attribution Field Can and Cannot Tell You

The Long Tasks API flags any task over 50ms, but its attribution array is coarser than people expect: it identifies the container (the top-level document or an iframe) responsible for the task, not the exact function. That is enough to answer “is this our code or a third-party frame?” — a genuinely useful triage question — but not “which handler?” For finer attribution you pair it with the Long Animation Frames API, which breaks a slow frame down by script and source location. The practical pattern is to use Long Tasks as a cheap, widely-supported alarm that something blocked the main thread, then reach for LoAF or a Performance trace to localise the cause once the alarm fires.

Frequently Asked Questions

Related Guides

• PerformanceObserver API Patterns — the parent guide covering buffered replay, entry types, and observer lifecycle.
• Automating Lighthouse CI Performance Budgets — turn the TBT signal from long tasks into a CI gate.
• Forced Synchronous Layouts — the layout-thrash pattern that hides inside many long tasks.
• Rendering Performance Metrics and Tooling — how field metrics and lab tooling fit together.