The Unofficial Chrome Trace Event Manual

Chrome tries to read another chunk of your HTML.

A DevTools Performance recording does not contain this event. Record blink with your own trace configuration to get it.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

Blink's HTML parser tests whether it is able to tokenize, and tokenizes when it is, on the renderer's main thread.

Arguments

Observed 145,565 times on 182 of 300 sites: 59,689 complete slices and 42,935 flow pairs, which carry no arguments.

Behaviour

Three events cover this work at three levels, nested inside one another:

PumpTokenizerIfPossible    the gate: may the parser run?          blink
  PumpTokenizer            the chunk loop: run until the budget   blink
    ParseHTML              the parse itself                       devtools.timeline

Chrome calls the outer gate whenever something has happened that might allow parsing to continue: more bytes have arrived from the network, a blocking script has finished running, document.write() has pushed markup into the stream, or the document is being brought to a close. Each of those is a reason to go and look, and looking is what this event records.

The answer is often no. The gate checks whether a blocking stylesheet has arrived, then tests the parser's state, and if the parser is stopped or paused it returns having consumed nothing at all. That is what IfPossible is doing in the name, and it is why a slice here is not evidence that any markup was read. A gate that contains no ParseHTML did nothing.

When the parser does run and then yields, having spent its budget, the gate schedules the next attempt before returning.

Derivations

Each attempt is flow-linked to the one it schedules, so following that chain from the first gives you every attempt on a single document in order: the ones that parsed, the ones that did nothing, and the time between them. DevTools will not draw that for you at any zoom level.

The transitions are where the value is. Find a run of gates that did nothing followed by one that parsed, and whatever completed in between is what unblocked the parser, usually a ResourceFinish for a script or a stylesheet. That is root-cause attribution for a stalled parse, from the trace rather than from inference.

Traps

All three events are on the blink category, which a DevTools Performance recording never asks for. The entire chain is invisible in the Performance panel, so this is a Perfetto or custom trace configuration job.

HTMLDocumentParser::PumpTokenizer, the middle of the three, is where endLine ends up for the ParseHTML inside it. See the traps on that entry.

{
  "name": "HTMLDocumentParser::PumpTokenizerIfPossible",
  "cat": "blink",
  "ph": "X",
  "ts": 1102933188,
  "dur": 6372,
  "tdur": 3193,
  "tts": 35974,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "parser": "0x1df400529100"
  }
}

See also ParseHTML · EvaluateScript

categories

blink

usage

high

duration

typical

references

html_document_parser.cc

Chrome reads a downloaded stylesheet and builds the CSSOM from it.

Spec

Blink's CSS parser decodes one fetched stylesheet and parses it into rules, on the renderer's main thread.

Arguments

Observed 3,119 times on 182 of 300 sites.

Behaviour

"Author" is the CSS specification's word for the stylesheets a page supplies itself, as opposed to the browser's built-in defaults and any user stylesheet. This event covers those, and only the ones Chrome fetched: the function takes a CSSStyleSheetResource, so a <link rel=stylesheet> or an @import reaches it and an inline <style> does not. Inline CSS is parsed by a different function that writes nothing to the trace at all.

The slice is scoped to the whole function, so its duration includes decoding the downloaded bytes into text as well as parsing that text into rules. The URL is the only thing recorded: there is no size and no rule count.

Derivations

Chrome keeps a cache of already-parsed stylesheets, and a sheet served from it never reaches this function. So the stylesheet URLs that appear in the network events but not here are the ones that were reused rather than reparsed. That set is not visible anywhere else in a trace, and on a site serving the same CSS across navigations it is the difference between the parse cost you measured and the parse cost a first-time visitor pays.

Traps

A page that inlines all of its CSS produces none of these events, so an absence here is not evidence that stylesheet parsing was cheap.

The duration understates the work. Chrome parses these sheets with declaration-block parsing deferred, so the contents of each rule are not read until something first matches against them, and that cost appears later under style recalculation instead.

styleSheetUrl is the only argument and trace_engine does not declare it, so anything built on the package's types sees an event with no data on it.

{
  "name": "ParseAuthorStyleSheet",
  "cat": "blink,devtools.timeline",
  "ph": "X",
  "ts": 1109076924,
  "dur": 415,
  "tdur": 389,
  "tts": 45866,
  "pid": 8475,
  "tid": 8475,
  "args": {
    "data": {
      "styleSheetUrl": "https://cdn.privacy-mgmt.com/Notice.1c267.css"
    }
  }
}

See also ParseHTML · ResourceFinish

categories

blink, devtools.timeline

usage

moderate

duration

long

undeclared args

args.data.styleSheetUrl

references

style_sheet_contents.cc, inspector_trace_events.cc

Chrome reads your HTML and builds the DOM from it.

Spec

Blink's HTMLDocumentParser runs its tokenizer and tree builder over part of the document, on the renderer's main thread.

Arguments

Observed 58,996 times on 182 of 300 sites.

Behaviour

Chrome parses a document in bursts rather than in one continuous stretch, and each ParseHTML brackets a single burst. Chromium calls a burst a pump, which is where the sibling event HTMLDocumentParser::PumpTokenizerIfPossible takes its name.

A burst ends for one of two reasons. The parser reaches a synchronous <script> and has to wait while it is fetched and executed, or it spends its token budget: the first two bursts of a document are capped at 250 tokens each, after which the cap is lifted and the parser tries to consume everything remaining in one task. A page therefore produces a chain of these events separated by gaps, and those gaps have two quite different causes that the event alone does not tell apart.

Derivations

ts plus dur of one event, to ts of the next, is time the parser spent blocked rather than parsing, and the next event's startLine is the line of your HTML it was stuck at. Sum those gaps across a load and you have the total the parser spent waiting, located in your own source rather than inferred from where the <script> tags sit.

Short gaps are the parser rescheduling itself after spending its token budget; long ones are a script being fetched and executed. An EvaluateScript between the two events confirms which.

Traps

endLine is not on this event, though trace_engine declares it. Blink does emit it, but the begin and end pairs of ParseHTML and HTMLDocumentParser::PumpTokenizer interleave rather than nest, so each end closes the other's slice. endLine arrives on PumpTokenizer, and PumpTokenizer's own counters arrive here as parsed_bytes and parsed_tokens. Record the blink category if you want the end line.

A stackTrace means JavaScript was on the stack when the burst began, which is true of nearly every parse on a modern site. It does not identify innerHTML or document.write. The field is gated behind disabled-by-default-devtools.timeline.stack, which also gates sampleTraceId and makes every burst take a V8 CPU profiler sample it would not otherwise take.

parsed_bytes counts UTF-16 code units in the parser's buffer, which is not the number of bytes the network delivered.

{
  "name": "ParseHTML",
  "cat": "devtools.timeline",
  "ph": "X",
  "ts": 1102952623,
  "dur": 86,
  "tdur": 86,
  "tts": 47032,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "beginData": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "sampleTraceId": 6909218608594550,
      "stackTrace": [
        {
          "columnNumber": 20,
          "functionName": "",
          "lineNumber": 78,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        }
      ],
      "startLine": 0,
      "url": "http://127.0.0.1:8801/"
    },
    "parsed_bytes": 1960,
    "parsed_tokens": 420
  }
}

See also HTMLDocumentParser::PumpTokenizerIfPossible · EvaluateScript

categories

devtools.timeline

usage

moderate

duration

typical

undeclared args

args.parsed_bytes, args.parsed_tokens, args.beginData.stackTrace[].columnNumber, args.beginData.stackTrace[].functionName, args.beginData.stackTrace[].lineNumber, args.beginData.stackTrace[].scriptId, args.beginData.stackTrace[].url

references

inspector_trace_events.cc, html_document_parser.cc, source_location.cc, v8-stack-trace-impl.cc, v8-debugger.cc, segmented_string.h

This event tells you a resource request has finished.

Spec

Blink closes out a request, on the thread that owned the fetch.

Arguments

Observed 36,088 times on 182 of 300 sites.

Behaviour

The terminal event of a request's trace record, and the only one that says whether the request failed.

Two call sites write the same event name through one payload builder. The success path forwards real values. The failure path hardcodes a null timestamp, didFail: true, and zero for both lengths, so an abort that moved bytes reports none: one capture emitted six data events totalling 35 bytes and then closed with encodedDataLength: 0.

A request blocked before a loader exists, by CSP or a mixed-content check, emits no finish event at all.

Derivations

Whether a request failed. didFail appears nowhere else in the lifecycle.

The cache tier, given a success: a ResourceMarkAsCached on the same request id means Blink's memory cache; fromCache: true on the response with no such marker means the HTTP disk cache; neither means the network.

Body size on the wire, on network loads only: this event's encodedDataLength minus the response event's. Verified to within a few bytes of content-length on HTTP/3. It is meaningless on cache hits, on 304s, and wherever the response reports -1.

How busy the thread was when the request landed: ts minus finishTime is the emitting thread's queueing lag. In one trace the six largest gaps, about 88 ms each, all fell inside a single 87.5 ms script task.

Traps

decodedBodyLength / encodedDataLength is not a compression ratio. The denominator includes the header block, so an uncompressed file reads below 1.0, and by more the smaller it is. This entry's own example event is the trap: 3,880 over 4,073 reads as 0.95 "compression" for a fixture file that is exactly 3,880 bytes on disk and is served with no compression of any kind. The field that would make the ratio honest exists in Chromium, is carried all the way into Blink, and is never written to the trace. The ratio is undefined on cache hits, 0/0 on failures, and 0.0 on a 304.

encodedDataLength: 0 means one of four things: a genuine disk-cache hit, a hardcoded zero for a memory-cache hit, a hardcoded zero for a failure that may have transferred plenty, or an empty body. Summing it undercounts every aborted request by its full size.

A missing finishTime is not a failure signal. Across eight traces, 117 absences split 93 memory-cache hits and 24 failures and nothing else. A present finishTime does not mean bytes came off the wire either, because disk-cache hits have one.

ts is not when the download ended. It is when the probe ran, which waits for the current task on that thread. Use finishTime for duration.

The payload carries no url and no frame, so it cannot be attributed to an iframe without joining on the request id. There is no error code, no error text and no distinction between failed, cancelled and aborted.

trace_engine types finishTime as required. It is absent on roughly one event in eight. Guard it.

{
  "name": "ResourceFinish",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1102939672,
  "tts": 39266,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "decodedBodyLength": 3880,
      "didFail": false,
      "encodedDataLength": 4073,
      "finishTime": 1102.922565,
      "requestId": "F19F977AB13E669964965F7427E6F7B2"
    }
  }
}

See also ResourceSendRequest · ResourceReceivedData · ResourceMarkAsCached

categories

devtools.timeline

usage

moderate

references

url_loader_completion_status.h, inspector_trace_events.cc, resource_loader.cc, url_loader.cc, NetworkRequestsHandler.ts

Chrome already had the file in memory and never asked for it.

Spec

Blink satisfies a subresource request out of the renderer process's own memory, on the renderer's main thread.

Arguments

Observed 2,959 times on 175 of 300 sites.

Behaviour

Not the HTTP cache. The guard is Blink's own memory cache, which covers two things: an entry in the process-wide MemoryCache, and a resource Blink materialised in-process such as a data: URI or an MHTML subresource. The second kind fires on first use, before any cache could have mattered.

The marker sits at a fixed slot inside a burst of five events that Blink manufactures for a request that never left the process: send, this marker, response, data, finish. The whole burst is typically 20 to 150 microseconds.

It only fires the first time a given document takes a url out of the process-wide cache. A second request for the same url in the same document emits nothing, so the event counts distinct memory-satisfiable urls per document, not reuses. Frames only; workers never emit it.

Derivations

Join on the request id to ResourceSendRequest for the url, frame and priority. This event carries none of them, so any rule phrased over "the url of this event" cannot be implemented.

An http or https scheme marker means another document in the same renderer process already held those bytes. Usually an earlier navigation, but a same-origin iframe in the same page load does it too.

On the matching ResourceFinish: no finishTime, encodedDataLength of zero, and didFail false. Do not add decodedBodyLength > 0 to that fingerprint, because it is zero for every data: URI.

Traps

It is not a repeat-view signal. Across eight cold loads with fresh profiles, 38 of these fired and 35 were inline data: URIs. One site produced 18 on a cold profile.

It is not the opposite of fromCache either. The two are independent and co-occur routinely, because a memory-cache entry replays the response it was stored with: if that response came from the disk cache, both appear on the same request. Measured at 6 of 8 in a warm-profile capture, and on a cold load of reddit.com.

The replayed ResourceReceiveResponse looks like a real network response, with a status code, protocol and socket id all carried over from the original fetch, and a timing block pointing backwards.

Whether the event appears at all can depend on your recorder. Chrome's two hard-coded 1x1 transparent placeholder GIFs emit the full burst when a CDP client is attached and nothing under --trace-startup, so the same page produces a different population under Puppeteer than under Perfetto.

A deferred resource does not emit it. An inline data: font without rel=preload, or an inline data: image with loading="lazy", loads normally and produces four events with no marker.

{
  "name": "ResourceMarkAsCached",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1119408173,
  "tts": 531693,
  "pid": 8591,
  "tid": 8591,
  "s": "t",
  "args": {
    "data": {
      "requestId": "8591.369"
    }
  }
}

See also ResourceReceiveResponse · ResourceFinish · ResourceSendRequest

categories

devtools.timeline

usage

moderate

references

inspector_trace_events.cc

Chrome hands part of a downloaded file to the page.

Spec

Blink hands a span of response-body bytes to the loader's observer, on the thread that owns the fetch.

Arguments

Observed 73,689 times on 182 of 300 sites.

Behaviour

This is a delivery notification, not an arrival notification. The bytes were already in the renderer process, and on two of the four code paths that emit it the whole body had finished downloading before the first event was written.

Four emitters reach it: document subresources, worker fetches, the main document itself, and a synthetic single event replaying a memory-cache hit. Each builds the span differently, which is why one event is neither one network chunk nor one fixed-size read.

Some requests carry a full body and emit nothing at all. A 204 or a 304 has no body; a fetch() resolved to a blob, a stream read by script, or a streamed script all have their body drained by someone else before the loader reads it. Those bytes may reappear later under a different request id.

Derivations

Summing over one request id gives the decompressed bytes received so far. It is the only byte figure available for a request that was still in flight when the recording stopped, and the only place an aborted request's bytes are visible at all, since ResourceFinish reports zeros for a failure.

Gaps between consecutive events on one request, lined up against main-thread tasks, show the renderer starving its own download. The reads happen in renderer tasks, so a blocked thread pushes them later with no change on the network: 11 to 44 microseconds from response to first data on quiet requests in one trace, against 41,802 microseconds on a busy one in the same load.

Traps

encodedDataLength here is decoded body bytes, not wire bytes. A gzipped stylesheet that was 255 bytes on the wire reports 200,020 here and 473 on ResourceFinish: a 424-fold gap between two fields with the same name. "Encoded" is Blink's raw-bytes-versus-text axis, not HTTP's content encoding. Summing these gives decoded size and never transfer size.

The timestamp is not a network timestamp. On the background-processed path the entire response, data and finish sequence can land in a burst of about 100 microseconds after the body already downloaded and V8 already compiled it off-thread.

Event count is not a streaming signal in either direction. One event can mean a small body, a busy main thread, a pre-assembled buffer or a cache replay. One or two is normal: 16 of 21 body-bearing requests in one trace emitted exactly one, and a 2 MiB stylesheet produced six.

Chunk sizes are buffer artefacts. The only real constant is a roughly 1 MiB per-task budget, and it binds only bodies the loader reads itself: a fetch() body pulled by JavaScript produced a single 1,114,112-byte event.

A memory-cache hit emits one event carrying the whole resource, and looks exactly like a fast network response unless you notice the ResourceMarkAsCached beside it.

DevTools collects these events and never reads them. Every byte figure in the Performance panel comes from ResourceFinish.

{
  "name": "ResourceReceivedData",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1102926911,
  "tts": 30693,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "encodedDataLength": 3880,
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "requestId": "F19F977AB13E669964965F7427E6F7B2"
    }
  }
}

See also ResourceReceiveResponse · ResourceFinish

categories

devtools.timeline

usage

moderate

references

inspector_trace_events.cc, resource_loader.cc

Chrome has the response headers for a request.

Spec

Blink takes delivery of a response head, on the thread that owns the fetch.

Arguments

Observed 34,142 times on 182 of 300 sites.

Behaviour

One event per request, and the only one carrying the status code, MIME type, protocol, headers, cache flags, socket identity and the network timing block. Nothing else in the lifecycle repeats any of it.

Redirect hops do not produce one. Only the final response does.

It fires for Blink memory-cache hits too, where it replays a stored response object rather than describing a fetch. In that case ResourceMarkAsCached fires first on the same request id, and everything in the payload describes the earlier load.

Derivations

The timing block is absolutely placeable, because requestTime is seconds on the same monotonic clock as ts. Every other offset in the block is milliseconds relative to it, so any phase lands at requestTime 1e6 + offset 1e3 in trace units.

That gives you when the headers really arrived, and subtracting it from ts gives you how long Blink took to pick them up: a main-thread congestion signal you cannot get anywhere else.

Server think time is receiveHeadersStart - sendEnd, which is what DevTools computes.

Connection setup is dnsEnd - dnsStart, connectEnd - connectStart, sslEnd - sslStart. These are blocking times, not occurrence times, so a zero means the request did not wait, as with a preconnected socket.

Traps

encodedDataLength here is five different numbers. On a fresh network response it is the response header bytes as they went over the wire, so on h2 and h3 it is the compressed HEADERS frame and lands far below the header text: a 204 with around 809 bytes of headers reported 57. It is 0 on an unvalidated disk-cache hit and on data:, and -1 on blob:, chrome:// and chrome-extension:. On a memory-cache replay it is the entire wire transfer of the original load, body included: one stylesheet reported 189 on the fetch that got it and 5,214 on the replay.

fromCache is not a flag. It is derived from two timestamps, true whenever the response predates the request, which is why HTTP/2 pushed resources and service-worker responses report it. A 304 revalidation reports false, and reports its status as 200, because the 304's headers are merged into the stored entry.

fromCache: true and ResourceMarkAsCached are not mutually exclusive. A memory-cache entry replays whatever response it was stored with, so one that originally came off the disk cache sets both. DevTools marks such a request as disk-cached and memory-cached at once, deliberately.

On a memory-cache replay the timing block belongs to the earlier fetch, measured 1.3 seconds stale in one capture and 2.5 seconds in another, and connectionId is a closed socket. There is no flag on this event to tell you; you have to join to ResourceMarkAsCached. How much of a trace is affected depends entirely on how you recorded: a single navigation has almost none, a two-navigation recording can be three quarters stale.

ts is not when the headers arrived. No timestamp is passed to the trace macro, so it is when the Blink probe ran, always at or after the headers completed and by tens of milliseconds on a busy thread.

pushStart and pushEnd are absolute seconds with a 0 sentinel, sitting among fifteen millisecond offsets that use -1.

protocol can be a url scheme. Filter data, blob, chrome and chrome-extension out of any protocol histogram.

Server think time understates on any origin sending 103 Early Hints, because receiveHeadersStart can be the 1xx, and the field that would correct it is recorded by Blink and never written to the trace.

{
  "name": "ResourceReceiveResponse",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1236061260,
  "tts": 450196,
  "pid": 10309,
  "tid": 10309,
  "s": "t",
  "args": {
    "data": {
      "cacheStorageCacheName": "devsite.pwa_RUNTIME_v2.1",
      "connectionId": 0,
      "connectionReused": false,
      "encodedDataLength": 0,
      "frame": "614FC5655E48B642B0235ABCA128B0C6",
      "fromCache": true,
      "fromServiceWorker": true,
      "headers": [
        {
          "name": "content-encoding",
          "value": "gzip"
        },
        {
          "name": "age",
          "value": "161242"
        },
        {
          "name": "report-to",
          "value": "{\"group\":\"devrel-devsite\",\"max_age\":2592000,\"endpoints\":[{\"url\":\"https://csp.withgoogle.com/csp/report-to/devrel-devsite\"}]}"
        },
        "... [16 more items]"
      ],
      "mimeType": "image/svg+xml",
      "protocol": "h2",
      "requestId": "10309.250",
      "responseTime": 1789291418105.672,
      "serviceWorkerResponseSource": "cacheStorage",
      "statusCode": 200,
      "timing": {
        "connectEnd": -1,
        "connectStart": -1,
        "dnsEnd": -1,
        "dnsStart": -1,
        "proxyEnd": -1,
        "proxyStart": -1,
        "pushEnd": 0,
        "pushStart": 0,
        "receiveHeadersEnd": 2.19,
        "receiveHeadersStart": 2.19,
        "requestTime": 1236.054677,
        "sendEnd": 0.002,
        "sendStart": 0.002,
        "sslEnd": -1,
        "sslStart": -1,
        "workerReady": 0.118,
        "workerStart": 0.002
      }
    }
  }
}

See also ResourceSendRequest · ResourceReceivedData · ResourceFinish · ResourceMarkAsCached

categories

devtools.timeline

usage

moderate

undeclared args

args.data.timing.connectEnd, args.data.timing.connectStart, args.data.timing.dnsEnd, args.data.timing.dnsStart, args.data.timing.proxyEnd, args.data.timing.proxyStart, args.data.timing.pushEnd, args.data.timing.pushStart and 13 more

references

load_timing_info.h, resource_load_timing.cc, inspector_trace_events.cc, web_url_response.cc, url_loader_util.cc, url_loader.cc and 3 more

Chrome asks for a file.

Spec

Blink hands a request down to be fetched, on the thread that owns it.

Arguments

Observed 34,467 times on 182 of 300 sites.

Behaviour

For a subresource this is Blink's fetcher passing the request on, before the network service, before DNS, before the socket. The queueing between this moment and the wire is why ResourceReceiveResponse carries a timing block at all.

For the document it is something else entirely. Blink writes it at navigation commit, from DocumentLoader, long after the browser sent the request and after the response headers have arrived. Chromium's own comment at that line reads "The fetch has already started in the browser". Measured on a real site, the renderer's event landed 110 ms after the browser's ResourceWillSendRequest and 0.16 ms before the response.

The payload is the richest of the six and none of the later events repeat it: url, method, resource type, priority, and where the request came from. Redirects emit one event per hop on a shared request id.

Derivations

Attribution. initiator.url falls back to stackTrace[0].url, which is exactly what DevTools does before matching the result against other requests to build a dependency tree rather than a flat waterfall.

A render-blocking audit: filter renderBlocking for blocking and in_body_parser_blocking to get the requests that actually held up first paint.

Queueing for a subresource: requestTime on the response event, minus this event's ts.

Traps

Never compute document time to first byte from this event. It is a commit timestamp, and the answer comes out around 0.1 ms.

Stack depth measures your recorder, not the page. V8 captures one frame unless a client has the Runtime domain enabled, and then up to 200. The same fetch() from an eleven-frame call chain gave eleven frames under Puppeteer and one frame under --enable-tracing. Never compare stack depth across traces made with different tools.

The stack itself is gated on disabled-by-default-devtools.timeline.stack. Without that category stackTrace and sampleTraceId are simply gone, and nothing in the output distinguishes that from no stack being available.

renderBlocking is not a property of the resource. It is whatever the code path that triggered this particular request handed over, so the same font url carries non_blocking on a cold load and loses the field entirely on a memory-cache hit. Absent is not a third value.

isLinkPreload means an explicit rel=preload directive, not "Chrome preloaded this". Anything the preload scanner found speculatively is false.

priority is the priority at send time. A separate ResourceChangePriority event can supersede it.

fetchPriorityHint is present on every event because auto is written unconditionally. Only low and high carry author intent.

On a redirecting navigation the earlier events' urls are not reliably the intermediate hops. Count the events for the hop count; do not reconstruct the chain from them.

{
  "name": "ResourceSendRequest",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1236185423,
  "tts": 104095,
  "pid": 10389,
  "tid": 10389,
  "s": "t",
  "args": {
    "data": {
      "fetchPriorityHint": "auto",
      "frame": "7EC3978477DE6DAE91460AF9D4ECB53A",
      "initiator": {
        "columnNumber": 13,
        "fetchType": "css",
        "lineNumber": 258,
        "type": "parser",
        "url": "https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Lfqf9YdAAAAAKUVvj6y53E_tMMlnj8dt1fpo-FV&co=aHR0cHM6Ly93ZWItZG90LWRldnNpdGUtdjItcHJvZC0zcC5hcHBzcG90LmNvbTo0... [98 more chars]"
      },
      "isLinkPreload": false,
      "priority": "VeryHigh",
      "renderBlocking": "non_blocking",
      "requestId": "10389.14",
      "requestMethod": "GET",
      "resourceType": "Font",
      "sampleTraceId": 4395473783086954,
      "stackTrace": [
        {
          "columnNumber": 81,
          "functionName": "",
          "lineNumber": 736,
          "scriptId": "5",
          "url": "https://www.gstatic.com/recaptcha/releases/BnqMGSY_YP4cCmbNINHpJPkd/recaptcha__en.js"
        },
        {
          "columnNumber": 413,
          "functionName": "",
          "lineNumber": 613,
          "scriptId": "5",
          "url": "https://www.gstatic.com/recaptcha/releases/BnqMGSY_YP4cCmbNINHpJPkd/recaptcha__en.js"
        },
        {
          "columnNumber": 49,
          "functionName": "LX.Bl",
          "lineNumber": 1223,
          "scriptId": "5",
          "url": "https://www.gstatic.com/recaptcha/releases/BnqMGSY_YP4cCmbNINHpJPkd/recaptcha__en.js"
        },
        "... [13 more items]"
      ],
      "url": "https://fonts.gstatic.com/s/roboto/v48/KFO7CnqEu92Fr1ME7kSn66aGLdTylUAMa3yUBA.woff2"
    }
  }
}

See also ResourceWillSendRequest · ResourceReceiveResponse · ResourceFinish

categories

devtools.timeline

usage

moderate

undeclared args

args.data.initiator.fetchType, args.data.initiator.type, args.data.initiator.url, args.data.sampleTraceId, args.data.initiator.columnNumber, args.data.initiator.lineNumber, args.data.stackTrace[].columnNumber, args.data.stackTrace[].functionName and 3 more

references

inspector_trace_events.cc, inspector_network_agent.cc, image_loader.cc, preload_helper.cc, preload_request.cc, resource_fetcher.cc and 7 more

Chrome is about to request a page or an iframe.

Spec

The browser process marks a navigation request as it is about to be sent, on the browser's main thread.

Arguments

Observed 952 times on 182 of 300 sites.

Behaviour

This is the only one of the six request events the browser process writes. The other five come from the renderer, which is visible in the trace itself: this event is process-scoped, "s": "p", while the others are thread-scoped, "s": "t".

It is written for cross-document navigations only, never for a subresource. A page, an iframe and a data: frame all get one; a back-forward cache restore, a prerender activation, a same-document navigation and about:blank do not. Chrome writes it before the URL loader exists and before any service worker sees the request, so a navigation answered offline by respondWith() still produces one.

Redirects produce one event per hop, all sharing a request id. N events means N-1 redirects.

Derivations

This is where a navigation actually started. The renderer's ResourceSendRequest for the same document cannot tell you, because Blink writes that one at commit, once the response is already in hand: measured at 0.014 to 0.092 ms before the response event across six captures.

So honest time to first byte for the main document runs from this event to requestTime + receiveHeadersEnd on ResourceReceiveResponse. In one capture the browser sent at 0 ms, the request reached the server at 92.60 ms after two redirects, headers completed at 129.40 ms, and the renderer wrote its ResourceSendRequest at 132.93 ms.

Consecutive timestamps on one request id give the cost of each redirect hop as the browser experienced it. A hop of a couple of milliseconds is an internal redirect, an HTTP to HTTPS upgrade rather than a round trip. DevTools reads these timestamps in preference to the renderer's.

A request id with this event and nothing else is a navigation that never committed: hung, superseded, a 204, or a download.

Traps

The gap to ResourceSendRequest is not network time. It contains browser dispatch, redirects, the wire, IPC and the renderer's commit. The non-network residual measured 2.7 to 5.0 ms on a warm headless machine and grows when a renderer has to be spawned.

The event does not mean bytes went on the wire. Service-worker-answered navigations and data: frames emit it with no network activity at all.

A failed navigation is not an orphan. A DNS failure still commits an error page, and the renderer emits the full set with the url chrome-error://chromewebdata/.

DevTools will not show you an orphan either: it drops any request with no send event, so you have to read the raw trace.

The request id is the navigation token, 32 uppercase hex characters, shared by every hop and by the renderer's four events for the same document. Subresource ids look nothing like it.

{
  "name": "ResourceWillSendRequest",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1102919608,
  "pid": 8178,
  "tid": 8178,
  "s": "p",
  "args": {
    "data": {
      "requestId": "F19F977AB13E669964965F7427E6F7B2"
    }
  }
}

See also ResourceSendRequest · ResourceReceiveResponse

categories

devtools.timeline

usage

low

references

devtools_instrumentation.cc

Chrome plays an animation or a transition on the page.

Spec

Blink records the play-state changes of one animation object, a CSS animation, a CSS transition or an element.animate() animation, as an async span on the renderer's main thread, with instants for state changes and for a failed handover to the compositor.

Arguments

Observed 18,728 times on 180 of 300 sites.

Behaviour

Every event one animation writes shares an async id, id2.local, so a single animation reads as one span.

The span follows the play state, not the frames. Blink writes the begin when an animation goes from idle, paused or finished to playing, and the end when it goes back. Any other change of state is an instant carrying nothing but state. Iterations write nothing, so a width animation with two iterations produced one begin, one state instant and one end. A pause() followed by play() closes the span and opens a new one on the same id.

A second kind of instant reports a decision about the compositor, the thread that can run an animation without the main thread once it has been handed over. Blink makes that decision in PreCommit, for an animation that is playing and is being started on the compositor. If the handover fails, it writes an instant with compositeFailed, a bitmask of reasons; the reason that stands for an unsupported CSS property also fills unsupportedProperties with the property names. If the handover succeeds, it writes nothing at all. Captures on Chrome 153 from two independent runs agree on which properties fail: width, top, left, margin-left, margin-bottom and box-shadow each wrote a failure, while transform, opacity and background-color wrote none. background-color is in that second group because Chrome paints it through a native paint worklet the compositor can drive; box-shadow has the same machinery, unfinished and off by default.

Only the begin identifies the animation. displayName is the animation's id if script gave it one, otherwise the CSS animation-name, otherwise the transitioned property, and nodeId and nodeName identify the element. Every later event on the span carries a state or a compositor result and nothing else.

The four categories form one group, and recording any of them is enough. A devtools.timeline recording on its own produced the full set.

Derivations

Which animations ran on the main thread, and why. Decode compositeFailed against FailureReason in Chromium's compositor_animations.h and join to the begin on id2.local for the element. Bit 13 is an unsupported CSS property, and it is the only reason that fills unsupportedProperties. Bit 5, the target not being in a compositable state, usually rides along with it, because an element with nothing else worth compositing carries no direct compositing reason on its paint property nodes; the same transition on an element that also runs a composited transform reports bit 13 alone. Read the mask as a set of reasons, not as a number to recognise.

The span is the window in which that animation costs main-thread time. While a width animation was running, the renderer's main thread ran UpdateLayoutTree, Layout and PrePaint once per frame for the whole span.

How the animation ended. endData.state is finished when it ran out, paused after pause(), and idle after cancel().

Traps

endData is on the begin event, not the end. Chrome's JSON exporter rebuilds each span as one slice and then splits it back into a begin and an end, copying the arguments onto the begin and clearing them from the end, so every e event has empty args. DevTools' own event types do not declare endData at all. A begin carries endData exactly when its animation ended inside the recording; a begin without it was still running when you stopped.

Start recording before the animation starts. An animation whose begin falls outside the recording has no span in it, and no end either: an end with no begin never becomes a slice, so it is never written. A 3 second width animation that was already running when tracing began, and finished well inside a 2.5 second recording, left no Animation event at all, while Layout ran on every frame throughout. Instants are exported one at a time and do survive, so such an animation can still drop a lone state or compositeFailed instant into the trace with no begin to attach it to. The compositor result has a second gate: Blink only keeps the list of reasons if the category was enabled when the animation last became pending.

No compositeFailed does not prove the animation was composited. Success writes nothing. Neither does an animation Blink never offered to the compositor: one in a hidden page, one that is not playing, or one whose reason list was never allocated. Nor does an animation whose begin predates the recording, which has no span to hang a result on. The absence tells you something only when the begin is in your trace, the animation started inside the recording, and the page was visible.

Not every compositeFailed is a performance problem. Bit 17 means the animation has no visible change, which Chromium's source attributes to constant keyframe values or an off-screen animation it optimised out. It writes the instant with no unsupportedProperties, and it repeats: Blink re-marks such an animation compositor-pending every time that verdict flips, and each re-check writes another instant. In captures it appeared once on a quiet page and once per frame on a page that was also running composited animations.

transform and opacity can fail too. An animation of either on an inline element, or under will-change: contents, was rejected with no property named at all.

unsupportedProperties is absent, not empty, when nothing in the failure was a property, at least in an exported JSON trace.

state on the begin reads running before the animation is running. Blink decides between begin, instant and end using an extra pending state that exists only for DevTools, but it writes the play state from the Web Animations spec, which has no pending. The first instant with state: running is when the animation actually got its start time, tens of milliseconds after the begin at most in these captures. In the same way, an instant with state: paused is the pause being requested, and the end that follows is the pause taking effect.

id is not the animation's id. It is a counter Blink increments for every animation it creates in the renderer process, so a recording that caught two renderers has two animations numbered 1. The id a script sets is name. And element.animate() starts the animation before it applies the id option, so the first begin of such an animation has an empty name and displayName; only a later restart carries it.

DevTools gives a still-running animation zero duration. trace_engine pairs each begin with its end, and keeps a begin with no end only if it has an instant, at dur 0. An infinite spinner looks as if it lasted no time at all, and instants whose begin came before the recording are dropped.

The layout shift culprits DevTools reports count instants, not animations, and ignore which property failed. CLSCulprits turns every instant with a non-zero compositeFailed into a failure, bit 17 included, and attributes it to a shift only if the shift lands in the first PrePaint after the animation's end, or after its begin if it had not ended. A constant animation can fill that list, and a non-composited animation that moves content while it runs is not named for those shifts.

{
  "name": "Animation",
  "cat": "blink.animations,devtools.timeline,benchmark,rail",
  "ph": "b",
  "ts": 1109196689,
  "pid": 8475,
  "tid": 8475,
  "id2": {
    "local": "0x38f4005fc1d8"
  },
  "scope": "blink.animations,devtools.timeline,benchmark,rail",
  "args": {
    "data": {
      "displayName": "margin-bottom",
      "id": "1",
      "name": "",
      "nodeId": 40,
      "nodeName": "BUTTON class='message-component message-button no-children focusable button sp_choice_type_11'",
      "state": "running"
    },
    "endData": {
      "state": "finished"
    }
  }
}

See also Layout · UpdateLayoutTree · Paint · LayoutShift · PrePaint

categories

blink.animations, devtools.timeline, benchmark, rail

usage

moderate

undeclared args

args.endData.state

references

animation.cc, inspector_animation_agent.cc

The compositor starts a new frame on a display refresh.

Spec

Chromium's compositor, cc, starts an impl frame for one display refresh signalled by viz, Chrome's display compositor, or writes the same event afterwards for a refresh it missed, on the thread that drives that layer tree.

Arguments

Observed 46,944 times on 182 of 300 sites.

Behaviour

Once per display refresh, viz sends a begin-frame signal to every compositor that has asked for one. When a renderer's compositor receives it, it starts an impl frame, cc's name for the work its own thread does each frame, and writes this event. It is an instant on the renderer's Compositor thread, not the main thread.

A compositor only asks for these signals while it has something to do: a requestAnimationFrame callback, a running animation, a pending redraw. A page with nothing to do writes none. In one capture a static page wrote no BeginFrames in four seconds, a single requestAnimationFrame wrote two, and a CSS animation or a requestAnimationFrame loop wrote one per refresh for as long as it ran. NeedsBeginFrameChanged marks each time a compositor starts and stops asking.

Every widget has its own compositor and its own layer tree: the main frame, and each out-of-process iframe in its own renderer. An animating cross-site iframe ticks its own layer tree and leaves the parent's silent.

A second code path writes the same event for refreshes that never reached the compositor. As each impl frame begins, cc's frame reporting controller compares the new sequence number with the previous one, sets aside the refreshes viz held back on purpose, and writes one event for every refresh in between, in the same task and just before the real one. A gap of n refreshes writes n minus one events, and a gap of more than a hundred writes none at all, so the longest stalls are the ones that leave nothing behind. The timestamps are arithmetic, the previous frame's time plus one interval each, rather than times viz recorded.

The browser draws its own tabs, toolbar and window chrome with a compositor of its own, and the first code path skips it. The second does not. Every BeginFrame on the browser's CrBrowserMain thread is therefore a refresh its interface missed, and the refreshes it handled write nothing.

Derivations

Which part of the page never goes idle. Group these events by pid and layerTreeId, and map each pair to a frame through SetLayerTreeId, which carries both the layer tree id and the frame id. A layer tree with an unbroken run of BeginFrames through a stretch where nothing should be moving has something requesting a frame every refresh: a spinner, a requestAnimationFrame polling loop, an ad iframe. That compositor is waking at the display's rate for as long as the run lasts.

One frame grid across processes. frameSeqId is numbered by viz, not by the renderer, so the same number in two processes is the same refresh and carries an identical ts. That lines the main frame, its out-of-process iframes and the browser UI up refresh by refresh.

Traps

ts is not when the event was written. Chrome passes the frame's start time from the begin-frame signal to the trace macro explicitly, so ts is the moment viz stamped the refresh, earlier than the compositor task that wrote it: a median of 0.15 ms headless and 0.46 ms headful in two Linux captures, and whole refresh intervals for the backfilled events. A trace sorted by ts puts the event ahead of the message that delivered it. tts is the thread time at write, so on this event the two do not describe the same moment.

Not every BeginFrame is a frame that started. The backfilled ones describe refreshes the compositor missed. They are written in a single task, so the signature is a run of consecutive events on one thread whose thread time barely moves while ts steps one refresh interval at a time. In a renderer the last event of such a run is the real frame. On the browser's interface compositor there is no real one, because only the backfill path runs there.

The count is not a frame rate. The compositor thread starts frames whether or not the main thread can supply them: a page blocking its main thread for 300 ms at a time still produced one BeginFrame per refresh. Nor is every impl frame drawn. A frame that finds nothing damaged abandons its draw, so on one real site a single layer tree had 309 BeginFrames, 23 DrawFrames and 80 DroppedFrames, while a page running one CSS animation had a DrawFrame for every BeginFrame. DroppedFrame is written only when the drop costs smoothness, so a BeginFrame with neither partner is usually a frame with nothing to redraw rather than a loss.

layerTreeId is not unique in a trace. It is a counter local to each process, starting at 1, so the browser and every renderer reuse the same small numbers. Key on pid and layerTreeId together. It is not fixed for a frame either, and the main frame is not always on the first tree its renderer created: read the number from SetLayerTreeId, which carries the layer tree id and the frame id together.

DevTools can merge an iframe's frames into the page's. Its frame model picks the main frame's layerTreeId and then accepts any BeginFrame or DrawFrame carrying that number, from any process, although it does check the process id on main-thread events. Two iframes from the same site usually share a renderer and get layer trees 1 and 2, which collides whenever the main frame is on 2. In one capture a page that repainted twice a second, with two same-site iframes animating, came out as 240 frames in four seconds; with the iframes on different sites it was 8.

frameSeqId joins BeginFrame to DrawFrame, not to Commit. DrawFrame carries the number of the impl frame it drew and DroppedFrame the number of the one it dropped, so both pair with BeginFrame inside one process and layer tree. Commit carries the number of the BeginFrame that asked the main thread for work, which is a different frame from the one that draws the result whenever the main thread is late. BeginMainThreadFrame has no frameSeqId at all, and DevTools' frame model never reads Commit's.

The numbering counts refreshes, not frames. It keeps advancing while a compositor is not listening, so a break in the run usually marks the moment that compositor stopped asking, which NeedsBeginFrameChanged confirms. While it is listening the backfill closes the gaps, unless the stall ran past a hundred refreshes. Chromium's own comment warns the sequence can break when the begin-frame source changes, and the source id is not in the trace.

The category is off by default. These events live on disabled-by-default-devtools.timeline.frame. DevTools puts it in every Performance recording, but a CDP or Perfetto session you configure yourself records nothing unless you ask for it.

Your harness can create these events. Puppeteer's waitForFunction polls with requestAnimationFrame by default, and that alone made a static page write one BeginFrame per refresh. Anything in a test script that polls through requestAnimationFrame does the same.

{
  "name": "BeginFrame",
  "cat": "disabled-by-default-devtools.timeline.frame",
  "ph": "I",
  "ts": 1102922548,
  "tts": 1503,
  "pid": 8257,
  "tid": 8278,
  "s": "t",
  "args": {
    "frameSeqId": 6,
    "layerTreeId": 1
  }
}

See also DrawFrame · BeginMainThreadFrame · Commit · NeedsBeginFrameChanged · DroppedFrame · SetLayerTreeId

categories

disabled-by-default-devtools.timeline.frame

usage

moderate

references

devtools_instrumentation.h, layer_tree_host_impl.cc, compositor_frame_reporting_controller.cc

The main thread starts its part of a new frame.

Spec

Chromium's compositor, cc, marks the start of a main frame on the renderer's main thread: the rendering update in which Blink runs frame-aligned input and events, requestAnimationFrame callbacks, style, layout and paint before handing the result to the compositor thread.

Arguments

Observed 27,016 times on 182 of 300 sites.

Behaviour

Chrome produces a frame on two threads. The compositor thread decides a frame is due and posts a task to the main thread, writing RequestMainThreadFrame as it does. When that task runs, cc checks that the page is visible and that rendering is not being held back, applies the scroll offsets and pinch-zoom deltas the compositor thread has accumulated, writes this event, and then hands control to Blink for the rendering update. It is an instant with no duration, a few microseconds into the task; the work it announces follows it in the same task, in this order:

BeginMainThreadFrame
  input held for the frame     mousemove, wheel, touchmove
  events                       resize, scroll, media queries, animations
  requestAnimationFrame        FireAnimationFrame
  style, layout, paint         UpdateLayoutTree, Layout, PrePaint, Paint
Commit                         layer update and handoff to the compositor

Chrome only asks for a main frame when something needs one: a requestAnimationFrame, a DOM or style change, an animation that has to tick on the main thread. An idle page writes none. An animation the compositor runs by itself writes almost none: in one capture a transform animation produced 2 main frames in 800 ms, and a width animation on the same element produced 37.

There are three situations in which Chrome writes nothing even though a frame was asked for. A hidden page aborts the main frame before this event. So does a page whose main frame updates are deferred, which is how a loading document holds off rendering: in one capture a script in <head> requested an animation frame and no main frame ran for the 2.5 seconds until the <body> arrived. And the browser's own UI compositor is excluded at the call site, so every one of these belongs to a renderer.

Each compositor has its own sequence. A page has one for its main frame, and each out-of-process iframe has one in its own renderer. frameId counts that compositor's main frames from 0.

Derivations

Waiting versus working. RequestMainThreadFrame is written the moment the compositor thread posts the task, so the gap from it to this event is how long the frame queued behind other main-thread work. The gap from this event to the start of the next Commit on the same thread is how long the rendering update itself took. Together they split a late frame into its two causes. A 300 ms timer task put the best part of 300 ms into the first gap and about half a millisecond into the second, while the compositor thread wrote 17 DroppedFrame events. A requestAnimationFrame callback doing 40 ms of work did the reverse: 40 ms of work and under 0.1 ms of waiting. The second gap stops where Commit opens, so cc's own commit work is outside it; that slice runs in tens of microseconds and stays under a millisecond even at the tail, but it is main-thread time too.

Which vsync the main frame answered. This event carries no frameSeqId, but the Commit that follows it does, and that number is the BeginFrame the main frame was started for. After the 300 ms task above, the Commit named a BeginFrame issued nearly 300 ms earlier, not the current one.

Which main frames changed anything. frameId reappears as frameId on ActivateLayerTree when the layer tree that main frame committed goes live on the compositor thread. A frameId with no matching ActivateLayerTree is a main frame that did its work and had nothing to commit. In two captures that also recorded cc's own abort events, the match was exact in both directions. Both events are in DevTools' default recording, so a trace exported from the Performance panel carries them, though neither is drawn in the panel itself.

Traps

The span to Commit is not a frame budget. It excludes the time the frame waited to start, which is where a long task puts its cost. A short span with dropped frames does not clear the main thread: in the capture above the span was about half a millisecond and 17 frames were lost to a main-thread task. Check the gap from RequestMainThreadFrame before you look at raster or the GPU. DevTools agrees with this reading: its own frame model dates a frame from the start of the task, not from this event.

frameId is not a frame. It is neither the frame token other events use to name a document nor the frameSeqId that BeginFrame, Commit, DrawFrame and DroppedFrame share. It is a counter of this compositor's main frames, advanced when one reaches the commit step. No field on this event joins it to those four; pair it with the next Commit on the same thread, or through ActivateLayerTree.

DevTools records this event but never draws it. Its timeline style carries a hidden flag, as do RequestMainThreadFrame, BeginFrame and DrawFrame, and ActivateLayerTree has no style at all, so none of them appear in the flame chart. Commit does. Turn on "Show all events" in the panel's settings to see them, or read the exported trace JSON.

The two events you want are on different categories. This one is written only on disabled-by-default-devtools.timeline.frame; Commit is written only on disabled-by-default-devtools.timeline. A DevTools recording asks for both, but a hand-written trace configuration that takes one and not the other cannot pair them at all.

Two trace events are called Commit, and a Performance recording contains both. The one this event pairs with is a complete event on the renderer's main thread carrying layerTreeId and frameSeqId. The other is an argument-less async pair on the compositor thread, category cc,benchmark,disabled-by-default-devtools.timeline.frame, written by cc's frame reporter as it walks a compositor frame through its stages. Match on thread and phase, not on the name.

layerTreeId is only unique within a process, because it comes from a per-process counter. In one trace the browser process wrote Commit events with layerTreeId: 1 and an out-of-process iframe's renderer used 1 for its own tree. Key on pid and layerTreeId together, or a pairing with "the next Commit" will pick up the browser's.

A Commit after this event does not mean anything was committed. cc opens the Commit slice before it checks for changes and closes it on the way out when there were none, so every main frame in every capture had one, including those that changed nothing on screen.

It is also possible, from source, for a main frame to run and then skip the commit altogether, while paint holding defers commits on a loading page, or on an animate-only frame. That leaves this event with no Commit after it and the next main frame repeating its frameId. It did not happen in any of the traces checked for this entry.

Style and layout are not confined to main frames. Script that reads layout after changing the DOM forces them in whatever task it is running, outside any BeginMainThreadFrame. Adding up the work between these events and Commit misses it.

Your recorder can create these events. Puppeteer's page.waitForFunction() polls with requestAnimationFrame by default, which requests a main frame every vsync for as long as it waits. A page that was idle produced none with a fixed sleep and one every 16.7 ms with waitForFunction.

trace_engine types data.frameId as optional. Chrome writes it on every event. DevTools' frame model tests it for truth rather than for presence, so the one main frame it never labels is the one with frameId 0, the first of every layer tree.

{
  "name": "BeginMainThreadFrame",
  "cat": "disabled-by-default-devtools.timeline.frame",
  "ph": "I",
  "ts": 1102922990,
  "tts": 28292,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "frameId": 2
    },
    "layerTreeId": 1
  }
}

See also RequestMainThreadFrame · Commit · ActivateLayerTree · BeginFrame · DroppedFrame · DrawFrame

categories

disabled-by-default-devtools.timeline.frame

usage

moderate

references

devtools_instrumentation.h, layer_tree_host.cc, layer_tree_host.h

Chrome brings style and layout up to date on demand, outside its regular rendering update.

A DevTools Performance recording does not contain this event. Record blink with your own trace configuration to get it.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

Blink brings a document's style and layout up to date synchronously, for any reason other than the regular rendering update, timed by LocalFrameMetricsAggregator on the renderer's main thread.

Arguments

Observed 1,015,746 times on 182 of 300 sites.

Behaviour

Chrome normally updates style and layout once per frame, in the rendering update it runs before painting, which Chromium calls BeginMainFrame. Anything that needs an answer sooner, such as script reading offsetHeight, can ask for the update immediately instead. Chromium's definition of forced is a single comparison in Document::UpdateStyleAndLayout: every request carries a reason, and any reason other than kBeginMainFrame opens this slice. The name is borrowed from the UMA histogram the same timer feeds.

Script is only one of those reasons. The others include hit testing, focus, accessibility, printing and Blink's own housekeeping, and they produce the same event with no script anywhere on the stack. Blink forces a layout of its own after the load event, and in one capture every synthetic mouse move produced one, in a task posted by the renderer's input event queue. The reason itself is never written to the trace.

The slice opens before Blink checks whether anything is out of date. When style and layout are already clean the event still appears, a few microseconds long, containing nothing but an argument-less LocalFrameView::UpdateStyleAndLayout. Consecutive requests are not merged either: a loop reading offsetWidth twenty times with no writes produced twenty events. When a request does find work, the slice contains UpdateLayoutTree, Layout, or both.

Only the outermost request in a frame is timed, which covers Blink re-entering the update for auto-sizing and plugins. That counter belongs to each frame, though, and a document inside a same-process iframe brings its embedding document up to date before its own. A read inside such an iframe therefore produces a nested stack of events, one for the document that was read and one for each document embedding it in the same process: the read document's slice on the outside, its parent's inside that, and so on up to the top frame.

preFCP is true until the frame's local root has painted contentful content. A local root is the top frame of a group rendered together in one process. For a page that is the main frame, shared by every iframe in the same process; an iframe running in a process of its own, normally a cross-site one, is its own local root.

Some documents never write the event at all. Blink skips the timer when the platform has no high-resolution clock, and an SVG image document has no metrics aggregator to write to.

Derivations

Layout thrashing, counted exactly. Within one task, a run of these events that each contain a Layout is script alternating writes with reads, one event per read that found layout dirty, and with the stack category recorded, the stackTrace on each Layout inside names the line. The events in between that contain nothing are reads that found layout clean. Nothing in a DevTools recording shows those reads at all, and they matter: a read that sits in a loop costs a layout per iteration the moment the same loop also writes.

Forced updates that script did not cause. DevTools' forced reflow warning and insight only count Layout and UpdateLayoutTree that fall inside a JavaScript event, so a forced update driven by input handling, the end of parsing or Blink itself never reaches it. An event here with no FunctionCall, EvaluateScript or other script event among its ancestors is one of those.

Traps

The event is on the blink category, which DevTools asks for only with Show all events ticked in settings. Even then trace_engine has no model for it, so the Performance panel draws it under its raw name. Recording blink yourself is the practical route.

The duration is not layout cost. The slice spans the whole body of Document::UpdateStyleAndLayout, which also applies scroll restoration, scroll anchoring and pending scroll-snap updates after the layout. A slice with nothing inside it did no work at all, and a sum of durations mixes those checks in with real updates. Sum the UpdateLayoutTree and Layout events inside instead. Summing the slices themselves counts a same-process iframe's ancestors again, because each event in a nested stack contains the ones under it; count only slices that are not inside another.

It does not cover every forced style recalculation. getComputedStyle() for a property that does not depend on layout, such as color or opacity, recalculates style through a different path and produces an UpdateLayoutTree with no forced event around it. For a layout-dependent property, and transform is one of those, the style recalculation runs just before the slice opens and the layout lands inside it. The exception is a style that comes from a container query: resolving even color on an element inside a container whose layout is dirty upgrades the style-only path to a full update, and the layout then runs inside a slice after all.

Nothing on the event identifies the caller: no reason, no frame, no stack. A slice that did work has UpdateLayoutTree and Layout inside it carrying a stackTrace, provided you recorded disabled-by-default-devtools.timeline.stack. A clean slice has nothing inside it, and the enclosing script event is the closest you will get.

preFCP is not a comparison with the reported First Contentful Paint. It flips when Blink paints the first contentful content, while the reported timestamp is when that frame was presented: in one capture, five forced events up to 4.5 ms ahead of the firstContentfulPaint mark already read false.

preFCP belongs to the local root, not to the document. A head script in a same-process iframe inserted after the page painted reads false before the iframe has painted anything, while the same script in a cross-site iframe running in its own process reads true. The flag never returns to true within one document's life, so every forced update after a soft navigation reads false.

preFCP: true says when the work happened, not that it delayed anything. It is not evidence about First Contentful Paint, and it says nothing about Largest Contentful Paint.

{
  "name": "Blink.ForcedStyleAndLayout.UpdateTime",
  "cat": "blink",
  "ph": "X",
  "ts": 1102948046,
  "dur": 5,
  "tdur": 2,
  "tts": 44138,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "preFCP": false
  }
}

See also Document::UpdateStyleAndLayout · LocalFrameView::UpdateStyleAndLayout · Layout · UpdateLayoutTree · InvalidateLayout

categories

blink

usage

very high

duration

short

references

local_frame_metrics_aggregator.cc

The main thread hands the page's updated layers over to the compositor thread.

Spec

Chromium's compositor library, cc, turns the frame Blink has just painted into layer updates and hands them to the compositor thread to be committed, on the main thread of the process that owns the layer tree.

Arguments

Observed 186,094 times on 182 of 300 sites.

Behaviour

Three different pieces of Chromium write an event called Commit, and they are easy to tell apart. The one DevTools draws, and the one this entry is about, is a slice with a duration on disabled-by-default-devtools.timeline, carrying layerTreeId and frameSeqId. The other two are async b/e pairs with empty args: one on cc,benchmark,disabled-by-default-devtools.timeline.frame, nested inside a PipelineReporter, and one on cc,benchmark,input,input.scrolling, nested inside an EventLatency. Those two are the same measurement, the compositor thread's own commit action, recorded as one stage in a per-frame breakdown and written after the fact, when the frame is finished with. They are why args is missing from so many Commit records. A Performance panel recording contains the first two and never the third, because DevTools records the timeline.frame category group and not input.

The main-thread slice lives inside ProxyMain::BeginMainFrame, cc's handler for a main-thread frame. By the time it opens, Blink has already run style, layout and paint. The slice begins with cc updating its layers, which for a Blink page mostly means copying Blink's display lists into cc's own. It then takes a snapshot of the changed state, posts that to the compositor thread and carries on, running Blink's post-lifecycle steps: accessibility updates and IntersectionObserver computation. It closes only when BeginMainFrame returns. So the handoff is somewhere in the middle of the slice, not at either end of it.

No Commit is written when a frame never gets that far: the page is hidden, updates or commits are being deferred, or the frame only needed to run animations. A page that is not changing produces none.

When cc updates its layers and finds nothing changed, the slice is still written. It contains an EarlyOut_NoUpdates and a MainFrameAborted whose args.main_frame_pipeline.aborted_on_main_reason is NO_UPDATE, nothing was committed, and no stage appears in the frame's breakdown. Both of those events are on the cc,benchmark category, which DevTools does not record, so in the panel such a commit looks like any other.

The browser process writes this event too. Chrome's own UI is drawn by a cc compositor that runs on the browser's main thread, with no compositor thread to hand to, so that slice contains the entire commit, LayerTreeHostImpl::FinishCommit included. On a static test page the browser process wrote more of them than the renderer did.

Derivations

What happened to the frame afterwards. Join this event's pid, layerTreeId and frameSeqId to the PipelineReporter in the same process whose args.frame_reporter has the same layer_tree_host_id and frame_sequence. That record tells you whether the frame was presented with this commit's content, presented with older content, or dropped, and breaks its path to the screen into timed stages. The join matched every renderer commit in a test capture, and PipelineReporter is one of the categories DevTools records, so it works on a panel recording. DrawFrame with the same number is not a substitute: a draw is not presentation, and it does not tell you which commit's content was drawn.

Traps

Filter on more than the name. Counting every event called Commit counts each commit two or three times. Keep the ones with ph X and a frameSeqId, which is exactly what trace_engine's isCommit does. Its comment blames old traces, but frameSeqId was added to this event well before it was renamed from CompositeLayers, so what the check really excludes is the two async stage copies.

layerTreeId is not unique across a trace. It comes from a per-process counter that starts at 1, so the browser's UI compositor and a renderer can both report layerTreeId: 1, with overlapping frameSeqId values. In one renderer the id moved from 1 to 2 when the page navigated away from the initial about:blank. Always key on pid as well. A SetLayerTreeId event maps a frame to its tree.

The async stage cannot be keyed back to a frame. In a JSON trace the exporter gives many PipelineReporter tracks the same id2.local, and the reporters overlap in time, so neither the id nor a begin/end stack will tell you which frame a stage belongs to. Use the main-thread Commit and its arguments for that.

Much of a long Commit may be IntersectionObserver work. In a fixture observing 400 elements, IntersectionObserverController::computeIntersections accounted for most of the time inside Commit. In the Performance panel none of it is drawn: Blink writes the child under that long name, trace_engine only knows the name ComputeIntersections, and the timeline hides event names it has no style for. Every other child of Commit is on the cc or cc,benchmark categories, which DevTools does not record at all, so a Commit bar in the panel has nothing underneath it. That is from reading the source and from a capture made with DevTools' own category list; the panel itself was not opened.

Commit is not a line between main thread and compositor. The compositor thread's own commit stage starts a fraction of a millisecond into the main-thread slice and almost always finishes before the main thread closes it.

The duration can include waiting. On a frame a few milliseconds after a click, the main thread was seen stopping inside Commit until the compositor thread finished. cc has a flag that makes it wait, and the only function that sets it is ProxyMain::SetInputResponsePending, whose comment says the main thread pauses when the next frame contains the response to input. Nothing in Chromium's source calls that function. The wait is measured; what sets the flag is unverified.

The reverse is also true: a main-thread wait for a commit that happens outside BeginMainFrame is not in any Commit. Chromium's own TODO at the call site says so. LayerTreeHost::WaitForCommitCompletion on the cc category is not a good way to find those, though. It fires about once per commit whether or not anything is waited on, because the same call is used to reset a flag after the compositor has already finished, and those take a microsecond or two. Only a long one is a real wait.

trace_engine types this event as an instant, but every main-thread Commit has a dur.

The frameSeqId values have gaps. Each is the number of the BeginFrame that started the main-thread frame, and a BeginFrame that produced no commit leaves its number unused. On a page animating every frame there are no gaps at all. DevTools does not read frameSeqId from this event; it only uses layerTreeId to mark the pending frame as committed.

{
  "name": "Commit",
  "cat": "disabled-by-default-devtools.timeline",
  "ph": "X",
  "ts": 1102923583,
  "dur": 59,
  "tdur": 53,
  "tts": 28651,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "frameSeqId": 6,
    "layerTreeId": 1
  }
}

See also BeginMainThreadFrame · BeginFrame · ActivateLayerTree · DrawFrame · PipelineReporter · ComputeIntersections · CompositeLayers · SetLayerTreeId

categories

disabled-by-default-devtools.timeline, cc, benchmark, disabled-by-default-devtools.timeline.frame, input, input.scrolling

usage

high

duration

typical

references

devtools_instrumentation.h, proxy_main.cc, single_thread_proxy.cc, compositor_frame_reporter.cc, event_latency_tracing_recorder.cc

The old name for Chrome handing the page's layers from the main thread to the compositor thread.

Chrome no longer emits this event. The code that wrote it was found in the history and then found to have been deleted.

Spec

Chromium's compositor, cc, blocks the thread that owns a layer tree while the compositor thread copies that tree into its own, recorded under this name from Chrome 42 until Chrome 111 renamed it Commit.

Arguments

Behaviour

Chrome's compositor keeps a page's layer tree on two threads. The main thread builds its copy through style, layout and paint; the compositor thread keeps its own, and rasterises and draws from that. A commit is the handover between them, and this event was the owning thread's side of it.

That thread does not do the copy. It posts the commit to the compositor thread, which cc calls the impl thread, and blocks until the compositor's scheduler has run it, so the slice is the wait, the scheduler's own delay and the copy together. It stayed open a little longer than that: after the wait came Blink's post-commit work, which is why an IntersectionObserverController::computeIntersections sits inside every one written by a renderer.

The slice opened after the layers had been updated and after cc had packaged the commit, and it opened before cc checked whether anything had changed, so a main frame with nothing to commit still produced a short one. Where a layer tree has no compositor thread, which includes the browser's own interface, the same code did the copy inline and the slice is the copy.

You got one per main frame that reached the commit stage. A frame the main thread never runs, such as one driven entirely by a compositor animation, wrote nothing, and so did a main frame that returned early because the page was not visible or commits were deferred.

Chrome no longer writes the name. Blink's DevTools agent wrote CompositeLayers around each commit until February 2015, when the event moved into cc itself as ScopedCommitTrace and shipped in Chrome 42. Chrome 94 added frameSeqId alongside layerTreeId. Commit e8a4175e91, first shipped in Chrome 111, changed the name to Commit and nothing else: the same struct, call sites, category and arguments. The same release gave the layerization step its own event, Layerize. No Chromium source contains the old string today, so you will only meet this event in a trace recorded by Chrome 110 or earlier, or in a tool written to read one.

Derivations

dur minus tdur is the part of the slice in which the thread was not running. Under threaded compositing that is the block on the compositor thread, so a long commit with little thread time points at a compositor that was slow to pick the work up rather than at an expensive copy. For a layer tree with no compositor thread the two are within a microsecond of each other, which is one way to tell which kind of compositor wrote an event you are looking at.

Traps

The name says composite, but the work is the commit. Nothing inside this slice rasterises, draws or composites anything to the screen. That happens afterwards on the compositor thread, marked by ActivateLayerTree and DrawFrame.

Commit is not the same measurement under a new name. Chrome 111 moved layer updating inside the span five days before it renamed the event, in commit 54d0b36333, so both changes reached users in the same release. Every stable build that wrote CompositeLayers opened the slice after that work; every build that writes Commit includes it, single-threaded compositors aside. A jump between an old trace and a new one can be the definition changing rather than the page.

Chrome emitted it as a begin and end pair, but what lands in a trace file is one complete event carrying dur, tdur and the arguments. trace_engine types it as an instant event with layerTreeId alone, which is wrong about the phase and about the arguments; from Chrome 94 the event also carried frameSeqId. Commit is typed as an instant there too.

Not every one belongs to your page. layerTreeId identifies which compositor committed, and every compositor built on cc writes the event, including the browser's own interface, which in a recording of a single page can write more of them than the page does. DevTools only counts events whose layerTreeId matches the SetLayerTreeId for the main frame. Filter the same way, and filter by process as well, because the id comes from a counter that is private to each process.

Do not normalise an old trace by renaming these events to Commit. DevTools rejects a Commit with no frameSeqId, and accepts a CompositeLayers without one, so a rename silently drops every event recorded before Chrome 94 from the frame model. It also collides: in a current trace three different events are called Commit, on three different categories, and only the one on disabled-by-default-devtools.timeline is this event.

Lighthouse still groups CompositeLayers under Rendering and does not list Commit at all, so the replacement takes its parent task's group instead, which in a current trace is Other. The same work moves from one bucket to the other in Lighthouse's main-thread breakdown between an old trace and a new one.

A short slice does not mean a cheap commit. cc opened it before deciding whether there was anything to commit, so an empty main frame produced one too, with the EarlyOut_NoUpdates marker inside it.

The category is disabled by default. DevTools turns disabled-by-default-devtools.timeline on for a Performance recording, but a tracing session you configure yourself has to ask for it.

See also Commit · BeginMainThreadFrame · SetLayerTreeId · ActivateLayerTree · DrawFrame

references

devtools_instrumentation.cc

DevTools' name for Chrome working out how far each element watched by an IntersectionObserver overlaps its root, which is the viewport unless the observer named an element.

No Chrome build writes this name into a trace file. It exists in the model, not on the wire.

Spec

ComputeIntersections is the name DevTools declares for Blink's IntersectionObserverController updating a document's IntersectionObserver observations on the renderer's main thread, work that Chrome writes to the trace only as IntersectionObserverController::computeIntersections.

Behaviour

Chrome never writes this name. The work it stands for reaches the trace as IntersectionObserverController::computeIntersections, fully qualified and with a lower-case c, on blink,devtools.timeline and with no arguments. Everything below describes that event.

The controller is a per-document object that holds every observation made in that document. A document gets one the first time something in it calls observe(), and keeps it: disconnect() removes the observations but not the controller, and the event carries on afterwards.

From then on, each main-frame update runs the controller twice for that document, both times inside ProxyMain::BeginMainFrame. The first pass comes near the end of the lifecycle update, after pre-paint and before paint, and serves only observers that must deliver before paint, such as the one Blink uses for content-visibility: auto. Anything else is skipped there without measuring geometry. The second pass runs inside the Commit slice, after the main thread has handed the frame to the compositor, and computes everything that delivers later: the page's own observers, and Blink's own loading=lazy watcher. Which pass an observation lands in is decided by its delivery behaviour, not by whether the page or the browser created it.

The count therefore follows frames and documents rather than observers: two per document per main-frame update, four when a same-origin iframe on the same thread also observes something, and more when the first pass makes the lifecycle repeat, which content-visibility: auto does when a section changes state. A parent's slice and a child frame's slice are siblings, not nested.

The slice is written whether or not anything needed updating. Each observation is only recomputed when something has marked it out of date, but that check happens inside the slice, so the controller still walks every observation on frames where nothing moved.

Not every controller is yours. Native loading=lazy images and content-visibility: auto sections both produced the event on pages with no script observer at all. Nor is the callback in the slice: a JavaScript observer's entries are queued, and a task the controller posts runs the callback later.

The naming has a history on both sides. Chromium wrote IntersectionObserverController::computeTrackedIntersectionObservations until Chrome 78, and wrote it on the blink category alone until Chrome 92, when commit bab2cb7b98, "DevTools: Expose computeIntersections trace event", added devtools.timeline. DevTools gained ComputeIntersections in the same release, as a key mapped to the real name, and labelled the event "Compute intersections". The newer trace engine declared the key with itself as the value. When a March 2024 refactor, first shipped in Chrome 124's DevTools, moved the Performance panel onto that table, the label stopped matching anything Chrome writes.

Derivations

Summed per frame, these slices are the main-thread cost of intersection observation, and in a DevTools recording nothing else measures it. Blink.IntersectionObservation.UpdateTime covers the second pass too, but only on the blink category, which the Performance panel does not record.

Traps

Searching a trace for ComputeIntersections finds nothing, from any Chrome version. Search for IntersectionObserverController::computeIntersections. Code built on trace_engine has the same problem: Types.Events.Name.COMPUTE_INTERSECTION holds the bare string and never matches a real event.

The Performance panel hides the real event. DevTools draws a main-thread event only if it has a style, and the only style is keyed on the bare name. The event is recorded and sits in the saved JSON, but the flame chart leaves it out unless the "Show all events" setting, timeline-show-all-events, is on. Its time is folded into whatever visible slice encloses it: Commit for the second pass, the plain task for the first.

A DevTools recording from Chrome 91 or earlier does not contain the event at all, because it was on blink only. Before Chrome 78 it had a different name.

There are no arguments, so the trace cannot tell you which observer did the work, or even whether it was one of yours. Chrome counts internal and JavaScript observations separately inside this function and sends both counts to its metrics, not to the trace.

The number of events tells you nothing about observers, callbacks or intersections. A page with one observer and a page with thousands produce the same count, and a page that disconnected its only observer keeps producing them.

For the page's own observers the cost is in the second slice of each pair, not the first; for content-visibility: auto it is the other way round. In one headless Chrome 153 capture with 2,000 observed paragraphs, the first pass had medians of 26 to 47 microseconds, the second 67 to 102 on frames with no animation and 573 during a requestAnimationFrame loop that moved an unrelated element with left; the single largest slice was 1,158. With one observer, every median stayed under 5. Read the pair per frame, never one slice alone, and do not expect milliseconds.

The slice is not the whole cost of an observer. The callback runs in a separate task and appears as its own FunctionCall.

See also Commit · PrePaint · BeginMainThreadFrame · FunctionCall

references

TraceEvents.ts

Chrome decodes an image's compressed bytes into pixels.

Spec

One of Blink's image decoders turns one frame of an image, or as much of it as has downloaded so far, into pixels, on whichever renderer thread asked for them.

Arguments

Observed 4,611 times on 153 of 300 sites.

Behaviour

Two places in Chromium write this name. ImageDecoder::DecodeFrameBufferAtIndex writes it for every format, and only if the frame it was asked for is not already fully decoded in that decoder. JPEGImageDecoder::DecodeToYUV writes it for JPEG decoded to YUV, the separate brightness and colour planes a JPEG actually stores, before they are converted to RGB.

For images on the page, <img> and CSS backgrounds alike, you will find it on a worker thread, ThreadPoolForegroundWorker, not the main thread. Paint only records that an image goes somewhere; the compositor schedules the decode as a task, so the event sits inside ImageDecodeTask and Decode LazyPixelRef:

ImageDecodeTask            the compositor's decode task       worker thread
  Decode LazyPixelRef      Blink is asked for the pixels
    Decode Image           the decoder runs

Which cache runs that task depends on how Chrome rasterizes. With GPU rasterization it is GpuImageDecodeCache, otherwise SoftwareImageDecodeCache, and the difference changes what this event shows (see traps). decoding="sync" does not move the work to the main thread. The attribute is a hint to the compositor about whether it may present a frame without the image, not a choice of thread, and images marked sync decoded on a worker in both raster modes.

The main thread gets one when script asks for pixels. A canvas 2D drawImage decodes when the canvas frame is finalized, WebGL texImage2D with an image decodes inside the call, and createImageBitmap on an <img> decodes the file again from scratch, even when the page has already decoded it. createImageBitmap on a Blob and the WebCodecs ImageDecoder decode on a worker, with no Decode LazyPixelRef around them.

One image can produce several of these. While an image is still downloading, Blink paints what it has, so each repaint with more bytes decodes again: an 800x600 baseline JPEG and an 800x600 PNG, each delivered in eight chunks, produced three and four events. An animated image gets one per frame the first time round. Once decoded pixels are in the compositor's decode cache, drawing them again writes nothing: a three-frame GIF animating for two seconds produced three, against twenty-one decode tasks.

The frame waits for the decode. Chrome builds each tile's raster task with the decodes of the images in that tile as dependencies, so the frame that first shows an image cannot be presented until its decode has finished. The exception is decoding="async", below.

Derivations

Decode time inside an image LCP. When the LCP element is an image, decoding is not async and a Decode Image exists for it, the candidate cannot be presented until that event has ended, and on GPU raster until the ImageUploadTask that follows it has ended too. Five runs per case on a 4000x3000 JPEG inserted after it had fully loaded, timed from the insert: under software raster the decode ended at 78 to 88 ms and the LCP candidate landed at 100 to 109 ms; under GPU raster the decode ended at 50 to 62 ms and the candidate landed at 108 to 122 ms. That is render delay no main-thread view of the trace shows, because none of it ran on the main thread.

Main-thread decodes. Every Decode Image on CrRendererMain in these captures, and none at all in a DevTools recording made on a different machine, was script asking for pixels through canvas, WebGL or createImageBitmap, and each one occupied the main thread for its full duration. Page images decoded on a worker in both raster modes and on both machines. So filtering this event to the main thread gives you the decode cost your own script put in the way of input, which is the cost createImageBitmap on a Blob would move to a worker.

Traps

A GPU-rastered trace does not show WebP or AVIF decodes to YUV at all. Only the JPEG decoder's YUV path writes this event; the WebP and AVIF decoders' do not. You see a Decode LazyPixelRef with nothing inside it, or ImageFrameGenerator::decodeToYUV if you recorded blink. One page of five images produced four events under software raster and two under GPU raster, losing the WebP and the AVIF. Chrome uses YUV only for a static image whose bytes had all arrived before its first decode, so whether an image appears here depends on the raster mode, the format and the network. Never count these events as "images decoded", and never compare counts between a headless crawl and a DevTools recording made on a machine with a GPU.

imageType is the decoder's file extension, from sniffing the bytes, not the URL or the Content-Type. It is jpg, not jpeg, and on the YUV path it is uppercase JPEG, so any JPEG breakdown needs both. A JPEG served as photo.png with image/png reports jpg.

There is no URL on this event, and the one DevTools shows can belong to another image. DevTools takes the most recent PaintImage on the same thread, or failing that the most recent Decode LazyPixelRef on the same thread, without checking that either is related. A main-thread canvas decode reporting imageType: "png" was labelled with the .jpg URL of an unrelated <img> painted earlier, and a createImageBitmap decode on a worker was labelled with the JPEG that worker had decoded before. Your own join is safer: the enclosing Decode LazyPixelRef carries the image's id, and the Draw LazyPixelRef written when an element painted that image carries the same one. An event with no enclosing Decode LazyPixelRef cannot be tied to an image at all.

A canvas decode is not under the drawImage call. It runs at CanvasRenderingContext2D::FinalizeFrame, which is a later task with no script on the stack unless something such as getImageData forces the canvas to flush first.

dur covers the decoder's own work and nothing else. Colour conversion runs after it, and the copy to the GPU is a separate ImageUploadTask. AVIF is given two decoder threads, so its tdur came out well below its dur, between a third and a half of it across captures, while every other format matched: for AVIF, dur is how long this thread waited and tdur undercounts the CPU.

With decoding="async" the LCP can be stamped before the pixels reach the screen. The compositor may present frames with the image's box still blank and fill it in later, and the LCP candidate is recorded on one of those frames. Across ten runs with screenshots, LCP was reported 76 to 138 ms before any presented frame contained a 4000x3000 photo. Chrome does this only for an image marked async that is static, was already fully downloaded when it was first drawn, and is at least a megabyte of decoded pixels on desktop, or half that on Android with GPU raster. So a cold first load is not affected: the hero is first drawn while still arriving and Chrome declines to defer it. A repeat view from the HTTP cache, or a preloaded hero held back by slow CSS, is affected, and there the reported LCP came in 15 to 29 ms ahead of the frame that actually showed a 1920x1080 hero. Do not read an LCP timestamp as proof that the image's pixels were on screen.

Several events for one image while it loads are separate partial decodes, not one slow one. This is about partial data, not progressive encoding: a baseline JPEG and a PNG both did it. Match them by the enclosing Decode LazyPixelRef id before adding durations up.

{
  "name": "Decode Image",
  "cat": "disabled-by-default-devtools.timeline",
  "ph": "X",
  "ts": 1108423719,
  "dur": 99,
  "tdur": 99,
  "tts": 929,
  "pid": 8407,
  "tid": 8471,
  "args": {
    "imageType": "png"
  }
}

See also Decode LazyPixelRef · ImageDecodeTask · ImageUploadTask · PaintImage · largestContentfulPaint::Candidate

categories

disabled-by-default-devtools.timeline

usage

moderate

duration

long

references

image_decoder.cc, jpeg_image_decoder.cc

Chrome makes sure a document's style and layout are up to date, because some code needs to read them right now.

A DevTools Performance recording does not contain this event. Record blink with your own trace configuration to get it.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

Blink's Document::UpdateStyleAndLayout brings one document's style and layout up to date for a caller that needs current geometry, updating any parent document first, on the renderer's main thread.

Behaviour

This is the on-demand path, not the scheduled one. Anything in Blink that is about to read geometry calls it first: offsetHeight, getBoundingClientRect(), a layout-dependent property read through getComputedStyle(), elementFromPoint(), scrollIntoView(), innerText, focus changes, editing, selection and printing. The rendering update Chrome runs in each frame does not come through here. It calls LocalFrameView::UpdateStyleAndLayout directly, so an animating page with no script produces frame after frame of Layout and not one of these.

The event is written before Blink checks whether anything is dirty, so every call produces one, whether or not there was work to do. A hundred consecutive offsetHeight reads with nothing changed in between produced a hundred events of about five microseconds each, and not one of them contained a Layout. The count tells you how often something asked for geometry, not how often Chrome laid out. Reads against a detached node or a document that was never put on screen do not reach the function at all, and produce nothing.

When the document is a same-origin iframe, Blink updates the parent document first, inside the child's slice. One read in the iframe therefore produces two nested events, and a dirty parent gets laid out on the child's behalf. It does not work the other way round: reads in the parent left a dirty iframe alone. A cross-process iframe has no local owner, and nothing crosses.

Your script is not the only caller. Blink forces one after the load event for the main frame and for visible iframes, and Chrome's own features add more around DOMContentLoaded and load. The one that will surprise you is selection: once a focused frame holds a selection, Chrome's input-method bookkeeping calls this function during every main frame, at the start of the frame to report the selection bounds to the browser, and again afterwards to update text input state. The trigger is the selection itself, not the click that usually creates it. Setting one from script, with no input at all, produced the same events a real click did, and clearing it took them back to none. It costs nothing on an idle page, because an idle page produces no frames; on a page that is animating, scrolling or running script it is every frame. Reporting the bounds is skipped on Android, where the compositor sends them instead, but the text input state half runs everywhere.

Almost every call opens a Blink.ForcedStyleAndLayout.UpdateTime slice inside this one, and this function is the only place that slice is opened. It is skipped for a document with no view, for a re-entrant call on a view already inside one, and on a machine with no high-resolution clock. Blink decides whether to charge a call as forced from a C++ DocumentUpdateReason that is never written to the trace, and no caller in Blink passes it the one reason that would exempt it.

Derivations

Layout thrashing, counted. Within one task, the events that contain a Layout are the layouts your code forced, and the ones that contain nothing were reads against a tree that was already clean. A loop of a hundred style writes each followed by an offsetHeight read produced a hundred of these with a Layout inside every one; the same hundred reads without the writes produced a hundred with nothing inside.

Who forced it. When one of these did real work, the UpdateLayoutTree and Layout nested inside it carry beginData.stackTrace, if you recorded disabled-by-default-devtools.timeline.stack, and that stack points at the line of JavaScript that asked. A nested Layout under this event with no stack was forced by Chrome rather than by script: in one capture, every such layout sat under selection bookkeeping or the end of parsing. Record the renderer category and the selection callers appear by name, as WidgetBase::UpdateSelectionBounds and WidgetBase::UpdateTextInputStateInternal.

Traps

Not every forced update appears here. Reading a property that does not depend on layout, such as getComputedStyle(el).color after a style write, recalculates style through a different function and produces an UpdateLayoutTree with none of these around it. For a layout-dependent property the style recalculation runs first, before this slice opens, so only the layout lands inside.

elementFromPoint() is a caller like any other. It opens one of these before it hit tests, to make sure the scrollbars it is about to measure against are current, and if the tree is dirty the style and layout happen inside it. What runs afterwards under LayoutView::HitTest is the rest of the lifecycle, prepaint included, and that part is outside the slice.

Style and layout inside a frame may not be script's fault. Once a selection exists, the selection-bounds call at the start of each frame is the first thing that needs layout, so the frame's pending work, a CSS animation's style and layout for example, runs inside this event ahead of requestAnimationFrame callbacks and the rendering update, and is charged as forced. Do not read a slice here as script-forced without a stack or a script event around it.

The population depends on how you recorded. A scripted click, of the kind a crawler sends to provoke input events, leaves a caret selection behind, and that selection multiplies these on every frame for the rest of the recording.

Durations nest across iframes. The parent document's event sits inside the iframe's, so summing dur over all of these counts the parent's work twice.

The event is on the blink category. A DevTools Performance recording neither captures it nor draws it unless the timeline-show-all-events setting is on: that one setting adds every category to the recording and lets an event DevTools has no model entry for be drawn at all. With it on, the slice appears under the System colour with its raw C++ name, above UpdateLayoutTree and Layout, and not as the Layout block, which DevTools draws around the Layout event two levels below.

DevTools' own forced-reflow warning never looks at this event. It counts Layout and style recalculation nested inside JavaScript, and only reports a task whose total crosses thirty milliseconds, so a page can be full of these and be flagged for none of them.

{
  "name": "Document::UpdateStyleAndLayout",
  "cat": "blink",
  "ph": "X",
  "ts": 1102948044,
  "dur": 8,
  "tdur": 5,
  "tts": 44136,
  "pid": 8257,
  "tid": 8257,
  "args": {
  }
}

See also Blink.ForcedStyleAndLayout.UpdateTime · LocalFrameView::UpdateStyleAndLayout · Layout · UpdateLayoutTree

categories

blink

usage

very high

duration

short

references

document.cc

The compositor has finished a frame and handed it to Chrome's display compositor.

Spec

A renderer's compositor turns its active layer tree into a compositor frame and submits it to Viz, the GPU-process service that puts frames on screen, on the renderer's compositor thread.

Arguments

Observed 21,196 times on 182 of 300 sites.

Behaviour

In Chromium's compositor, draw does not mean pixels. LayerTreeHostImpl::DrawLayers builds a compositor frame, a list of already-rasterised tiles and quads to be placed on screen, and hands it to the pipe to Viz. DrawFrame is written just after that hand-off, before anything has been drawn. Viz then combines the frame with the browser UI and every other renderer's frames, draws and swaps in the GPU process, and only then is anything visible. In software-only fixture captures on one machine the frame reached the screen a median of about 4 ms later; in a DevTools recording of a real page load the gap ran to tens of milliseconds once the page had settled and into the hundreds during the load, spent waiting for and doing the draw inside Viz.

Chrome writes one only when there is something to draw. Each BeginFrame gives the compositor a chance to produce a frame, and one where the active layer tree has no damage takes an early exit before this line, leaving a cc event called EarlyOut_NoDamage behind. An idle page therefore writes almost none and an animating page writes one per display refresh, so how far the DrawFrame count falls short of the BeginFrame count is a statement about the page, not about traces in general.

The main thread does not have to take part. The compositor waits for the main thread's update until a deadline inside the frame, then draws without it, carrying compositor-driven animations and scrolling forward on the last content it was given. During a 600 ms busy loop in one capture the compositor kept writing DrawFrame for a CSS animation, with no BeginMainThreadFrame and no Commit at all, and each of those draws landed about 16 ms into its frame rather than the usual 1 ms.

The browser's own UI compositor is excluded by an explicit check, so a trace can hold BeginFrames and PipelineReporters from the browser process and no DrawFrames. Every renderer compositor writes them, which means the main frame and each cross-site iframe running in its own process, each with its own layerTreeId.

Derivations

When a drawn frame actually reached the screen, or whether it ever did. Join to PipelineReporter on process, layerTreeId = layer_tree_host_id and frameSeqId = frame_sequence: the reporter ends at the presentation timestamp, and its state says whether the frame was presented, partially presented or dropped. DrawFrame to that end is the part of a slow frame that happened after the renderer had finished, in Viz and the GPU, which separates a busy renderer from a busy display pipeline. The join is not one to one: a frame can carry a second reporter, marked frame_type: FORKED, which follows the main thread's half of that frame and can end dropped while the compositor's frame was presented.

Frame production for compositors DevTools does not show. Counting DrawFrame per process and layerTreeId gives the submitted frame rate of each cross-site iframe, such as an animating ad, which the Frames track leaves out.

Traps

DrawFrame is not presentation. It is the hand-off to Viz, and a handed-off frame can still be thrown away: when Viz presents a later frame first, every earlier one still waiting is recorded as not presented. Anything measuring "time to pixels" from this event is measuring time to hand-off.

A BeginFrame without a DrawFrame is usually not a dropped frame. Most often nothing on the active layer tree had changed, and Chrome reports the frame as no update desired. It reports one as dropped instead when the frame was skipped for any other reason, so the reporter's state is what tells you which, never the absence of the event.

A dropped frame may have a DrawFrame of its own. It has one exactly when the compositor had something to draw and only the main thread's update went missing: during a blocked main thread with a CSS animation running, every frame Chrome flagged as dropped also wrote a DrawFrame. On a page whose animation runs on the main thread, the same block produced dropped frames with no DrawFrame at all. hasPartialUpdate on a DroppedFrame does not mean anything was drawn either. DevTools takes its dropped and partial flags from DroppedFrame and never from a missing DrawFrame.

A steady stream of DrawFrame does not mean the page is responsive. Compositor animations and scrolling keep producing them while the main thread is completely stuck.

layerTreeId is not unique in a trace. It is a counter local to each process that starts at 1, so two renderers in one capture reported 1, and one frame switched from 1 to 2 during load. Join on process as well, always.

frameSeqId is shared, not yours. The number comes from the display's begin-frame source and goes to every client, so the main frame, a cross-site iframe and the browser UI all use the same numbers at the same moments. It also counts from browser start rather than trace start, so a recording opens in the hundreds or thousands and there is no frame 1 to look for.

frameSeqId is the BeginFrame during which the frame was drawn, not the one in which any main-thread work for it began. Content that took three refreshes to produce carries the last one's number.

ts is when the event was written. BeginFrame's timestamp is the frame's scheduled start instead, so the gap between the two on one frameSeqId is how far into the frame the draw happened, not how long the compositor worked.

The Frames track matches a layer tree number, not a process. DevTools takes the main frame's layerTreeId and accepts any frame event carrying it, whatever process wrote it. A cross-site iframe animating at 60 fps on a different number wrote 180 DrawFrames in three seconds and DevTools built two frames; one that landed on the same number instead fed the same model, and its requests for main-thread frames held the gate shut and suppressed the page's own frames. Within the track, DrawFrame only decides which queued BeginFrames become frames: a frame starts at its BeginFrame and ends where the next one starts.

The first DrawFrame of a recording can have no BeginFrame, because that BeginFrame happened before tracing started.

The whole frame family lives in disabled-by-default-devtools.timeline.frame. A recording without that category has none of it.

trace_engine ignores DrawFrame unless it is an instant event. Its own comment says older Chrome builds wrote an async begin and end pair, so a very old trace yields no frames.

{
  "name": "DrawFrame",
  "cat": "disabled-by-default-devtools.timeline.frame",
  "ph": "I",
  "ts": 1102924416,
  "tts": 2021,
  "pid": 8257,
  "tid": 8278,
  "s": "t",
  "args": {
    "frameSeqId": 6,
    "layerTreeId": 1
  }
}

See also BeginFrame · BeginMainThreadFrame · Commit · DroppedFrame · PipelineReporter

categories

disabled-by-default-devtools.timeline.frame

usage

moderate

references

devtools_instrumentation.h, layer_tree_host_impl.cc

This event tells you when the first content on the page - text, an image, a video, a canvas or an SVG shape - reached the screen.

Spec

Blink's PaintTiming records the presentation time of the first compositor frame that carried contentful content for one document, written on that document's renderer main thread once the compositor reports that frame presented.

Arguments

Observed 398 times on 180 of 300 sites.

Behaviour

Painting does not write this mark. A painter that draws something contentful raises a flag on Blink's PaintController, and at the end of the paint Blink bundles the flags raised during that rendering update and asks the compositor for a presentation promise on the frame being produced. The mark is written when the feedback for that frame comes back, on that document's renderer main thread, and it is stamped with the presentation timestamp that came with it: the moment the pixels were on screen, not the moment they were painted. The timestamp is handed to the trace macro rather than taken from the clock, so the record is written later than the instant it claims.

What counts as contentful is a short list with sharp edges. Text that is not all whitespace. An image being drawn, where an image means a real image resource: an <img>, a background-image pointing at a file, an SVG <image>. A <video> element's layer being prepared for the compositor. A <canvas> that has been drawn into. The fill or the stroke of an SVG shape. Text, images and video raise a flag that the end of the frame reads; canvas, SVG shapes and SVG images call the marking function directly.

The edges are where a reader goes wrong. A CSS gradient is a generated image rather than a contentful one, and Blink hands it a do-not-report flag, so a page whose hero is a gradient gets a first paint and nothing here. An empty <canvas> has not been drawn into and does not count, even with a 2D context on it; a canvas filled with white does, because the test is whether anything was drawn and never what colour it was. An <svg> with no shapes in it invokes no painter. Anything painted under opacity: 0 raises nothing, so a page whose content starts transparent gets its mark from the paint after the opacity changes.

PaintTiming belongs to a document, and a CHECK in Chromium makes a second mark for the same document impossible. One document, at most one mark, and nothing further for a soft navigation or a restore from the back/forward cache. But every document gets its own: a same-origin iframe writes its own pair of paint marks on the same thread as its parent, a cross-site iframe writes them in its own renderer process, and a main frame that paints nothing contentful writes none at all while its iframes do.

Derivations

FCP itself is this ts minus the ts of the navigationStart carrying the same navigationId, which is exactly what DevTools computes before classifying it against 1.8 and 3.0 seconds.

The gap from firstPaint in the same frame and navigation is how long the page was on screen with nothing on it: painted, laid out, and showing only a background. When the first paint was already contentful the two marks carry the same timestamp, so a gap exists only when there was really one.

Per-iframe FCP. Each frame's mark stands against that frame's own navigationStart, so the trace gives you a first contentful paint for an embedded document, including a cross-origin one that no script on the page can reach: a document's performance entries only ever describe that document.

Traps

This is not the number your RUM script reports. The mark carries the raw presentation timestamp, because Chromium does not coarsen timestamps it does not expose to the web. The PerformancePaintTiming entry that a field script reads carries the same instant rounded up to the next multiple of 4 ms, unless the document is cross-origin isolated. DevTools uses the raw ts, so the Performance panel and a beacon from the same load can differ by up to that. Measured on a one-paragraph page: the trace said 16.008 ms and the entry said 20. Serve the same page with Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy set and the coarsening stops, and the entry reports the same fractional millisecond the trace does.

The paint-side timestamp is not in the trace. Blink carries it alongside the presentation time all the way into the callback that writes this mark, and writes only the presentation time. The web-exposed entry does expose it, as paintTime, but it is not when painting finished: it is taken near the top of the rendering update, before the paint phase runs. So presentationTime - paintTime covers the paint, the commit, the raster and the swap together, and this event will not tell you how much of that was which.

The mark can precede anything you could see. A <video> marks it when its layer is prepared for the compositor, not when a frame of video appears: a fixture whose video source never delivered a byte still produced the mark on a blank screen, and Chromium says so at the call site. Text still inside a font-display: block period marks it too. A page whose only content is a paragraph in a web font that never arrives reports a first contentful paint and then stays blank; the font-readiness test in Blink's text painter guards the LCP detector, not this flag.

The record is behind its own timestamp. In every capture the mark's ts fell in a gap between two tasks on its own thread, with the next task starting anywhere from a fraction of a millisecond to thirteen milliseconds later. Nothing was running at the instant the mark claims. Do not read the enclosing task as the work that produced it, and do not assume marks reach the file in timestamp order.

Nothing on the event says which frame this is. There is no isMainFrame or isOutermostMainFrame here, unlike an LCP candidate or a navigationStart. Join args.frame to the frame tree, or you will read an iframe's FCP as the page's. DevTools does the join and draws the marker for the main frame only, so an iframe's mark is in the trace and not on the ruler.

The frame id is at args.frame, not args.data.frame, which is where MarkDOMContent and MarkLoad keep theirs.

A frame id does not separate two loads. Reload a page and the second mark has the same frame id as the first; only navigationId tells them apart. Join on it rather than on the nearest navigationStart, because one load can leave three of those in a trace, across two processes, and picking the wrong one moves the answer by milliseconds. DevTools throws rather than guess when the id is missing.

A soft navigation produces no mark here. The document already used its one FCP. DevTools manufactures a soft FCP from a field inside SoftNavigationStart instead, so a soft-navigation FCP on the timeline has nothing to do with this event.

It is phase R, a mark, with no duration; a consumer filtering for instants (I) will not see it. And firstPaint can carry exactly the same timestamp, because a first paint that is contentful backdates the first-paint stamp to its own. Which of the two is written first is the iteration order of a hash set, not a fact about the page.

{
  "name": "firstContentfulPaint",
  "cat": "loading,rail,devtools.timeline",
  "ph": "R",
  "ts": 1102971047,
  "tts": 133797,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "navigationId": "F19F977AB13E669964965F7427E6F7B2"
    },
    "frame": "14A831DCB73EB1205B67CDB89FC6EBD7"
  }
}

See also firstPaint · navigationStart · largestContentfulPaint::Candidate · SoftNavigationStart

categories

loading, rail, devtools.timeline

usage

rare

references

inspector_trace_events.cc, paint_timing.cc

This event tells you when the browser first painted something of the page's own, rather than the blank background it starts from.

Spec

Blink's PaintTiming marks the presentation of the first frame in which a document drew anything other than its default background, timestamped with the presentation time the display compositor reported for that frame, on the renderer main thread that owns the document.

Arguments

Observed 400 times on 180 of 300 sites.

Behaviour

Blink decides what counts while it paints, one document at a time. A stack object, FramePaintTiming, brackets each document's paint; when it goes out of scope it asks the paint controller, the object that records the drawing operations for a frame, whether anything was drawn, and hands the answer to PaintTiming. The paint controller says yes at the first recorded drawing operation that actually puts pixels down, with one exception: the document's own background is skipped there, because at that point nothing knows whether it is the default one. The root background gets in through a separate door in ViewPainter, which raises the flag by hand only when the colour it is about to fill with differs from the frame's base background colour.

The working test is therefore whether the page drew anything of its own, and the line falls in some surprising places. A border counts, including the border Chrome puts on an <iframe> for you. So do a box shadow and an empty form control. So does a white box on a white page, which nobody can see but which is still a fill. A background counts only when it is not the colour the frame started with, so a page whose only styling is background: #fff writes nothing at all. That base colour is a variable, not a constant: under color-scheme: dark it is dark, and the same background: #fff then does count while an unstyled page still does not. A body background is part of the document background only while it transfers to the canvas, which stops as soon as the root element has a background of its own; after that it is an ordinary fill and counts like any other box. A box with size but no decoration draws nothing, and neither does anything under opacity: 0 or visibility: hidden. Painting for printing or for a paint preview runs inside a scope that suppresses paint timing, under a feature that ships on.

Raising the flag does not write the event. It puts kFirstPaint into a set of pending paint events; after the lifecycle update the document asks the compositor to call back when that frame has been presented, and only in that callback does Blink write the mark, stamped with the presentation time rather than with the time of the callback. So the event sits in the trace a little earlier than the task that produced it, and later than the Paint slice that did the drawing.

One per document, ever. The mark and its timestamp are each guarded by a null check on the value they set, and there is no soft-navigation copy of the timing to reset. A second full navigation in the same tab is a second document and writes a second event. A same-document navigation, however much of the page it rewrites, writes none. A page restored from the back/forward cache records its first paint through a different function, which writes nothing to the trace.

Every document writes its own, so an iframe gets one for itself, from its own renderer process when it is cross-origin. The parent does not inherit it, but it is not left out either: the iframe's border is the parent's own paint. Take the border away and a page whose body holds nothing else has drawn nothing of its own, and writes no event, while its child writes one.

First contentful paint marks first paint on its way past, so a document that reaches firstContentfulPaint always has a firstPaint at or before it. Usually it is the same frame, and the two events share a timestamp. Raising the flag is also one of the two things that release paint holding after a navigation, the other being first contentful paint.

Derivations

The interval from this event to firstContentfulPaint in the same document is how long the viewport was styled but empty: painted, so not the browser's blank canvas, and with nothing in it yet. A fixture that set a root background immediately and injected its text a second later put firstPaint at 23 ms and firstContentfulPaint at 1,023 ms. When the page's first drawing is also its first content, which is the ordinary case, both events land in the same frame and the interval is exactly zero: it was zero in every capture made for this entry that had both, and in every trace already on disk.

An absolute number needs the navigationStart whose navigationId matches, not the first one in the trace.

Traps

Its absence does not mean the page did not paint. A fixture whose only styling was a white background over a white base produced Paint, Commit, ActivateLayerTree and DrawFrame and no firstPaint, in Chrome 141 and 153 alike. A page whose body holds only a borderless iframe produces none either, and neither does one whose content is entirely under opacity: 0. Treating the mark as "the screen was blank until here" is wrong in both directions.

args.frame is not a document. It is the frame the document lives in, and a frame outlives its documents: two navigations in one tab wrote two marks with the same frame id, and a trace already in this collection does the same across three renderer processes. args.data.navigationId, the id of the document's loader, is the only field that separates them, and it is the one to join on. It can also name a navigation that is not in the trace at all, when recording started after it; trace_engine drops the metric when that happens.

ts is a presentation time, not a paint time. It is the timestamp the display compositor reported for the frame, so on a real display it is tens of milliseconds after the main-thread Paint slice that drew the content, and it lands on a display refresh. Do not line it up with the paint work; that is not what it measures. Chrome 141 still wrote a thread timestamp on this mark, which shows the backdating directly: firstContentfulPaint and firstPaint shared a ts to the microsecond while their tts values were 64 microseconds apart.

It is not the number the page can read. performance.getEntriesByType('paint') rounds first-paint up to the next multiple of 4 milliseconds unless the page is cross-origin isolated. The trace keeps the uncoarsened value, so the two will not match, and the trace is the more precise of the two.

Chrome 153 writes no tts on this event. Chrome 141 did. In a 153 capture the events written with an explicit timestamp, this one and navigationStart, have no thread time, while RunTask, Paint and Commit still do. Both headless, same trace config, one machine.

DevTools does not show it. The Performance panel builds its Timings markers from a fixed list of navigationStart, soft navigation start, LCP candidates, FCP, DCL and Load, and this event is not on it; the Timings track itself appends only user timings and extension markers, and the event's flame-chart style is declared hidden on top of that. The panel still has a "First Paint" label, an "FP" abbreviation and a green marker colour that nothing reads, and the trace engine still parses the event into a metric score, with no good or poor rating attached. Read from devtools-frontend source; the panel itself was not opened.

In the file it comes after firstContentfulPaint. When both fire from the same frame they share a timestamp, and the write order follows the iteration order of a hash set, not the order of events. Sort on ts and expect ties.

{
  "name": "firstPaint",
  "cat": "loading,rail,devtools.timeline",
  "ph": "R",
  "ts": 1102971047,
  "tts": 133866,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "navigationId": "F19F977AB13E669964965F7427E6F7B2"
    },
    "frame": "14A831DCB73EB1205B67CDB89FC6EBD7"
  }
}

See also firstContentfulPaint · largestContentfulPaint::Candidate · navigationStart · Paint · Commit · DrawFrame

categories

loading, rail, devtools.timeline

usage

rare

references

inspector_trace_events.cc, paint_timing.cc

Blink works out what is at a given point on the page.

Spec

LayoutView::HitTestNoLifecycleUpdate searches one frame's paint layers for whatever lies at a point, or inside a rectangle, on the main thread of the renderer that owns the frame.

Arguments

Observed 10,373 times on 174 of 300 sites.

Behaviour

Two unrelated pieces of Chromium write an event called HitTest. The one this entry is about is a slice with a duration on blink,devtools.timeline, carrying an endData object. The other is an instant on the compositor thread, on the input category, whose only argument is disposition: before a touchstart is sent anywhere, the compositor tests it against its own copy of the layer data to decide whether the main thread needs it, and disposition is that answer. A Performance recording never contains the second one, because DevTools does not record input.

The main-thread slice is Blink asking a paint layer tree, the structure it paints a frame from, what lies at a point or inside a rectangle. It is written whether the answer was computed or served from the per-document hit test cache, which holds two entries and is thrown away by any style recalculation, any layout and any DOM change.

What the count follows is callers and frames. Every mouse move, press, release, context menu and drag update makes one, and a point over nested same-process frames makes one per frame level it passes through. A single click makes several: the move that precedes it, the press, the release and the targeting that dispatch does, all but the first usually served from the cache in a microsecond or two. A tap asks twice over, a rectangle of candidates for touch adjustment and then the adjusted point, and that pair repeats across the touch and gesture events. document.elementFromPoint and elementsFromPoint each make one per call, under a FunctionCall, so they are attributable to your script.

The largest source on a busy page is none of those. After every layout, and at the end of every scroll, Blink marks the hover state dirty, and at the top of the next main-thread frame WebFrameWidgetImpl::BeginMainFrame clears that flag by dispatching a synthetic mouse move at the pointer's last known position. That is a full hit test, with move set, and no user input is involved. So a page that lays out every frame hit tests every frame, and a page being wheel-scrolled hit tests once per scroll rather than once per frame: scrolling itself does no main-thread hit test, it just keeps moving the page under a stationary pointer. The whole mechanism is gated on the pointer having moved at least once. In one capture an animating page whose mouse was never touched produced none of these in five seconds; the same page, with a single mouse move at the start, produced one in each of its three hundred frames.

IntersectionObserver produces them only with trackVisibility: true. That option is the v2 occlusion check, Blink refuses it unless you also pass a delay of at least a hundred milliseconds, and that delay is what paces the tests: each update hit tests each intersecting target's rectangle, inside IntersectionObserverController::computeIntersections. Six hundred plain observers produced none.

Blink hit tests your page on its own account too. An ad detector tests the centre of the viewport, at most once a second, looking for an overlay interstitial; in Chrome 153 a second one tests nine-tenths of the way down, looking for a sticky ad. Both run inside Commit, on every page, ads or not, but only after the first contentful paint and only while the page is still producing main frames. A tab that has gone quiet produces neither: a static page with nothing animating and nobody pointing at it wrote no hit tests at all in five seconds.

Derivations

The element, without any correlation work. nodeId is a DOMNodeId, which is the same number CDP calls a backendNodeId: DOM.describeNode or DOM.resolveNode will turn it into a node while that renderer is still alive. In a saved trace you still have nodeName, which names the node and, for an element, carries its id and class attributes.

The main-thread cost of hit testing for one interaction. Sum dur over the events in an input task and you have work that sits directly in the interaction's critical path and that nothing else in a trace measures. Discount the nesting first (see traps).

Traps

Most of what a hit test costs is outside the slice. Except when a caller has already guaranteed a clean lifecycle, a hit test first runs style, layout, compositing inputs and pre-paint, and all of that happens in LayoutView::HitTest, the enclosing function, before the traced slice opens. Chromium's own comment at the call site says "LayoutView::hitTest causes a layout". In one capture of a :hover rule that changes height, the enclosing call was 1,308 microseconds, of which the hit test was 20: 63 in UpdateLayoutTree, 471 in Layout, 712 in PrePaint. Even with nothing dirty the enclosing call ran about twice the slice. DevTools does not connect the two, and it will not call it a forced reflow either: its warning only fires for a layout with a JavaScript call on the stack, and this one has none.

Two emitters, one name. Keep the compositor's instant out of any count: it has no dur, no endData, and describes a decision about a touch, not a search of the page.

Filtering on ph of X silently drops the cheapest ones. A hit test served from the cache can take zero nanoseconds, and Perfetto's JSON exporter writes a zero-duration slice as an instant with no dur. The endData is all there.

Every field but x and y is present-or-absent. None of them is ever written as false, so endData.move === false is never true and absence is the only negative.

A one-microsecond hit test is a cache hit, and its flags belong to an earlier test. The slice opens before the cache is consulted, and a hit replaces the whole result, the request that produced it included. The payload is then built from that request, so move and touch describe whichever test filled the cache rather than the one you are looking at. This is why a mousedown, whose own request never sets the flag, routinely reports move: true a microsecond after the mouse move that preceded it.

move does not mean the user moved the pointer. It is the flag Blink sets for the mouse-move code path, which the synthetic hover update also goes through. The complement is not "a click": it includes both ad detectors, every elementFromPoint and every IntersectionObserver occlusion test.

rectilinear tells you nothing. Every point-based test sets it, by construction, and so does every rectangle. Only a quad-based test can leave it out.

There is no node on a list-based test. elementsFromPoint and touch adjustment ask for a list rather than a target, and the payload builder writes listBased instead of the node, never both. A test that hit nothing has no node either.

Nested same-process frames write several events for one point, and the durations nest. A gesture that descends through three same-origin iframes wrote four slices, each enclosing the next, with x,y stepping into each frame's own coordinates and all four naming the innermost node. Pointer moves over the same page wrote three, this time as siblings, each naming its own frame's node. Adding dur up across a page with iframes double counts; a single point producing several events is a frame count, not a symptom.

nodeName is Node::DebugName(), not a tag name. For an element it is the tag name followed by the id and every class, quoted: DIV id='b7' class='b'. For text it is #text, because the node a hit test resolves is a node, not an element. Treat it as a label, not as anything to parse or select with.

The coordinates are the frame's own, and a rectangle reports its centre. Scroll offset is not applied, so a point that stays under a stationary pointer keeps the same coordinates through a four-thousand-pixel scroll, and an event from a subframe is in that subframe's space. Page scale is divided out, so with a fallback layout viewport the numbers are not the device's CSS pixels: a tap in the middle of a 390-pixel-wide emulated screen with no viewport meta tag reported x of 490, half of the 980-pixel layout viewport. On a rect-based test, x and y are the centre of the rectangle, not a corner.

DevTools draws the bar and shows none of this. There is no detail handling for the event, so the summary pane offers nothing beyond the timings, and the node is never linked, because the code that resolves node ids to elements reads args.data.nodeId for a fixed list of event names and this one is neither on the list nor in that shape. Everything useful is in the trace JSON.

Only two of the callers survive a default recording. A hit test inside Commit is one of Blink's ad detectors; one inside FunctionCall is your own script. LayoutView::HitTest, EventHandler::handleMouseMoveEvent and WebFrameWidgetImpl::BeginMainFrame are all on categories the Performance panel does not record, so every other hit test is an unattributed bar. Turning on "Show all events" replaces DevTools' category filter with a wildcard and records them.

Depth is not what makes one expensive; count and positioning are. Across one set of runs on one build and machine, 40 pointer moves over 600 boxes took a median of 34 microseconds each. Nesting those boxes 200 levels deep took it to 47. Adding 20,000 plain in-flow boxes took it to 544. Positioning those 20,000 took it to about 3.5 milliseconds, per pointer move, and neither pointer-events: none nor putting them far off screen changed that. Why positioning costs so much is not established here, only measured.

{
  "name": "HitTest",
  "cat": "blink,devtools.timeline",
  "ph": "X",
  "ts": 1104756124,
  "dur": 13,
  "tdur": 12,
  "tts": 207556,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "endData": {
      "move": true,
      "nodeId": 8,
      "nodeName": "DIV class='box'",
      "rectilinear": true,
      "x": 400,
      "y": 300
    }
  }
}

See also EventDispatch · Layout · UpdateLayoutTree · PrePaint · ComputeIntersections · Commit · EventTiming

categories

blink, devtools.timeline, input

usage

moderate

duration

typical

undeclared args

args.endData.nodeId, args.endData.nodeName, args.endData.rectilinear, args.endData.x, args.endData.y, args.endData.move, args.endData.rect, args.endData.listBased

references

layout_view.cc, hit_test_request.h, event_handler.cc, hit_test_location.cc, input_handler_proxy.cc

Chrome turns all the text in one block into positioned glyphs.

A DevTools Performance recording does not contain this event. Record blink with your own trace configuration to get it.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

Blink shapes the text of one inline formatting context into glyphs with HarfBuzz, plus a second pass for ::first-line when that style needs different glyphs, on the renderer's main thread.

Behaviour

One event is one inline formatting context: one block box that has inline-level content in it. A <p>, a table cell, a list item, an SVG <text>, the inner editor of an <input> or a <textarea>, or the anonymous block Chrome wraps around loose text that sits beside a block sibling. One event covers the whole of it, however the text is marked up inside. In local captures a paragraph containing an <em>, a <strong>, a link and a <span> produced one event, and so did a paragraph set in three fonts, a paragraph mixing English and Arabic, and a paragraph wrapping to dozens of lines. It is not one event per line, per font, per text node, per element or per shaping run.

Text is not required, only inline content. A block whose single child is an <img>, a <br>, an <input> or an empty <span> still has inline items to prepare and still gets an event. A block with no inline content at all gets none: an empty <p>, an empty <div>, a <p> holding only collapsible whitespace. Lists are the case that catches people out. With markers outside, which is the default, every marker is a block of its own, so a <ul> of three items gave six events and three empty <li> gave six as well, while list-style: none and list-style-position: inside each gave three.

Inside the slice Blink walks the block's inline items and coalesces adjacent text into as few HarfBuzz calls as it can, shaping straight across element boundaries wherever the font, the resolved direction and the run segment agree. It breaks the run at a control character, at a zero-width non-joiner, and at an inline box carrying an inline-start padding, margin or border or a vertical-align off the baseline (inline_node.cc:471-527, 1622-1660). None of those runs has an event of its own.

Chrome prepares a block again only when a flag on it, NeedsCollectInlines, has been set, and PrepareLayout clears that flag as soon as it has run (inline_node.cc:621-665), so one invalidation is one event however many times the block is laid out afterwards. Three things set it. A text change, through LayoutText::TextDidChange (layout_text.cc:1083). A web font arriving, through LayoutText::InvalidateSubtreeLayoutForFontUpdates (layout_text.cc:1086-1094), which also invalidates the block's cached inline items, so the reshape is a full one. And a style change that Blink classes as needing a reshape, which is a narrower thing than a style change that needs a layout: ComputedStyle::DiffNeedsReshape sets diff.needs_reshape, and only LayoutText::StyleDidChange and LayoutInline::StyleDidChange act on it (layout_text.cc:233-235, layout_inline.cc:172-173).

That one rule predicts the whole matrix. On a local fixture, font-size, font-family, font-weight, font-kerning, font-variant-caps, letter-spacing, word-spacing, text-transform, white-space, direction, writing-mode and -webkit-text-security each produced exactly one event, as did every edit to a text node, appending a block, and restoring one from display: none. Halving the container, resizing the window, and changing padding, margin, color, background, line-height, text-align, text-indent, tab-size, outline and vertical-align produced none, although every one of those laid the page out again. A border is the odd one: putting a border on an inline box reshapes the block, because it breaks the shaping run there, and changing the width of a border it already had does not. (Chrome 153, Linux, headless, one profile.)

A web font finishing its download invalidates every block set in it, and re-shapes exactly those. In one capture the chain ran RemoteFontLoaded, StyleEngine::InvalidateStyleAndLayoutForFontUpdates, Layout, and then three of these events for the three paragraphs in the late font, with the two in the fallback stack untouched.

One path does not go through layout at all. When script edits part of a text node rather than replacing it, InlineNode::SetTextWithOffset re-shapes the block on the spot (inline_node.cc:1031); in a capture that event sat inside the timer task that called replaceData, with no Layout slice above it.

Derivations

How much of a layout was text. The layout-path events nest inside the Layout slice DevTools already draws, and summing them within one Layout gives the share of it that was shaping, which is the only breakdown of a layout slice Chrome offers outside SVG text. It takes a recording with both categories in it: Layout is devtools.timeline and the shapes are blink, so a blink-only trace has the shapes and nothing to nest them in. On local fixtures that share ran from 8 to 39 percent, the high end being the relayout after a web font arrived.

What a font swap cost, and which blocks paid it. The events that follow RemoteFontLoaded are the reshaping that font-display: swap bought: the count is the number of text blocks that used the font and the sum is the shaping time spent on them. Neither number appears anywhere else, and the layout shift the swap causes tells you nothing about either.

Whether your text is being shaped once or repeatedly. Every event after the first layout is a block whose glyphs Chrome threw away and recomputed, and the load-time count is the page's total of blocks with inline content to measure it against.

Traps

A default DevTools Performance recording cannot contain this event. The panel records a fixed list of categories that does not include blink (TraceEvents.ts:3301), and the fixture that gave one event per paragraph on the blink category gave none under that list. There are two ways round it. Record blink yourself, through the Perfetto UI, chrome://tracing, or Tracing.start over the DevTools protocol. Or turn on Settings > Performance > Show all events, which switches the panel's category filter from - to and draws events it has no model for under their raw name (TimelineController.ts:424-428, ThreadAppender.ts:376). The second is expensive: the same page recorded several times as many events as the default configuration, where recording blink on its own got the same events in a far smaller trace. It also costs you the context: Layout is on devtools.timeline, so a blink-only trace has every shape and no layout slice to attribute it to.

There are no arguments. TRACE_EVENT0 writes a name and a duration and nothing else (inline_node.cc:1859): no element, no url, no character count. Nothing in the trace says which block a slow shape belongs to, so you get a total and a count, and attribution comes from bisecting the page.

The fastest shapes are not phase X. A slice whose duration rounds to zero is exported as "ph": "I" with no dur at all (export_json.cc:886-890), and short shapes round to zero readily. Filtering on ph === "X", or on the presence of dur, drops them silently, and how many it drops depends on the machine and on how short the text is: a fixture of 1,500 one-character paragraphs put a different slice of them in the instant bucket on every run.

A ::first-line rule that changes the font makes each event cover two full shapes of the whole block, not of the first line. Line breaking has not run when the shaping happens, so Blink cannot know which characters are on the first line and re-shapes every item in the node with nothing to reuse, whenever the first-line font differs from the block font or a first-line text-transform rewrites the string (inline_node.cc:1785-1853). The event count does not move, so the cost hides unless you compare durations: on a 40-paragraph fixture, total shaping went from 571 us with no rule to 1,374 us for a font-family rule and 1,574 us for font-weight, with text-transform at 1,083 us. A color rule stayed level, because it needs no reshape at all. Medians of five loads each.

Width does not reshape, but a width that changes the font does. Glyphs and advances survive re-layout at a new width, so resizing the window emits nothing. Size the text in vw, or switch font-family at a breakpoint, and every block in the page reshapes on every resize, through the font rather than through the width.

Not every event is inside a Layout. The SetTextWithOffset path fires during the DOM mutation, so do not assume a parent slice when attributing these to a frame.

The count is a block count, not a measure of how much text there is. The same 24,000 characters split into 20 blocks and into 2,000 blocks gave 20 events and 2,000 events, and about twice the total time, not a hundred times.

The slice is the shaping only. Collecting the block's inline items and segmenting the text into script runs happen immediately before it in the same PrepareLayout and write nothing to the trace, so inline layout costs more than the sum of these events.

{
  "name": "InlineNode::ShapeTextIncludingFirstLine",
  "cat": "blink",
  "ph": "X",
  "ts": 1102943300,
  "dur": 249,
  "tdur": 153,
  "tts": 40884,
  "pid": 8257,
  "tid": 8257,
  "args": {
  }
}

See also Layout · RemoteFontLoaded · LocalFrameView::UpdateStyleAndLayout

categories

blink

usage

high

duration

short

references

inline_node.cc

Something has made layout out of date, and Chrome has scheduled the page to be laid out again.

Spec

Blink's LocalFrameView schedules a relayout, after a dirty layout bit has propagated up the box tree as far as a layout root, on the renderer's main thread.

Arguments

Observed 31,873 times on 182 of 300 sites.

Behaviour

Marking an element dirty is not what writes this event. Blink sets a bit on the element, then walks up its container chain setting a bit on each ancestor, and it abandons that walk at the first ancestor that already carries one. Only a walk that runs the whole way to a layout root ends in a call to LocalFrameView::ScheduleRelayout or ScheduleRelayoutOfSubtree, and those two functions are the only places the event is written. A layout root is either the frame's LayoutView, which stands for the whole document, or a box Blink is able to lay out without touching anything above it.

So the event marks a transition from clean to scheduled, once per layout root, rather than one dirtied element. In one capture, twenty inline-style writes to a single element produced one event; five removeChild calls in one task produced one, whose stack named the enclosing function and not any particular removal; two separately contained subtrees dirtied in the same task produced two, one each. Per-element dirtying, with a reason string and the element's name attached, is a different event on a different category: LayoutInvalidationTracking. There are far more of those.

That also makes nodeId the layout root and never the element you changed. On the frame-wide path Blink passes the LayoutView's node, which is the document, so every frame-wide invalidation in a frame reports the same id. On the subtree path it passes the boundary box, which is an element you will recognise, and the Layout that follows carries beginData.partialLayout: true.

Whether a box can be a boundary is a long list of conditions, and the ones that catch people out are the ones that disqualify it. It needs a layer of its own to paint into, it cannot be fragmented across columns or pages, and it cannot be a table part, a flex item, or anything inside a grid, whatever else is set on it: contain: strict on a flex item is not a boundary, and neither is the same box inside a grid. Past those, what qualifies a box is layout and size containment together, or being an SVG root, or having a fixed width and height and either clipping its overflow on both axes or being a text control. A fixed-size input with position: relative is a boundary; the same input with no layer of its own is not.

Nothing about any of this is specific to script. An image finishing its download, a web font arriving and a change of viewport size each schedule layout the same way, and a font can dirty the whole tree.

A frame-wide invalidation does not stop a second one arriving in the same rendering update. Blink tracks a full relayout and a simplified one, the kind a moved out-of-flow box needs, with separate bits, so the second walk can travel a chain the first has already marked and reach the document again. Changing a normal box and moving an absolutely positioned box in one task gave two events with the same nodeId and one Layout after them.

Three situations produce no event at all. Dirtying something while layout is already running is suppressed outright. The frame-wide path is also gated on Document::ShouldScheduleLayout, which holds until render-blocking resources have loaded and a body exists, so early parsing produces none. And a caller can mark an object without marking its container chain, which never schedules anything. A fourth is easy to hit by accident: a change inside a content-visibility: hidden subtree writes nothing, not this event and not the per-element one.

Derivations

Whether your containment is doing anything. Read the nodeId values between two Layout events, and read what they are rather than how many there are. One that resolves to the document is a relayout of the whole frame; anything else is a box Blink could lay out on its own, and the matching Layout will say partialLayout: true. A page that means to confine its work and keeps reporting the document is not confining it. No other event in the trace names the boxes layout was actually scheduled from.

How long a scheduled layout waited. The gap between an invalidation and the Layout that follows it on the same frame is the delay between something going out of date and Blink doing anything about it: microseconds when the invalidation happened inside the style recalculation of the update that is already running, a frame or more when it happened in a task of its own. This is the number DevTools prints as "Pending for" when you select a Layout.

The difference between "no script did this" and "no stack was captured". Record disabled-by-default-v8.cpu_profiler as well, and sampleTraceId resolves against cpuProfile.trace_ids inside ProfileChunk, which points at a node in the profile's call tree. In a DevTools recording of a real page, every one of the events resolved, and every event without a stackTrace landed on (program): V8 was not executing JavaScript at that instant. That is a positive answer, where a missing field on its own is not.

Traps

A stackTrace names whatever scheduled the layout, which is often not what changed the page. Writing to style, toggling a class and appending an element all leave layout alone at the time; the layout bit is set later, inside the style recalculation that runs in the next rendering update, and no script is on the stack by then. Removing a node or replacing textContent destroys layout objects there and then, so the walk reaches the root inside your task and you do get a stack. A forced read such as offsetHeight pulls the style recalculation back into the same task, which is why layout thrashing always leaves one. Recording the stack category and finding no stack is evidence about when layout was scheduled, not about whether script was responsible.

Stack depth measures your recorder, not the page. V8 captures one frame unless a client has the Runtime domain enabled, and then up to 200. A loop three functions deep gave a single frame under Chrome's own --enable-tracing and more than one under Puppeteer. Never compare depth across traces made with different tools. The frames run top first, so stackTrace[0] is the line that ran, and its line and column numbers count from one.

stackTrace and sampleTraceId are both gated on disabled-by-default-devtools.timeline.stack. Without it they are simply absent, and nothing in the output distinguishes that from no stack being available. With it, every invalidation also takes a V8 CPU profiler sample it would not otherwise take.

nodeId has no name beside it, and the id belongs to one renderer process. LayoutInvalidationTracking carries nodeName and this event does not, so resolving it means CDP or a trace that has both categories, and a default DevTools recording has neither: the per-element category is not one it records. Worse, backend node ids are handed out per process, so an id written by another process resolves against your document to a real element that has nothing to do with it. In one capture, three events from a second renderer carried the same id as the page's own head. Check args.data.frame before you resolve anything.

The Performance panel does not draw this event. DevTools marks it hidden, so it never reaches the flame chart unless Show all events is on, and an initiator arrow needs both of its ends drawn. What you usually see pointing at a Layout is a ScheduleStyleRecalculation, which DevTools substitutes when the invalidation happened inside a style recalculation that had an initiator of its own. The event does appear in the Layout's details pane, as the stack under "First layout invalidation", an "Initiated by" link and "Pending for". Either way DevTools keeps only the last invalidation for the frame and forgets it once a Layout has used it, so when several layout roots were invalidated the earlier ones are dropped.

LayoutInvalidationTracking is not a superset of this event. Only the call that marks an object as needing layout itself writes one. Marking an ancestor, or marking a box for the simplified layout that a moved out-of-flow element needs, goes straight to the container walk. Moving an absolutely positioned box by changing top produced an InvalidateLayout and no per-element event at all.

scriptId inside stackTrace is a string, not a number.

Chrome's own internal documents write these too. A six second headless recording of one trivial page carried events from six frames across four renderer processes, with stacks from Chrome's own interface code. Filter on args.data.frame.

{
  "name": "InvalidateLayout",
  "cat": "disabled-by-default-devtools.timeline",
  "ph": "I",
  "ts": 1102950855,
  "tts": 45968,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "nodeId": 3,
      "sampleTraceId": 6909218608594504,
      "stackTrace": [
        {
          "columnNumber": 81,
          "functionName": "note",
          "lineNumber": 24,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        },
        {
          "columnNumber": 5,
          "functionName": "",
          "lineNumber": 47,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        }
      ]
    }
  }
}

See also LayoutInvalidationTracking · Layout · UpdateLayoutTree · ScheduleStyleRecalculation · Blink.ForcedStyleAndLayout.UpdateTime

categories

disabled-by-default-devtools.timeline

usage

moderate

undeclared args

args.data.sampleTraceId, args.data.stackTrace[].columnNumber, args.data.stackTrace[].functionName, args.data.stackTrace[].lineNumber, args.data.stackTrace[].scriptId, args.data.stackTrace[].url

references

source_location.cc, v8-stack-trace-impl.cc, v8-debugger.cc, local_frame_view.cc

An element has reached the screen that is larger than every contentful element shown before it, which makes it the page's Largest Contentful Paint so far.

Spec

Blink's LargestContentfulPaintCalculator names a new Largest Contentful Paint for one document, written on the renderer's main thread when a frame reaches the screen carrying a contentful element whose visible area beats every candidate that document has already reported.

Arguments

Observed 619 times on 179 of 300 sites.

Behaviour

Blink keeps two records for each document: the largest text it has painted, and the largest image. When the display pipeline reports back that a frame has been presented, the calculator takes the larger of the two and, if it beats the size of the last candidate it reported, writes this mark and hands the same value to the page's PerformanceObserver. The test is against the last size reported, not against the runner-up, so the candidates only ever climb, and an element that merely ties writes nothing.

The mark is backdated. It is written while the presentation callback runs, but its ts is the raw presentation timestamp the display pipeline gave for that frame, which is earlier. Where the event sits on the timeline is when the element reached the screen, not when Chrome worked out that it had.

Size is what Chrome saw, not what the page declared. size is the area of the element's box clipped to the viewport, in CSS pixels, and then, if the box is larger than an image's natural size, divided by the factor it was stretched by. A 400x300 image displayed at 800x600 reported 120000, its natural area; an 800x600 image with 160 px below the fold reported 352000.

Three rules take an image out of the running completely: one with no viewport intersection at all is never recorded, so an image appended below the fold produces nothing; one whose clipped area reaches the viewport's own area is discarded, so a hero sized to 100vw by 100vh never becomes a candidate while the same hero at 99vh does; and one carrying less than 0.05 bits per displayed pixel is judged too sparse to be content. All three belong to images, because the function that applies them is called from the image detector alone. Text is judged on one thing, that its clipped area is not zero, which is why a block of text measured at exactly the viewport's area was a candidate where the image was not. Fully transparent text, with no shadow and no stroke, is never recorded. An element removed from the page between painting and presenting is dropped before the comparison; one removed after its candidate was written simply stands.

Several candidates are normal, because they are a record of what the largest thing on screen was at each point in the load. A heading usually paints before the hero image finishes, so the common shape is a text candidate and then an image one. Content that arrives later adds one more each time it is the largest yet.

Every document runs its own calculator. A cross-origin iframe writes its own stream, in its own process, with its own candidateIndex starting at 1 and its own navigationId, and none of it counts towards the top-level page's LCP. A soft navigation writes largestContentfulPaint::CandidateForSoftNavigation from this same call site instead.

The stream ends at the first real interaction and is never closed. PaintTiming::NotifyInputEvent drops the calculator for any input that reaches the main thread except a mouse move, a mouse enter or leave, a key up and a pinch gesture, and NotifyScroll drops it for any user or compositor scroll. On a fixture whose hero grew afterwards, a click and a key down each ended the stream in every run and a mouse move never did. A wheel is the case to watch: on a page too short to scroll and with no wheel listener the stream survived every run, because the compositor handled the wheel by itself and the renderer never saw it, but one passive wheel listener on the same page ended it every run.

Derivations

LCP itself, to a precision the page cannot see. Subtract the ts of the navigationStart sharing this event's navigationId from the ts of the last candidate for that navigation with isOutermostMainFrame true. The trace carries the presentation timestamp raw, while PerformanceObserver rounds startTime up to the next multiple of 4 ms on any page that is not cross-origin isolated. Across 60 paired observations every API value was an exact multiple of 4 ms and landed 0.02 to 3.98 ms after the trace's, never before.

The image half of the LCP breakdown, from this event alone. imageDiscoveryTime is when the fetch was queued, imageLoadStart when the request went out, imageLoadEnd when the last byte arrived, and ts minus imageLoadEnd is the element render delay that followed, once the two are in the same units. No network event needs to be matched up, which matters because matching one to an element is the awkward part. DevTools does not use them: its LCP breakdown insight finds the network request instead, by way of the image URL on LargestImagePaint::Candidate.

Traps

Not every candidate is the LCP, and the last one in the trace often is not either. Group by args.frame and navigationId first and take the highest candidateIndex in that group. On a page with a cross-origin iframe, the iframe's candidate was both larger and later than the page's own, and the page's PerformanceObserver correctly ignored it. isOutermostMainFrame is the filter.

Two candidates can share a timestamp. Presentation callbacks queue up and are drained together, so a text and an image candidate were written with identical ts and with candidateIndex 1 and 2. Order by candidateIndex, never by ts alone.

candidateIndex counts what was written, not what happened. The counter lives inside the payload builder, which the trace macro only runs when the category group is enabled. A recording started a second into a load whose page had already produced two candidates showed one event, numbered 1, while the page's own PerformanceObserver still reported three entries. Nothing in the trace says the earlier ones existed.

This is not the number CrUX reports. The field metric travels a separate path out of the same class. It is computed from different members, taking an image that has painted but not finished loading, and an animated image's first frame time rather than its paint time. The browser then merges the page's value with its subframes' and keeps it only if the paint happened while the tab was in the foreground. Its trace events are LargestImagePaint::Candidate and LargestTextPaint::Candidate, on the loading category, each with a candidateIndex counted separately from this one. For a static image or a text LCP the two agree; for an animated image, a video, or a page whose largest content is inside an iframe, expect them not to.

There is no URL on this event. DevTools gets one by looking up LargestImagePaint::Candidate on the same nodeId in the same process and reading its imageUrl. That event is on the loading category alone, so a trace recorded with only devtools.timeline has the LCP and no way to name the image.

nodeId is a DevTools backend node id, unique only inside one renderer process. A main frame and its iframe both used nodeId: 4 in one capture, so any lookup has to be keyed on the process as well. It resolves to an element only against a live page; in a saved trace, nodeName (the tag plus its class or id) is all the identification there is.

loadingAttr tells you what kind of element this is, not just what the attribute said. The key is written only when the candidate is an <img>. An <img> with no loading attribute gets an empty string, so the value you see most is "". The key missing altogether means the candidate is not an <img>: text, a CSS background image, a video poster or first frame, an SVG <image>, an <input type=image>. All of those still report type: "image" apart from text, so type will not tell them apart.

The three image times are milliseconds since that frame's own time origin, as floats, while ts is the trace clock in microseconds. In an iframe they are relative to the iframe document's origin, not the top document's.

They describe the resource, not this element. When a second, larger element used an image the page had already downloaded, its candidate repeated the original download's discovery, start and end times, while the PerformanceObserver entry for the same paint reported a loadTime 800 ms later. If you want when this element's image became available, the trace event is not where it is.

An image served without Content-Length can drop out of LCP entirely. The minimum-entropy check takes the response's expected content length, or the bytes received so far when there is no such header, and divides its bits by the displayed area. It is computed once, when the image's record is created at its first paint, and never revisited for that record. So the number that decides it is the bytes in hand at first paint against the displayed area times 0.00625, and a hero first painted on a few kilobytes of a streamed response stays below the threshold forever. A progressive JPEG shown at 1280x755, so needing 6040 bytes, and dribbled out in 1 KB chunks: with the header the image was the LCP in three runs of three, without it the LCP stayed on the <h1> in three of three and the image produced no candidate at all. The same page in 8 KB chunks, which put enough bytes in hand before the first paint, kept the image as the LCP in two runs of three even without the header. Unthrottled, and on a repeat view from the HTTP cache, where the bytes arrive at once, it always counts, so the same page can report a different LCP element on a first and a second visit.

With decoding="async" the candidate can be stamped before the pixels are on screen. The compositor may present a frame with a large image's box still blank and fill it in later, and the LCP is recorded on one of those frames. On an ordinary page the reported LCP came in 15 to 29 ms ahead of the frame that actually showed a 1920x1080 hero, and 76 to 138 ms ahead for a 4000x3000 one. It needs an image that is static, fully downloaded when it was first drawn and at least a megabyte of decoded pixels, so a cold first load is unaffected and a repeat view or a preloaded hero behind slow CSS is not.

trace_engine does not declare size, performanceTimelineNavigationId or any of the three image times, so anything typed on that package sees an event without them. It does declare loadingAttr as always present, which it is not.

The candidate stream is not a closed set. If a trace stops before the page does, a larger element may have arrived afterwards and there is no marker saying the value was final. largestContentfulPaint::Invalidate, which withdrew a candidate, was removed in Chrome 88; a candidate whose element is later removed from the page simply stands.

{
  "name": "largestContentfulPaint::Candidate",
  "cat": "loading,rail,devtools.timeline",
  "ph": "R",
  "ts": 1108451601,
  "tts": 119589,
  "pid": 8407,
  "tid": 8407,
  "s": "t",
  "args": {
    "data": {
      "candidateIndex": 1,
      "imageDiscoveryTime": 70.19999999995343,
      "imageLoadEnd": 135.9000000001397,
      "imageLoadStart": 117,
      "isMainFrame": true,
      "isOutermostMainFrame": true,
      "loadingAttr": "eager",
      "navigationId": "BAAF482071D29F77645D385F984F23B2",
      "nodeId": 274,
      "nodeName": "IMG class='Image-styles__ImageStyled-sc-8c99a12b-0 cVsHni'",
      "performanceTimelineNavigationId": 4052,
      "size": 213752,
      "type": "image"
    },
    "frame": "2EA8810E92C12C680C55B2941251AA98"
  }
}

See also largestContentfulPaint::CandidateForSoftNavigation · largestContentfulPaint::Invalidate · LargestImagePaint::Candidate · firstContentfulPaint · navigationStart · Decode Image

categories

loading, rail, devtools.timeline

usage

low

undeclared args

args.data.imageDiscoveryTime, args.data.imageLoadEnd, args.data.imageLoadStart, args.data.performanceTimelineNavigationId, args.data.size

references

image_resource.cc, largest_contentful_paint_calculator.cc, resource_fetcher.cc, performance.cc, window_performance.h, paint_timing_record.h

Chrome records the largest text or image painted in the page's response to a single user interaction, separately from the document's own largest contentful paint.

Spec

Blink's LargestContentfulPaintCalculator has a new largest contentful paint for one SoftNavigationContext -- the record Chrome keeps of what a single user interaction changed -- and marks it on the renderer's main thread at the presentation time of the frame that painted it.

Arguments

Observed 18 times on 15 of 300 sites.

Behaviour

Blink runs a second largest-contentful-paint calculation alongside the document's own. Both are driven by the same class, LargestContentfulPaintCalculator, and each one asks its owner a single question: is this a hard navigation? The document's owner says yes and gets largestContentfulPaint::Candidate; a soft navigation context says no and gets this name. Both names are written by the same two functions, so the payloads are identical but for one field, which is the only thing that reliably tells them apart (see traps) (largest_contentful_paint_calculator.cc:218-227 and 259-266).

A soft navigation context is Chrome's record of one user interaction and everything that interaction went on to change. Chrome creates one for every event that counts as an interaction -- a click, a tap, a key press -- while the event is being dispatched, long before it knows whether a route change is coming (event_timing.cc:144-146, soft_navigation_heuristics.cc:674-698). Each context builds its own calculator (soft_navigation_context.cc:31-33), and that calculator writes this event.

A paint belongs to a context when the interaction's own code modified the painted node, or an ancestor of it. Chrome follows the interaction through promises, timers and continuations to decide that, and when two interactions have touched the same node the most recent one wins (soft_navigation_paint_attribution_tracker.h:19-73). After every presented frame, Chrome sorts the frame's text and image paints into the contexts they belong to and hands each context its own largest (soft_navigation_heuristics.cc:516-530). The timestamp is the presentation time of that frame (paint_timing.cc:607-623).

Nothing in that path asks whether a soft navigation happened. The heuristics -- the URL changed, the DOM was modified, enough area was painted -- gate SoftNavigationStart and the performance entries, not this event. A click that swaps in a paragraph and changes no URL produces one of these; so does a click that appends a single character. In a 300-site crawl that clicked once on each page, the corpus contains these events and not one SoftNavigationStart to go with them.

candidateIndex counts up within one interaction and starts again at one for the next, because the counter belongs to that context's calculator. It is not a position in the document's candidate stream.

The stream ends the way hard LCP does. Once a context has painted something, the next click, key press or user scroll freezes it, and later paints attributed to that interaction are no longer reported (paint_timing.cc:962-989, soft_navigation_context.cc:174-187). An interaction that has not painted yet is not frozen by further input, and a newer interaction never ends an older one, which is how a context can outlive several later ones.

Derivations

Soft LCP. Pair the event with the SoftNavigationStart whose performanceTimelineNavigationId matches, and the gap between the two timestamps is how long the route change took to render, measured from the interaction that started it -- SoftNavigationStart is stamped at the interaction's own start time (soft_navigation_context.cc:65-67, 256-260). That is the number DevTools computes (PageLoadMetricsHandler.ts:207) for the marker it draws in the Timings track as "Soft Largest Contentful Paint", and nothing in the page's own LCP reporting will match it: a soft navigation produces no largest-contentful-paint entry at all, so a script watching for LCP never sees the route change, and the interaction-contentful-paint entry that does carry the paint starts its clock at the interaction rather than at the paint.

The image sub-phases. When the candidate is an image, imageDiscoveryTime, imageLoadStart and imageLoadEnd split the wait into discovery, download and render delay, exactly as they do for a hard navigation's candidate, and every image candidate carries all three. They are measured from the document's time origin, so subtract the soft navigation's own start time first; what is left tells you whether the route change's hero image was requested late or merely arrived slowly.

Traps

Most of these are not soft navigations. The event is written for any interaction whose paints Chrome can attribute, whether or not the URL changed and whether or not enough of the page was repainted. Counting them, or reading each one as an SPA route change, overcounts badly: a crawl that clicks once per page collects them from sites that never soft-navigated at all. Only an event you can pair with a SoftNavigationStart describes a soft navigation.

performanceTimelineNavigationId is the window's current navigation id, not the interaction's. Chrome reads it off the performance timeline at the moment it writes the event (largest_contentful_paint_calculator.cc:499-501), and the timeline's id only advances when some context commits a soft navigation. So an interaction that never became one carries the hard navigation's id, and joining candidates to navigations on that field alone drops an interaction's paint into the initial page load. Worse, an interaction whose paint is still pending is not frozen by the click that starts the next one, and a context that no longer owns the URL can never commit -- so its later paints are stamped with whatever soft navigation is current by then. A fixture where one button changes the URL and paints a second later, while a second button changes the URL and paints at once, reliably produced two candidates from two different interactions under one navigation id.

candidateIndex is per interaction, so two events in one trace can both be candidate one. In the case above, both were. Anything that assumes the index orders a navigation's candidates, or that a higher index is a later candidate, is reading a different counter than it thinks. DevTools only replaces a stored candidate when the index is strictly higher (PageLoadMetricsHandler.ts:229-239), which is what stops the stray candidate above from becoming the reported soft LCP; a hand-rolled "last candidate wins" join has no such protection.

There is no navigationId, and that absence is the only reliable way to tell the two candidate events apart from their payloads. performanceTimelineNavigationId is on both. Chrome writes the loader-id navigationId only for a hard navigation, deliberately: the commit that introduced this name removed it rather than keep the sentinel value the old code used.

size is missing from trace_engine's declaration of the event and loadingAttr is declared as always present, so code built on those types cannot see the LCP size and will be surprised by the candidates that have no loadingAttr. loadingAttr is written whenever the element is an <img>, and it is written as an empty string when the attribute is absent, so an empty value means "no attribute", not "not an image"; a candidate with no loadingAttr at all was a CSS background image, a video poster or an SVG image.

The image timings are on a different clock from ts. ts is the raw monotonic presentation timestamp in microseconds; imageDiscoveryTime, imageLoadStart and imageLoadEnd are DOMHighResTimeStamp milliseconds from the document's time origin (largest_contentful_paint_calculator.cc:464-474). Subtracting one from the other produces nonsense.

Some image paints can never be candidates, soft or hard. An image whose visual rect fills the viewport is rejected outright, and so is one whose encoded bytes come to less than 0.05 bits per painted pixel (largest_contentful_paint_calculator.cc:648-669, 677-755). A flat-colour placeholder swapped in by a click paints, is attributed to the interaction, and still produces no candidate. Text is judged on painted area alone (largest_contentful_paint_calculator.cc:671-674).

DevTools discards the ones it cannot place. If the trace holds no SoftNavigationStart with a matching id -- because the interaction never became a soft navigation, or because the soft navigation happened before recording started -- the Performance panel drops the event silently (PageLoadMetricsHandler.ts:284-291). Turning off the "Enable soft navigation performance monitoring" setting drops every one of them, along with SoftNavigationStart (PageLoadMetricsHandler.ts:82-87, LiveMetrics.ts:17-22). Only the winning candidate per soft navigation is ever drawn.

The kill switch does not switch the whole event off. SoftNavigationTraceEvents is on by default and can be disabled from the command line, but it guards only the image branch and SoftNavigationStart; the text branch has no such check. Running with it off leaves you with text candidates and nothing to pair them to.

A trace from a Chrome before 145 has no events with this name. Soft navigation candidates were written as largestContentfulPaint::Candidate then, carrying the fixed sentinel navigationId deadbeef-dead-beef-dead-beefdeadbeef, which is what an old trace has to be filtered on and what a current trace does not.

See also largestContentfulPaint::Candidate · SoftNavigationStart · SoftNavigationContextCreated · EventTiming · firstContentfulPaint

categories

loading, rail, devtools.timeline

usage

rare

undeclared args

args.data.imageDiscoveryTime, args.data.imageLoadEnd, args.data.imageLoadStart, args.data.size

references

largest_contentful_paint_calculator.cc

Chrome threw away the LCP candidate it was holding, and had no other contentful element left to replace it with.

Chrome no longer emits this event. The code that wrote it was found in the history and then found to have been deleted.

Spec

Blink's LargestContentfulPaintCalculator was left holding neither a largest-text record nor a largest-image record, and wrote this instant on the renderer's main thread to say the document had no largest-contentful-paint candidate any more; Chrome wrote it from version 78 until version 88 removed it.

Behaviour

Blink works out LCP in two layers. Two detectors, one for text and one for images, each keep a record of the largest thing that has painted so far. A calculator, LargestContentfulPaintCalculator, takes both records after a paint and decides what to report to the page and to the trace. This event came from one branch of the calculator: if a held record had just changed, and the calculator was then holding neither a text record nor an image record, it wrote this instant and returned (largest_contentful_paint_calculator.cc:86-94 at 87.0.4280.141).

Neither, not either. A record went away when the element's layout object was destroyed, which covers being removed from the document and being given display: none, and losing the largest image while a text record was still held did not produce this event: it fell through to the size comparison below and produced a largestContentfulPaint::Candidate for the text instead. The event meant the document had run out of candidates altogether, not that a bigger candidate had been replaced by a smaller one.

It did not fire on input. The first qualifying input or scroll runs PaintTimingDetector::OnInputOrScroll, which stops both detectors (paint_timing_detector.cc:179-198); from then on the text side is not recording, and a stopped image detector ignores removals (image_paint_timing_detector.cc:154-175). No held record can disappear after that, so the branch cannot be entered. Finalisation is the end of the candidate stream, not an invalidation of it.

The payload was candidateIndex, isMainFrame and, from Chrome 79 on, navigationId, under args.data, with the frame id alongside in args.frame. No node, no size, no type: the event said a candidate was gone, not which one. candidateIndex came from count_candidates_, the same counter largestContentfulPaint::Candidate increments, so an invalidation consumed an index of its own.

The name was one of a pair added in August 2019 and first shipped in Chrome 78, by commit e7a0a11a0e6f, "Add renderer trace events for LCP.". Its stated reason was that DevTools could not easily consume the two browser-process events that already carried these names. Commit a5484e6310a3, "[LargestContentfulPaint] Allow removed content by default", deleted it in October 2020 for Chrome 88. That change made the web-exposed LCP monotonic: the calculator now keeps largest_reported_size_ and reports a new entry only for a candidate strictly larger than the last one it reported, and content that is removed keeps the entry it already produced. Remove every contentful element from a page on a current Chrome and the last candidate still stands. The condition this event reported can no longer arise, and nothing took its place.

Derivations

In a trace recorded on Chrome 78 through 87, this event is the only signal in the renderer stream that the largestContentfulPaint::Candidate before it is void. Chrome of that era reported whatever the detectors currently held, so LCP could go down: after an invalidation the next candidate may be smaller than the one before it. Take the last Candidate in such a trace and you may be reporting an element Chrome had already discarded; do what DevTools and Lighthouse both do, and let the highest candidateIndex for a navigation decide, discarding the result if it is an invalidation. From Chrome 88 the sequence of candidate sizes never decreases, so no correction is needed and the last candidate is the answer.

Traps

A live event has almost the same name and means something else. NavStartToLargestContentfulPaint::Invalidate::AllFrames::UKM is in current traces, on the loading category, and it is not this event withdrawing anything. It is written in the browser process by UkmPageLoadMetricsObserver::OnTimingUpdate as the plain else-branch of "is there a valid merged LCP time right now", so it means no LCP value at this timing update, which is the ordinary state early in a load. It carries main_frame_tree_node_id and nothing else, and it is older than the renderer event: the commit that added this one gave those browser-side events as the reason. There is a matching NavStartToExperimentalLargestContentfulPaint::Invalidate::AllFrames::UKM beside it.

DevTools never drew this event, but it did act on it. TimelineFlameChartDataProvider._appendPageMetrics kept, per navigation, the LCP event with the highest candidateIndex, and appended it to the Timings track only if it was a candidate. An invalidation at the end of the stream therefore removed the LCP marker from the Timings track altogether, and that was the only sign of it in the panel. As a marker in the overview ruler it was invisible: markerStyleForEvent had no case for the name, so it took the default non-tall style, createEventDivider sets a background colour only on a tall marker, .resources-event-divider declares none of its own, and its container carries pointer-events: none.

Today's DevTools ignores it. The name survives in devtools-frontend as Types.Events.Name.MARK_LCP_INVALIDATE, with no interface, no style, no handler, and no place in the marker list, so an old trace loaded into a current Performance panel shows the withdrawn candidate as the LCP and says nothing. Lighthouse is the exception: it still accepts the name as an LCP event, and a trace whose last LCP event is an invalidation comes back with lcpInvalidated set instead of an LCP.

Its timestamp is not a paint time. Candidate is a mark backdated to the element's paint time; this was an instant stamped when the calculator ran, at the end of a paint. Comparing the two as if they were the same clock overstates how long the page held a candidate.

Candidate numbering has gaps in an old trace, because invalidations took indices from the same counter. A jump in candidateIndex across two Candidate events is not a dropped or lost event.

LargestImagePaint::NoCandidate is live and sounds like a successor. It is not. It comes from LargestContentfulPaintCalculator::ReportNoMetricsImageCandidateToTrace on the metrics side, beside LargestImagePaint and LargestTextPaint, and it means the image candidate is not reportable yet, not that one was withdrawn.

See also largestContentfulPaint::Candidate · largestContentfulPaint::CandidateForSoftNavigation

references

largest_contentful_paint_calculator.cc

Blink turns the page it has just painted into the layers the compositor will draw from.

Spec

Blink's PaintArtifactCompositor groups the paint chunks the renderer has just painted into cc::Layers and builds cc's property trees from them, on the renderer's main thread, after paint and before the commit.

Arguments

Observed 26,989 times on 182 of 300 sites.

Behaviour

Blink paints a document once, into a single display list cut into paint chunks: runs of drawing commands that share one transform, one clip and one effect node. Deciding which of those chunks get their own compositor layer is a separate pass over the finished list, and that pass is this event. PaintArtifactCompositor::Layerizer opens a pending layer for every chunk, then tries to merge each new one backwards into the ones before it, stopping at the first whose bounds in screen space might overlap. What survives becomes the layer list, and a PropertyTreeManager turns the paint property nodes those layers reference into cc's transform, clip, effect and scroll trees. Chromium's own note on the algorithm puts its cost at O(pqd), where p is the number of paint chunks, q the number of merge attempts and d the depth of the property trees.

Chromium calls that ordering CompositeAfterPaint. Before it, layerization came first: a lifecycle phase named compositing assignments picked the layers, and painting then went into them one layer at a time. That phase was still in local_frame_view.cc in Chrome 98, behind RuntimeEnabledFeatures::CompositeAfterPaintEnabled(), and was gone from it in Chrome 99. The trace event is younger than the rearrangement: Layerize first appears in that file in Chrome 111, the release that also renamed CompositeLayers to Commit. In Chrome 110 the same code ran and was marked only by a blink-category event that no Performance recording asks for, so in a trace from 110 or earlier this work is simply not there.

It runs in the same main-thread task as the rest of the rendering update, between the last Paint and the Commit:

BeginMainThreadFrame
  UpdateLayoutTree, Layout, PrePaint, Paint
  Layerize                     paint chunks -> cc layers and property trees
Commit                         handoff to the compositor thread

It is never inside Commit. cc runs Blink's whole lifecycle before it opens that slice, and the "update layers" step cc does inside it is its own, copying Blink's display lists into cc's.

One is written per rendering update per local root: the top document of a renderer, or an out-of-process iframe in its own renderer. Same-process iframes have no local root of their own and are layerized inside their parent's event. Across five fixtures the count matched BeginMainThreadFrame exactly, every time. Blink writes it, so unlike Commit the browser process never does.

Most of them do almost nothing. PaintArtifactCompositor records what kind of update it owes, and the event covers the cheap answers as well as the expensive one. If nothing was painted, the function returns at once and the slice is a couple of microseconds. If something was repainted but no chunk changed its identity, its bounds or its count, and no paint property value changed, the repaint fast path runs: it pushes the new drawing commands into the layers that already exist and re-issues raster invalidation, without deciding anything. Only the third case re-runs the layerizer. On a fixture of 800 one-pixel divs each carrying opacity: 0.99, so each got its own chunk, those three cost about 2, 218 and 362 microseconds respectively. A full re-layerization is forced by a chunk being added or removed, by a chunk's bounds changing, or by a paint property value changing. Changing one element's colour every frame stayed on the repaint path; changing its width did not.

Derivations

Whether a Layerize actually re-layerized. Only the full path calls PaintArtifactCompositor::Update, which writes an event of that name on the blink category. A Layerize with that child made compositing decisions; one without it took a fast path. blink is not a category DevTools records, so this needs a trace configuration of your own. In a Performance recording the duration is the only tell, and it is a good one: the fast paths and the full path differ by two orders of magnitude on the same page.

Which document paid. args.data.frame is the local root of the renderer that did the work. The same token appears on FrameCommittedInBrowser and CommitLoad next to a url, so layerization time on a page full of third-party iframes can be attributed to the frame that caused it rather than to a process id.

How many compositor layers a page actually has, and what each one is. Record disabled-by-default-devtools.timeline.layers and cc writes LayerTreeHostImpl:snapshot, whose args.snapshot.active_tree.layers is the real layer list with a layer_name on each entry naming the element. That is the only way to check a guess about promotion against what Blink decided, and it is worth the trip: a fixture of 800 elements carrying opacity: 0.99 turns out to produce four layers, and the same 800 carrying will-change: transform produce 804. The catch is in the traps below: that category also makes this event slower, so read the counts from such a recording and the durations from an ordinary one.

Traps

It has arguments. Four of them, on every event: frame, isMainFrame, isOutermostMainFrame and page. Nothing in the payload builder is conditional. trace_engine declares none of them and has no type for the event at all, only the name, which is probably where the belief that it carries nothing comes from.

page is a copy of frame. Blink fills it with the local frame root of the frame it was given, and the frame it was given is always the local frame root, so the two are the same string on every event, in an ordinary page as much as in an iframe. Chromium's own comment next to that line says page does not work with out-of-process iframes and that callers should use frame instead.

The name says layers, but the cost is chunks. It is not the number of composited layers that drives a full run; it is the number of paint chunks the layerizer has to walk and try to merge, and an element gets its own chunk as soon as it has its own transform, clip or effect node, whether or not that node composites anything. On a fixture of 800 elements with opacity: 0.99, which between them add no compositor layer at all, a full run cost about 350 microseconds a frame. That page ends up with four compositor layers, the same four an empty page has. Promoting the same 800 with will-change: transform, which does produce 804 layers, took it to about 500. Promotion adds to a bill the chunk already ran up. A non-composited transform cost more than either, because it also deepens the property trees.

Off-screen content is free. Blink does not paint far outside the cull rect, so content there produces no chunks and no layers. Spread 200, 400 and then 800 promoted boxes down a 28,800-pixel document and the page ends up with the same 140 compositor layers every time, and the same cost; pack them into one screen and the count and the cost both triple. Counting will-change declarations in a stylesheet tells you nothing about what a frame will pay.

It is the driver of an animation that decides, not the promotion. A transform animation written in CSS or through element.animate() re-layerizes once and then never, however many frames it runs for. The same movement written as a per-frame style.transform from JavaScript forces a full re-layerization on nearly every frame, while painting almost nothing, and will-change: transform on the element does not change that at all: promoted, unpromoted, or already carrying a transform, the three behave identically. Blink has a direct transform update that skips layerization, and its own comment says it can only be used when an animation is present, because that is the case in which overlap testing can be assumed away. Both look like "an animated transform" in a screen recording; one of them costs a full layerization a frame.

Recording it changes it. Ticking Enable advanced paint instrumentation in the Performance panel adds disabled-by-default-devtools.timeline.layers, and that category is one of the three that turn on Blink's paint debug info. The debug info is built inside this slice: a name for every composited layer, plus a list of compositing reasons for each on a full run. On an 800-layer page that added about half again to every full-path Layerize. Having the Layers panel open does the same thing, for the same reason, without any recording setting. A default Performance recording does not do this, and nothing else about the event inflates itself either: its four arguments are four dictionary writes, with no traversal behind them. While you are in there, treat the compositing reasons that debug info carries with care: Chromium's comment above the function that produces them says they are informative for tracing and partly heuristic, not the decision Blink actually made.

Averaging the durations is meaningless. The distribution is not one population but three, and the cheap ones outnumber the expensive ones on any page that is not changing much. Sum the long ones, or count them; a mean sits in a gap where no frame lives.

The bar has nothing under it. Every child this event has with a duration is on blink or on cc, and a Performance recording asks for neither. Layerize itself is on plain devtools.timeline, so the panel always has the slice and never has its contents. The one child on a category DevTools does record, Layer:created, is an instant, and there are far fewer of them than there are layers: a page that built 804 compositor layers wrote two.

DevTools files it under Rendering. Paint, immediately before it, and Commit, immediately after it, are both Painting. In the panel's summary the three steps of one handover land in two different buckets.

Lighthouse does not know the name. Its task groups list CompositeLayers, Paint, PrePaint, UpdateLayer and UpdateLayerTree, and neither Layerize nor Commit. An unlisted event inherits its parent task's group, and the parent here is an ungrouped task, so layerization time is reported as Other.

No Layerize does not mean a cheap frame. A main frame on a hidden or render-throttled page never reaches the paint phase, so it writes no Layerize and no Paint either, and neither does a frame taken while anything is printing or producing a paint preview. The slice also opens some way into the function that writes it, after the returns for a frame with no page and for a renderer with accelerated compositing switched off, so a call can happen and leave nothing behind. In the other direction, Chromium can run the lifecycle and then skip the commit, which would leave a Layerize with no Commit after it; that is from the source, and it did not happen in any trace captured for this entry. One more path writes a Layerize outside any main frame, when a local root becomes render-throttled; also unobserved.

The same span is measured twice more in a trace. Blink.CompositingCommit.UpdateTime, on the blink category, wraps the same code and is this event's parent rather than its child. So does composite_commit_us inside args.send_begin_mainframe_to_commit_breakdown on a PipelineReporter's SendBeginMainFrameToCommit stage, which is on a category DevTools does record. The UMA timer opens a few lines earlier and its value is rounded and accumulated per main frame, so it tracks the slice closely without equalling it: of the pairs checked in two captures, none matched exactly and most were within two microseconds. The sibling update_layers_us in that same breakdown is cc's own layer update inside Commit, which is a different step.

{
  "name": "Layerize",
  "cat": "devtools.timeline",
  "ph": "X",
  "ts": 1102923357,
  "dur": 208,
  "tdur": 104,
  "tts": 28532,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "data": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "isMainFrame": true,
      "isOutermostMainFrame": true,
      "page": "14A831DCB73EB1205B67CDB89FC6EBD7"
    }
  }
}

See also Paint · PrePaint · Commit · CompositeLayers · BeginMainThreadFrame · UpdateLayerTree · UpdateLayer · RasterTask · DrawFrame · PipelineReporter

categories

devtools.timeline

usage

moderate

duration

typical

undeclared args

args.data.frame, args.data.isMainFrame, args.data.isOutermostMainFrame, args.data.page

references

inspector_trace_events.cc, document.cc, local_dom_window.cc, local_frame_view.cc

Chrome works out the size and position of the parts of one document that are out of date.

Spec

Blink's LocalFrameView::UpdateLayout lays out one document, either from the whole layout tree or from the subtree roots registered since the last pass, on the renderer's main thread.

Arguments

Observed 25,372 times on 182 of 300 sites.

Behaviour

One event is one call to LocalFrameView::UpdateLayout, and Blink only makes that call when something is actually dirty. So the event means layout ran: there is no empty Layout the way there is an empty forced-update slice. It covers one document. A same-process iframe is laid out by its own call, and the two calls never overlap: the scheduled update lays out this document and then walks into its children, and a read inside an iframe brings the embedding document up to date before the iframe's own layout starts. Either way you get two events side by side rather than one inside the other, and beginData.frame is what tells them apart. One rendering update can still produce several, because the update repeats style and layout while ResizeObserver callbacks and the first observation of a content-visibility: auto subtree keep dirtying things.

Most of the time the pass starts at the layout tree root, Blink's tree of boxes and text runs that mirrors the rendered part of the DOM. It can instead start lower. When an element's layout is invalidated, Blink walks up marking its ancestors, and if it meets a relayout boundary on the way it stops there and registers that box as a subtree root instead. A box qualifies if laying it out cannot change anything around it: contain: layout size is the explicit route, and the implicit one is a fixed width and height, overflow clipped on both axes, and a paint layer of its own, on a box that is not a flex or grid item. The near misses are easy to write by accident. contain: layout on its own does not qualify, nor does a fixed size with hidden overflow on a box that has no layer of its own, and an absolutely positioned box is excluded while it still depends on its static position, so one with top set and left left alone does not qualify either. partialLayout says whether any subtree root was registered, and endData.layoutRoots names them, deepest first.

The frame's own layout and a layout your code forced look identical on the event itself. What separates them is what they sit inside, and beginData.stackTrace. The stack is only written when JavaScript was on the V8 stack at the moment the pass opened, and then its top frame is the line that forced the pass. That is usually a geometry read, but focus(), scrollIntoView(), the selection APIs and innerText all put their own line there instead. Blink forces layouts of its own, at the end of parsing, after the load event, for hit testing and for selection bookkeeping, and those carry no stack at all, so an event without one is not necessarily the frame's own work.

beginData is written before Blink lays anything out, so its counts describe the work about to be done. endData is written afterwards, but its roots were snapshotted before the pass as well, and when there were none the layout tree root is substituted for them. A full layout therefore always reports one root, the document.

Some of the events in a trace belong to documents you did not write. Every SVG image has its own page and document, and it runs its lifecycle from inside the host document's paint, so one of its layouts sits under Paint, on the host's own thread. Such a document has a full set of loading events of its own, with an empty document URL and no CommitLoad and no request, which is the surest way to recognise it. Tracing is browser-wide, so Chrome's own WebUI pages and extension pages produce them too.

Derivations

Which line forced a layout. When the stack category is recorded, the top frame of beginData.stackTrace is the JavaScript that asked, and sampleTraceId gets you the rest: DevTools resolves that id against the CPU profile to rebuild the whole JS stack above the event. This is the only place that line appears, and it is the difference between knowing that a task forced eleven layouts and knowing which function did it.

Whether your containment is working. Scoping is a property of the box, not of the change: partialLayout flips to true only once the invalidated element has an ancestor Blink is willing to treat as a relayout boundary. Adding contain: layout size to a widget that updates constantly, then checking whether its layouts now report partialLayout: true with that element in layoutRoots, is a direct before-and-after measurement of the containment, and layoutRoots[].nodeId is a backend node id that DevTools links straight to the element.

Traps

The duration is not the cost of laying out. Producing dirtyObjects and totalObjects means walking the layout tree in pre-order, and that walk only happens while devtools.timeline is being recorded, inside the slice it is describing. On one machine it cost roughly four nanoseconds per layout object. That is invisible on a small page and not on a large one: on a page of 24,000 divs, two hundred forced layouts of a single box took about 2ms with nothing recording at all and about 44ms with devtools.timeline on, and the median Layout event read 205us for a layout that costs about ten. That the walk is the whole difference can be shown on the same page: put those 24,000 divs inside a content-visibility: hidden container, which the walk skips and layout does not care about, and the measurement falls back to about 4ms with dur at 9us. Untraced, the same incremental layout did not grow with the tree at all between 500 and 24,000 divs. Blink.Layout.UpdateTime wraps the same call and is the number to read instead, but only in a recording that leaves devtools.timeline out, because the walk happens inside that timer too.

endData goes missing, and it depends on your category list. The end of the Layout slice and the end of the enclosing LocalFrameView::layout slice are written in the wrong order in Blink, so when blink or benchmark is recorded the endData argument lands on LocalFrameView::layout and Layout ends with nothing. Record neither and it stays where it belongs. A third slice, LocalFrameView::performLayout, sits inside Layout and closes itself, so it takes nothing away; it is written on rail, which DevTools does record by default, while blink and benchmark are not. That is why a Performance panel trace has both that slice and its endData, and why the Show all events setting, which asks for every category, takes endData away, and with it the Layout root link in the details pane, because that link is built from endData.layoutRoots. devtools-frontend's own type for this event carries the comment "endData is not reliably populated. Why? TBD."

The ratio reads backwards. dirtyObjects close to totalObjects is not the whole-document relayout it looks like. On a partial layout both numbers describe only the subtree, so a well-scoped layout is the case that reads near one: two objects dirty out of three was one 300x200 box being laid out on its own. A small fraction is the ordinary full pass: four dirty objects out of four hundred is one element being changed on a page where nothing else moved. The reading the ratio does support is a document whose layout tree really is all dirty, which is what the first layout of every document and every iframe is. What separates that from a scoped layout is partialLayout, not the ratio.

totalObjects is not the size of your DOM. It counts layout objects, and an element with a text node inside it is two of them, so it runs to about twice the element count. It is also only the part of the tree the walk could reach: children of a display-locked subtree are skipped, so a content-visibility: hidden container holding 500 divs took a document of 1006 objects down to 6, and an off-screen content-visibility: auto container did the same. Elements with display: none have no layout object to count at all. And when partialLayout is true, totalObjects is the size of the subtree, not of the document.

dirtyObjects counts ancestors too. An object is dirty if it needs layout itself or if any descendant does, which is how Blink propagates the flag, so changing the width of one div near the root of a large page reported four: the layout tree root, html, body and the div. It is a count of marked objects, not of elements you changed.

partialLayout and layoutRoots are promises made before the work. Both are read before Blink lays anything out. PerformLayout can still throw the subtree roots away and lay out the whole view if the layout tree root turned out to be dirty too, and nothing in the trace records that it did. On a full layout, layoutRoots is always a single entry for the document, with the viewport as its quad, so it is an attribution path back to real elements only when partialLayout is true.

The stack is shallower than you think, and how deep depends on the recorder. Blink asks V8 for a non-full stack, which is one frame unless a client with the Runtime agent enabled is attached to the renderer. The same page, the same three-deep call chain, gave [inner] under Chrome's own --trace-startup and inner < middle < outer < (anonymous) through puppeteer. A DevTools panel recording has such a client, so it gets the deep version. The line and column numbers are 1-based, unlike the ones in a CPU profile's call frames, and DevTools subtracts one before showing them.

Filter on the frame before you add anything up. A trace holds layouts from documents that have nothing to do with the page you are looking at: an SVG image's own document, laid out inside Paint, plus Chrome's WebUI and any extension's pages, each in its own process. Summing dur across a trace without checking pid and beginData.frame counts all of them.

DevTools' two warnings about this event have gates you will not guess. The forced reflow warning counts only Layout and UpdateLayoutTree nested inside a JavaScript event, and reports nothing unless one task's total of those crosses thirty milliseconds. The DOM size insight wants a single Layout of at least forty milliseconds whose dirtyObjects is over a hundred, on the main frame's own main thread. Both are thresholds on dirty objects and on durations that, per the first trap, include the recording's own tree walk.

{
  "name": "Layout",
  "cat": "devtools.timeline",
  "ph": "X",
  "ts": 1103040878,
  "dur": 138,
  "tdur": 135,
  "tts": 131619,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "beginData": {
      "dirtyObjects": 6,
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "partialLayout": false,
      "sampleTraceId": 6909218608593003,
      "stackTrace": [
        {
          "columnNumber": 39,
          "functionName": "",
          "lineNumber": 85,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        }
      ],
      "totalObjects": 10
    }
  }
}

See also InvalidateLayout · LayoutInvalidationTracking · UpdateLayoutTree · Document::UpdateStyleAndLayout · Blink.ForcedStyleAndLayout.UpdateTime · LocalFrameView::UpdateStyleAndLayout · PrePaint

categories

devtools.timeline

usage

moderate

duration

typical

undeclared args

args.beginData.stackTrace[].columnNumber, args.beginData.stackTrace[].functionName, args.beginData.stackTrace[].lineNumber, args.beginData.stackTrace[].scriptId, args.beginData.stackTrace[].url

references

local_frame_view.cc, layout_subtree_root_list.cc, source_location.cc, v8-stack-trace-impl.cc, v8-debugger.cc

Blink code has asked for the next rendering update to run for this frame.

A DevTools Performance recording does not contain this event. Record cc with your own trace configuration to get it.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

LocalFrameView::ScheduleAnimation records one request from Blink C++ code for a main-thread frame on behalf of one document's frame, written on that renderer's main thread just before the request is passed to the ChromeClient and on to the compositor's LayerTreeHost.

Arguments

Observed 125,001 times on 182 of 300 sites.

Behaviour

Blink has more than one way to ask the compositor for a new main-thread frame, and this event records one of them. Code that holds a LocalFrameView (Blink's object for one frame's rendering state) and calls its ScheduleAnimation method writes the event, then hands the request to the ChromeClient, which finds the widget for the frame's local root and asks cc, the compositor, to schedule a main frame.

Most of what you will see goes through one function, ScriptedAnimationController::ScheduleAnimationIfNeeded: requestAnimationFrame, queued scroll, scrollend and resize events, media query listeners, video frame callbacks, and the re-arm Chrome performs after running a frame's rAF callbacks if more are queued. Animations add their own. Starting a CSS animation, a CSS transition or a Web Animation writes one from PendingAnimations::Add, and an animation that runs on the main thread, such as a transition on width, writes one from AnimationTimeline::ScheduleServiceOnNextFrame for every frame it runs. A composited animation, once started, writes none. IntersectionObserver.observe() and ResizeObserver.observe() write one each, and page load writes a few from lifecycle code such as BeginLifecycleUpdates and, in an iframe, WasShown.

There is one event per call, and nothing merges requests before the event is written. Merging happens afterwards, inside cc: a request that arrives while one is already pending is folded into it, unless it is marked urgent or needs to lift frame throttling. Call requestAnimationFrame ten times in one task and you get ten of these, one ProxyMain::SetNeedsAnimate (the cc instant that marks a request actually being posted) and one BeginMainThreadFrame. A single rAF loop writes two per frame, one from the requestAnimationFrame call inside your callback and one from the re-arm after it, with identical arguments.

The event is written before the request goes anywhere, so it appears even when the request is then ignored, for example for a frame that does not have a widget yet. Each renderer writes its own: with site isolation a cross-site iframe writes it in its own process, while a same-site iframe writes it in the page's renderer with is_main_frame false.

Traps

Style and layout changes request their frame without this event. Writing el.style.width, toggling a class, changing display or content-visibility or appending DOM nodes asks for a frame through PageAnimator::ScheduleVisualUpdate, which goes straight to the ChromeClient. So do main-thread scroll animations, the visual viewport and autoscroll. In a capture each of these produced a posted frame request and a BeginMainThreadFrame, and none of these events. The exception is a style change that starts a transition or animation: the animation code then writes it, as Add and ScheduleServiceOnNextFrame. Counting these events does not count the frames a page asked for.

location is Blink's C++ caller, not your code. It is filled by a default argument evaluated where ScheduleAnimation is called, so it names the Blink function one level up, with no class name and a line number that moves between Chrome builds. A few Blink wrappers are themselves called ScheduleAnimation, and then that is what you see. To find the script that called requestAnimationFrame, use the RequestAnimationFrame event and its stack trace.

ScheduleAnimationIfNeeded does not mean page script asked. Every rAF, queued scroll or resize event and media query listener shows that same line in scripted_animation_controller.cc. Scroll events are queued whether or not anything listens for them, so on a page with no scroll listener at all, a smooth scroll still wrote one per frame.

A count of these is a count of calls, not frames. Ten in a row may be one frame; a steady rAF loop gives two per frame; and, from the first trap, frames also run with none. Events written while a frame runs its rAF callbacks ask for the next frame, not the current one. Nothing here says whether a frame followed, or whether it drew anything.

delay is always 0. No Blink code passes a delay to this function.

The reason is not recorded. The function receives a BeginMainFrameReason (rAF, animation, CSS animation, and so on) and an urgent flag, and writes neither.

frame is the frame that asked, not the one that draws. A same-site iframe's request goes to its parent's compositor and can be merged with the parent's. frame.document.url is an empty string for events written before the frame's first navigation commits, and about:blank for a fresh iframe.

Record cc, and expect DevTools to hide it. cc is not in the categories the Performance panel records unless its "Show all events" setting is on, and even in a trace that contains the event, DevTools draws it only with that setting on, because it has no style for the name. A trace of the whole browser can also contain these events from Chrome's own interface pages: in new headless Chrome 153 a process named WebUI Top Renderer wrote them for chrome://omnibox-popup.top-chrome/. Filter on process or frame.document.url.

{
  "name": "LocalFrameView::ScheduleAnimation",
  "cat": "cc",
  "ph": "X",
  "ts": 1102925982,
  "dur": 9,
  "tdur": 8,
  "tts": 30078,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "delay": 0,
    "frame": {
      "document": {
        "url": "http://127.0.0.1:8801/"
      },
      "is_cross_origin_to_outermost_main_frame": false,
      "is_cross_origin_to_parent": false,
      "is_main_frame": true,
      "is_outermost_main_frame": true
    },
    "location": {
      "file_name": "third_party/blink/renderer/core/dom/scripted_animation_controller.cc",
      "function_name": "ScheduleAnimationIfNeeded",
      "line_number": 248
    }
  }
}

See also RequestAnimationFrame · FireAnimationFrame · ScheduleStyleRecalculation · BeginMainThreadFrame

categories

cc

usage

high

duration

short

references

scripted_animation_controller.cc, frame.h, location.cc, document.cc, local_frame_view.cc, traced_value_support.h and 2 more

Chrome brings one frame's style and layout up to date.

A DevTools Performance recording does not contain this event. Record blink with your own trace configuration to get it.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

Blink's LocalFrameView::UpdateStyleAndLayout recalculates style and runs layout for a single frame's document, doing only what is dirty, on the renderer's main thread.

Behaviour

Every frame on the page, the main document and each iframe, has its own view in Blink, the object that owns that frame's layout, and this is the view's update function. It has two main callers, and they put it in two different places in the trace.

The rendering update Chrome runs before painting calls it under LocalFrameView::RunStyleAndLayoutLifecyclePhases, once for every frame that process is rendering, parent first and then each child in turn, and again for all of them if choosing the root scroller dirtied layout. When something needs geometry sooner, such as script reading offsetHeight, the request goes through Document::UpdateStyleAndLayout, which calls this function inside its own slice, normally with a Blink.ForcedStyleAndLayout.UpdateTime slice in between. The Forced slice is left out when the request starts inside another one in the same frame, so the dependable sign of the forced path is the enclosing Document::UpdateStyleAndLayout. In no capture did one of these contain another, not even for iframes: in the rendering update each child frame's call follows its parent's, and on the forced path an iframe's document brings its parent up to date first, so the parent's call is an earlier sibling of the child's.

The function only does what is out of date. It recalculates style, which writes UpdateLayoutTree, then runs layout, which writes Layout, and each runs only if something is dirty. It then updates CSS counters, runs an extra sizing loop for the rare frame whose size follows its content, and makes one more pass if layout is still dirty. When anything was laid out, post-layout tasks such as geometry updates run before the slice closes. When nothing was dirty, the slice closes a microsecond or two after it opened, with nothing inside. That is by far the most common outcome, because the forced path calls it on every request whether or not anything changed: a hundred offsetHeight reads with no writes in between produced a hundred of these, all empty. Across the crawled corpus most of them come from the forced path, for the selection reason explained under Document::UpdateStyleAndLayout, so a trace full of these is mostly a trace full of clean reads.

The function begins with a guard that refuses the update for a frame whose rendering is throttled, a document that is not active, a frame that has not committed yet, a view already in the middle of layout, or a document whose lifecycle is postponed. The guard sits inside the traced scope, so a refused call is also a slice. Both main callers check most of those conditions before calling, which leaves the guard little to catch. A throttled iframe, such as one that is offscreen and cross-origin, is skipped before the call and so produces fewer of these, not more: in one headless capture, an offscreen cross-site iframe running a requestAnimationFrame animation for two and a half seconds wrote three, and the same iframe on screen wrote over a hundred and fifty.

Derivations

Which layouts did work. A slice that contains Layout or UpdateLayoutTree did real style or layout for that frame; an empty one did nothing. The working slice's duration covers that work plus the post-layout tasks that follow it, and one slice can hold more than one style and layout pass. Combined with the enclosing slice, this sorts every layout on the main thread, and the style recalculations that ran as part of one, into forced work (inside Document::UpdateStyleAndLayout) and rendering-update work (inside LocalFrameView::RunStyleAndLayoutLifecyclePhases), per frame through the beginData.frame on the nested events. Style recalculations that needed no layout, such as getComputedStyle() for a colour, run outside this event and are not covered.

Traps

A short slice is not a refused update. The guard returns inside the traced scope, but so does a call that simply found nothing dirty, and the trace cannot tell the two apart. Both are a slice of a microsecond or so with no children. Count children, not durations.

The fastest ones are not slices. Chrome's trace clock ticks in whole microseconds, so a call that opens and closes within the same tick has a duration of exactly zero. JSON traces recorded over the DevTools protocol, which is how Puppeteer and most tools record, are written by Perfetto's JSON exporter, and it writes a zero-length slice as an instant event: "ph": "I" with "s": "t" and no dur. They are the same event, just the cheapest instances of it. A parser that only reads "X" records undercounts the empty calls, and one that expects dur on every record will choke on them. The odd "ph": "B" record with no matching end is a slice that was still open when the recording stopped, usually a forced update caught mid-flight, with Document::UpdateStyleAndLayout and Blink.ForcedStyleAndLayout.UpdateTime open around it.

Summing durations double counts. Each forced one sits inside a Document::UpdateStyleAndLayout, usually with a Blink.ForcedStyleAndLayout.UpdateTime in between, and its own duration includes the UpdateLayoutTree and Layout inside it. Add up one level only. When blink is recorded, the direct children of a working slice are the timer slices Blink.Style.UpdateTime and Blink.Layout.UpdateTime, with UpdateLayoutTree and Layout one level below them, so look for descendants rather than children.

There are no arguments, so an empty slice does not say which frame it was for. The Layout and UpdateLayoutTree inside a working one carry beginData.frame; for the rest you have the process and thread.

Not all of them are the page. A trace that records every renderer process picks up Chrome's own interface pages as well. Under headless Chrome, a process named WebUI Top Renderer contributed a handful per capture, some directly under LocalFrameView::HandleLoadCompleted, the caller that runs this once more at load completion for a frame whose size follows its content. Filter by process before counting.

The event is on blink, which a DevTools Performance recording does not capture unless the timeline-show-all-events setting is on, and DevTools has no model entry for it, so it appears under its raw C++ name in the System category. DevTools' Layout block is drawn from the Layout event nested inside, not from this one.

{
  "name": "LocalFrameView::UpdateStyleAndLayout",
  "cat": "blink",
  "ph": "X",
  "ts": 1102923242,
  "dur": 4,
  "tdur": 4,
  "tts": 28430,
  "pid": 8257,
  "tid": 8257,
  "args": {
  }
}

See also Document::UpdateStyleAndLayout · Blink.ForcedStyleAndLayout.UpdateTime · Layout · UpdateLayoutTree · InvalidateLayout

categories

blink

usage

very high

duration

very short

references

local_frame_view.cc

Chrome records the drawing commands for the parts of a page that need to be drawn again.

Spec

Blink's paint phase walks the PaintLayer tree of one local frame tree and records drawing commands into a display list for any content that needs repainting, on the renderer's main thread; nested Paint events mark individual PaintLayers that were repainted.

Arguments

Observed 70,939 times on 182 of 300 sites.

Behaviour

Paint records drawing commands; it does not produce pixels. What Blink writes is a display list, which cc later rasterizes in RasterTask, so a long Paint is time spent walking the page and recording, never time spent filling pixels.

The event comes in two shapes, one inside the other. A PaintLayer is Blink's own unit of paint. The document has one, and so does every element that is positioned or forms a stacking context, which includes anything with a transform, an opacity below 1 or a filter, and always includes the root html element. A PaintLayer is not a compositor layer, and most never become one.

Paint   #document          the root: the whole paint walk for this frame tree
  Paint HTML               a layer that needed repainting
  Paint DIV id='menu'      another one

The outer event is written for the top PaintLayer every time the paint phase runs, and it covers the whole walk, including the cheap work of copying the recorded output of layers that did not change. Blink's comment says it is there "to cover the cost of tree walk and cache copying of non-repainted contents". Same-process iframes are painted inside their parent's walk; an out-of-process iframe gets a root event of its own in its own renderer.

Inside it, a nested Paint is written for a PaintLayer that itself needed repainting, but only when the enclosing layer being reported did not also need it. If a whole stacking context changed, you get one event for it, not one for each layer inside. Layers that paint beyond what is on screen, a scroller or an element with a composited transform, are reported whenever they repaint. Nesting follows paint order, not the DOM: a positioned child of a positioned parent that does not form a stacking context is painted by the stacking context above both, and its event sits beside its parent's rather than inside it.

A changed element with no PaintLayer of its own is reported as the layer it paints into, and on most pages that is the root element's, named HTML: a colour change on an ordinary div shows up as #document with HTML inside it. On a page's first paint every layer needs painting, the root itself included, so the nested events are suppressed and there is a single #document.

The paint phase only runs when something needs repainting. A rendering update where nothing does writes no Paint at all, even though style, layout, PrePaint and Layerize all ran. A JavaScript style.transform animation on a promoted element produced a full rendering update every frame and not one Paint across 29 frames; the same loop changing a background colour produced two Paints a frame. A CSS transform animation produced no main-thread frames at all.

This is the third event to carry this name. Before CompositeAfterPaint, Chromium's rearrangement that paints first and decides compositor layers afterwards, there was a timed Paint for each composited layer, carrying that layer's id, beside one for the frame. From Chrome 97, when CompositeAfterPaint became the default, to Chrome 132 there were two kinds: a timed Paint per frame with a layerId of 0, and an instant Paint for each compositor layer that had damage, whose clip was the damaged rect in screen space and whose layerId was real. (Chrome 96 already had the code, behind a flag that was off by default.) Chrome 133 removed both and replaced them with the events described here. Articles and tools written before 2025 describe the older events.

Derivations

Which layers were actually repainted. The nested events inside a root Paint name the PaintLayers that needed repainting in that rendering update, by nodeName. That is the nearest a default Performance recording gets to "what repainted", and it is enough to tell a repaint confined to one component from one that dragged in the whole root layer. Its granularity is the PaintLayer: an element without one is reported as whatever layer it paints into.

Whether an animation is paint-free. Line the rendering updates up against the Paint events. A BeginMainThreadFrame whose PrePaint is not followed by a Paint on the same thread was a frame in which nothing needed repainting. An animation that is supposed to be paint-free and still produces a Paint every frame is not.

Traps

layerId is always 0. Blink writes a literal zero, with the comment "For backward compatibility". It has not been a compositor layer id since Chrome 133, and nothing in the event links it to one.

clip is not what was repainted. It is the layer's cull rect, the area Blink is willing to paint for that layer: the visible area, expanded along each axis the content can scroll by up to 4000 pixels (2000 on Android, and multiplied by the device pixel ratio), never past the scrollable content. Content that scrolls both ways gets half the expansion on each axis. A page that does not scroll gets no expansion at all, so its clip is exactly the viewport, and a small scroller gets its box plus 1024 pixels of scroll. On a page of 20-pixel boxes, each box's event carried a clip of 1000 by 924 pixels, the same size as the root's. It is in the layer's own local coordinates, so a nested event's rect usually starts at negative numbers, and the root's moves with the scroll position: scrolled to 8000 in an 800-pixel viewport, the root's clip ran from 4000 to 12800. DevTools' own type definition calls the field unreliable and slated for removal. The damage-rect meaning comes from the instant events of Chrome 96 to 132.

nodeId names the layer, not the element you changed. DevTools labels it "Layer root" for exactly that reason. Expect #document and HTML most of the time. nodeName is only present from Chrome 137. The id is a DOM node id allocated per renderer process, so an out-of-process iframe's #document can carry the same number as an element in the page.

frame is the frame that owns the reported layer, which is not always where the change happened. Blink carries an iframe's need to repaint up to the iframe element's own PaintLayer, and when that layer does not paint itself, which is the case for an unpositioned iframe, the layer above it is marked as needing repaint instead: usually the parent's HTML. That suppresses every nested event inside the iframe, so a repaint in a same-process iframe shows up as the parent frame's HTML, with the parent's frame id. Give the iframe position: relative and the nested event carries the iframe's own frame id and names the layer inside it.

Adding up Paint durations counts the same time twice. The nested events run inside the root one. Sum the root events, or use self time.

DevTools does almost nothing with this event beyond drawing it. LayerTreeHandler skips every Paint whose layerId is 0, which is all of them, so for a trace from Chrome 133 or later the frame model never attaches a paint to a frame and the picture preview never appears. Older traces, with real layer ids, still get both. InvalidationsHandler does not attach invalidations to Paint either: it uses a Paint only as the point after which a frame's pending invalidations are thrown away, and it credits them to UpdateLayoutTree and Layout. Nothing in DevTools answers "why did this repaint" from this event. DevTools' type definition also still says nodeId is absent under CompositeAfterPaint; it is on every event.

stackTrace never appears. Script is forbidden while Blink paints, so there is no JavaScript on the stack to capture. sampleTraceId does appear when disabled-by-default-devtools.timeline.stack is recorded, which a DevTools recording does, and then every Paint, however tiny, also takes a V8 CPU profiler sample.

Advanced paint instrumentation repaints everything once. Recording disabled-by-default-devtools.timeline.layers (the Performance panel's advanced paint instrumentation setting records it), or having the Layers panel open, switches on Blink's paint debug info, and the first paint after it is switched on forces a full repaint of every frame. The first Paint in such a recording is not representative.

The root Paint is most of the paint phase, not all of it. The cull rect update runs before it, and committing the display list and Layerize run after it closes.

{
  "name": "Paint",
  "cat": "devtools.timeline",
  "ph": "X",
  "ts": 1102944950,
  "dur": 444,
  "tdur": 287,
  "tts": 41633,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "data": {
      "clip": [0, 0, 1280, 0, 1280, 1100, 0, 1100],
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "layerId": 0,
      "nodeId": 3,
      "nodeName": "#document",
      "sampleTraceId": 6909218608594407
    }
  }
}

See also PrePaint · Layerize · Commit · RasterTask · PaintImage · PaintSetup · BeginMainThreadFrame · UpdateLayoutTree · Layout

categories

devtools.timeline

usage

moderate

duration

short

undeclared args

args.data.sampleTraceId

references

paint_layer_painter.cc, node.cc

Blink records one image being drawn into a page's paint.

Spec

Blink writes PaintImage on the renderer's main thread while it records the drawing of one image into a frame's display list: an <img> or other image box, a CSS background, or a border-image, with the painted rectangle and the source rectangle it draws from.

Arguments

Observed 56,965 times on 147 of 300 sites.

Behaviour

Painting in Blink is recording, not drawing pixels. It builds a display list, a list of drawing operations per element, and the compositor turns that into pixels later, on other threads. PaintImage marks the recording of one image operation, and there are three places that write it: ImagePainter for an <img> (and anything else laid out as an image box, such as a CSS content: url() image), the background painter for background-image, and the border painter for border-image.

Blink keeps each element's recorded drawing and reuses it until something invalidates it, and a reused drawing writes nothing. So the event follows re-recordings, not images. An image can be recorded more than once during load, as layout settles around it or as a progressive file arrives in pieces. After load, scrolling the window or an overflow container wrote nothing for images already painted, a style change on a neighbouring element wrote nothing, and adding an outline to an image wrote one more event for that image alone.

Blink records more than what is on screen: it paints everything inside its cull rect, an area that extends well beyond the viewport. An eager image 6000px down the page was recorded on the first scroll, before it came into view, and in one configuration during load; one at 30000px was not recorded at all. A PaintImage for an element does not mean the user saw it.

There is a fourth writer that paints nothing. During PrePaint, the step before paint, Blink works out whether each box's background will be completely hidden by what sits on top of it, so it can skip painting that background. When the answer depends on an image, either an <img> with a background of its own or an <img> that fills a box with a background, Blink asks whether the image is opaque, and that question writes a PaintImage named after the <img>. These events sit inside PrePaint, not Paint, and carry nodeId, nodeName and url only, with no rectangle and no frame. The check runs again whenever that background changes, so it can write an event for an image whose own drawing is reused and gets no regular PaintImage at all.

For a bitmap, the duration is the recording and nothing more. Decoding happens later, at raster, on a worker thread, with software and GPU rasterization alike: a 4000x4000 JPEG whose decode took around 30 ms on a worker had PaintImage events of a few microseconds. An SVG image is different. It is a whole document with its own lifecycle, which Blink runs from inside the host page's paint. When the SVG is drawn at a size it has not been drawn at before, its own Layout and PrePaint sit inside its PaintImage; a repaint at the same size carries only the PrePaint.

Derivations

Oversized <img> files. srcWidth times srcHeight is the number of pixels the file decodes to, and width times height is the area it was painted over, so their ratio is how much of the file the display could use. DevTools' Image delivery insight does exactly this: per image URL it takes the paint with the largest area, divides width and height by the device pixel ratio of the machine that recorded (see traps), and compares. Do it per URL, not per event, skip the events that have no rectangle, and use only bitmap <img> elements; the traps below say why the rest mislead.

Which element an image request became. url plus nodeId joins a network request to the element that painted it, and nodeId is a backend node id DevTools resolves to the DOM node. Join on the URL the request started with, because url is the pre-redirect one. A requested image with no PaintImage at all was downloaded and never painted while you were recording, which is what a preload for the wrong candidate, or an image hidden on this viewport, looks like.

Traps

width, height, x and y are device pixels of the machine that recorded, not CSS pixels. A 400x300 CSS <img> reported width: 400 at device scale factor 1 and width: 800 with the display at 2x, with software and GPU rasterization alike. DevTools' device emulation does not change them: emulating a 2x phone on a 1x desktop still reported 400. DevTools corrects for this using the host DPR it stores in the trace metadata, and warns that without it the results may be very misleading. A trace from chrome://tracing or puppeteer has no such metadata, so divide by the recording machine's DPR yourself.

srcWidth and srcHeight are not naturalWidth and naturalHeight. For an <img> they are the pixels of the part of the file being drawn; for a CSS image they are always the whole image.

• A srcset candidate chosen by its w descriptor has a naturalWidth corrected for density; srcWidth is not. srcset="big.jpg 1600w" sizes="400px" gave naturalWidth 400 and srcWidth 1600.
• Under object-fit: cover the source is cropped to the box but the painted rectangle is not. A 1600x1200 file in a 300x300 box reported srcWidth 1200 and width 400 at x -42, so the ratio says 3 where the file is more than 5 times the box width. With overflow: visible on the image nothing is cropped and srcWidth is the full 1600.
• They are in the file's stored orientation. A JPEG with an EXIF rotation displayed 300x400 reported srcWidth 1600 and srcHeight 1200: compare width to height and the ratio is wrong on both axes.
• An SVG is drawn at whatever size it is painted, so its source size equals its painted size and the ratio is always 1. The same holds for a CSS gradient.

CSS backgrounds cannot be judged by the ratio. For a repeating background, width and height are the whole painted area while srcWidth is the image that makes up one tile, and for a sprite, srcWidth is the whole sheet while width is the little box showing one icon: a 50px box on a 1600px sheet reads as 32 times oversized. DevTools skips CSS images for this reason. isCSS is true for every background and border-image, and also for an image made by the CSS content property; it is false for an <img>.

Counting events is not counting images. One image writes an event every time its drawing is re-recorded, so group by url and nodeId.

Events without a rectangle break size arithmetic, DevTools' included. The background check described above writes events with a url but no width, height, srcWidth, srcHeight or frame; filter them out first. DevTools does not. Its Image delivery insight picks the largest paint per URL with a comparison that a missing size wins when it comes last, and then has nothing to measure: of three identical oversized JPEGs, the one whose wrapper changed background colour after load dropped out of the insight, while the other two were flagged.

loadingAttribute and srcsetAttribute are the <img> element's own attributes as written, an empty string when absent, and they exist only when the element is an <img>. loadingAttribute: "" means no attribute, not eager loading by decision. In a <picture>, the candidates live on <source> elements and are not reported: srcsetAttribute is empty even though a candidate was chosen, and isPicture (whether the <img>'s parent is a <picture>) is the only sign. url is the candidate that was actually picked.

url is the URL the image was requested with, before any redirect: an <img> whose URL answered with a 302 reported its own URL, not the one it was sent to. It is missing whenever there is no fetched resource, which is every CSS gradient. A URL longer than 1024 characters, typically a data: URI, is cut to its first 511 and last 510 characters around ..., so it will not match anything exactly.

x and y are in the local coordinate space of whatever the element paints into. For ordinary content that is the document, but an image under transform reported 0, 0, and one inside a scrolling container was positioned relative to the container's contents. Do not treat them as page or viewport coordinates.

The event is on disabled-by-default-devtools.timeline, which a DevTools Performance recording includes and most other tracing setups do not.

{
  "name": "PaintImage",
  "cat": "disabled-by-default-devtools.timeline",
  "ph": "X",
  "ts": 1108423745,
  "dur": 121,
  "tdur": 120,
  "tts": 91874,
  "pid": 8407,
  "tid": 8407,
  "args": {
    "data": {
      "frame": "2EA8810E92C12C680C55B2941251AA98",
      "height": 346.5,
      "isCSS": false,
      "isPicture": false,
      "loadingAttribute": "eager",
      "nodeId": 274,
      "nodeName": "IMG class='Image-styles__ImageStyled-sc-8c99a12b-0 cVsHni'",
      "srcHeight": 360,
      "srcWidth": 640,
      "srcsetAttribute": "https://ichef.bbci.co.uk/news/240/cpsprodpb/09f1/live/aaa670e0-af38-11f1-a540-61c3f7fc4e6c.jpg.webp 240w,https://ichef.bbci.co.uk/news/320/cpsprodpb/09f1/live/a... [578 more chars]",
      "url": "https://ichef.bbci.co.uk/news/640/cpsprodpb/09f1/live/aaa670e0-af38-11f1-a540-61c3f7fc4e6c.jpg.webp",
      "width": 616,
      "x": 332,
      "y": 529
    }
  }
}

See also Paint · Decode Image · Decode LazyPixelRef · Draw LazyPixelRef · ImageDecodeTask · PrePaint · LayoutImageUnsized · largestContentfulPaint::Candidate

categories

disabled-by-default-devtools.timeline

usage

moderate

duration

typical

references

inspector_trace_events.cc, image_painter.cc

Chrome set up a layer for painting, before painting into it.

Chrome no longer emits this event. The code that wrote it was found in the history and then found to have been deleted.

Spec

Chromium's compositor, cc, timed its BitmapContentLayerUpdater allocating a new backing bitmap and canvas for a layer whose area to repaint had changed size, on cc's main thread, immediately before painting into it; the code shipped from Chrome 29 to Chrome 44.

Behaviour

Before impl-side painting, cc painted a layer's contents straight into a bitmap and uploaded that bitmap as a texture. The layer type that worked this way was ContentLayer, and its painter was BitmapContentLayerUpdater. On each update, cc worked out the rectangle to repaint (the union of the layer's dirty tiles) and handed it to the updater, which compared its size with the previous one. If the size differed, it allocated a new bitmap and a canvas over it, and that allocation is all this event covered. So it fired on a layer's first paint and whenever the invalidated area changed size, not only when the layer itself was resized; a repaint of an area the same size as last time reused the bitmap and wrote nothing.

It was a begin and end pair on cc's main thread, which for a page is the renderer main thread, carrying one argument, layerId, the cc layer being painted. The category was cc,devtools up to Chrome 36 and disabled-by-default-devtools.timeline from Chrome 37. From Chrome 33 the span closed before the paint began, so the paint sits next to it. In Chrome 29 to 32, cc also wrapped the whole update in a PaintLayer span, so there PaintSetup and the paint are both nested inside that.

Chrome no longer writes it. Impl-side painting, where a layer's drawing commands are recorded first and rasterised into tiles later, uses a different layer type and never reaches this code. With default flags it was already on for Android when the event was added, became the default on Linux and Chrome OS by Chrome 38, and on Windows and Mac in Chrome 39. After that a page's renderer only reached this code if Chrome was started with --disable-impl-side-painting. Chrome's own interface on Windows, Linux and Chrome OS kept painting this way by default through Chrome 44. In June 2015 commit d23f2953ca removed ContentLayer and commit 4dac85e885 removed BitmapContentLayerUpdater, both before Chrome 45, so Chrome 44 is the last release that contains the code.

The event was added in May 2013 together with a Blink change that did not write a trace event of its own. DevTools' old record-based Timeline listened for cc's PaintSetup, and Blink turned it into a Timeline record with the DOM node that owned the layer attached, placed just before the Paint record. Blink deleted that record-based Timeline in February 2015; the trace-based Timeline that replaced it read cc's event directly. Either way it was cc's measurement of the same allocation.

The name survives in three places: an unused kPaintSetup constant in cc/base/devtools_instrumentation.h, the DevTools Performance panel, which still labels it "Paint setup" and colours it as painting, and Lighthouse, which still counts it under Rendering. You will only meet the event itself in a trace recorded by Chrome 44 or earlier.

Traps

Nothing replaced it. PrePaint is Blink's lifecycle step before paint in a current trace, but it does different work and is not this event under a new name. A trace from after Chrome 44 that has no PaintSetup has not lost anything you could look for elsewhere.

It measured allocation, not drawing. A long one means cc allocated a large bitmap because the area to repaint changed size; it says nothing about how expensive the layer's contents were to paint. That cost is in the paint that follows (or, in Chrome 29 to 32, in the enclosing PaintLayer, which contains both).

layerId is a cc layer id, not a DOM node id, and trace_engine declares no arguments for this event. DevTools still assigns it a "Layer root" label in its code, but it resolves no node for PaintSetup, so that row never appears.

In a trace from Chrome 39 to 44 with default flags, a page's renderer did not write it. A PaintSetup there came from the browser process drawing Chrome's own interface, or from a renderer started with --disable-impl-side-painting. Check which process wrote it before blaming the page. On Android, a page never wrote it with default flags.

See also Paint · PrePaint · UpdateLayer · RasterTask · CompositeLayers

references

devtools_instrumentation.h, bitmap_content_layer_updater.cc

Blink gets the page ready to be painted: it works out the transforms, clips and effects each part is drawn with, and which parts need drawing again.

Spec

Blink runs the compositing-inputs and pre-paint lifecycle phases for one local frame root, walking the layout tree with PrePaintTreeWalk to update the paint property trees and invalidate what must be repainted, on the renderer's main thread between layout and paint.

Arguments

Observed 48,090 times on 182 of 300 sites.

Behaviour

Before Blink can record drawing commands it needs to know, for every element, which transform, clip, effect and scroll offset it is drawn under, and whether what it drew last time is still valid. Chromium keeps the first answer in paint property trees, one node per element that introduces a transform, clip, effect or scroll container, and works both answers out in a single walk of the layout tree called PrePaintTreeWalk. The same walk updates the data the compositor uses to hit-test touch and wheel input (touch-action, blocking wheel listeners) and skips subtrees with nothing dirty. The slice also covers a smaller phase Chromium calls compositing inputs, which updates some per-layer flags and commits the pending text selection. The two are separate phases in the code, and the slice covers both on purpose: Chromium's comment above it says the difference "is not relevant to web developers, so include them both under PrePaint."

In a rendering update it runs in the same main-thread task as the rest of the pipeline:

BeginMainThreadFrame
  UpdateLayoutTree, Layout
  PrePaint          compositing inputs, then the pre-paint walk
  Paint, Layerize
Commit

Each rendering update writes at least one per local root: the top document of a renderer, or an out-of-process iframe in its own renderer. It can write more. After PrePaint, Blink delivers ResizeObserver callbacks and a few other post-layout steps (the first IntersectionObserver check for content-visibility: auto, container-query changes, view transitions); if any of them dirties style or layout, the whole sequence runs again inside the same update. A ResizeObserver that resized an element produced Layout, PrePaint, Layout, PrePaint, Paint in one update.

The walk starts at the local root and crosses into every same-process iframe, so a same-origin iframe never gets a PrePaint of its own; its work is inside its parent's. A cross-site iframe that site isolation puts in its own process writes its own stream.

It is written whether or not anything changed. A page with nothing scheduled writes none, because no rendering update runs. A page with an empty requestAnimationFrame loop writes one on every frame, each a few microseconds long, while Paint never appears.

A rendering update is not the only way in. Every hit test brings the lifecycle up to this phase first, and writes a PrePaint whether or not anything was dirty, with no paint after it. document.elementFromPoint called three times in a row wrote three. Chrome's own hit test for mouse movement does the same, so under a moving mouse a frame holds two: one under the mousemove handling, then the frame's own. A forced layout stops short of it: getBoundingClientRect after a style change ran style and layout and returned, because Blink stops before this phase when layout is all the caller asked for. Printing and prerendering's dry run also stop after it.

No PrePaint is written for a frame Blink is currently render-throttling, unless an IntersectionObserver needs a fresh answer from it, for a document that is not active, or while DevTools has the lifecycle postponed.

The event carried a different name until Chrome 102. crrev.com/c/3519012 renamed UpdateLayerTree to PrePaint, in the same place in the code, and added three of the four arguments; UpdateLayerTree had only frame. Current Chrome does not write UpdateLayerTree at all.

Derivations

Which renderer did the work. args.data.frame is the frame id of the local root whose lifecycle ran. The same id appears on FrameCommittedInBrowser and in the frames list on TracingStartedInBrowser, next to a URL, so pre-paint time on a page with cross-site iframes can be split by document rather than by process id. isMainFrame alone separates the top-level stream from the out-of-process iframe streams, without needing that map.

Which lifecycle update a layout shift belongs to. Blink normally writes LayoutShift from inside this slice, at the end of each frame's pre-paint walk, when LayoutShiftTracker adds up the region that moved and scores it. The PrePaint that contains a LayoutShift is the update in which the shift was detected, and whatever dirtied layout before it is the candidate cause. DevTools uses it that way: LayoutShiftsHandler only collects and sorts PrePaint events, and the CLS culprits insight maps each shift to the PrePaint containing it, then credits a web font or a non-composited animation that finished within half a second before that PrePaint, an iframe created before it, or an image with no dimensions painted in the next PaintImage after it.

Traps

It has arguments. Four, on every event, none conditional: frame, isMainFrame, isOutermostMainFrame and page. trace_engine declares none of them.

page is a copy of frame. Blink fills it with the local frame root of the frame it was given, and the frame it was given is always the local root, so the two are the same string on every event. In the top renderer that happens to be the page; in an out-of-process iframe it is the iframe. Chromium's comment on that line says page does not work with out-of-process iframes and callers should use frame.

frame is not the frame whose content changed. It names the local root. Work for every same-process iframe is inside the parent's slice, under the parent's id. The LayoutShift events inside it carry their own frame, which can be a same-origin iframe: in one capture, a shift in a same-origin iframe sat inside the main document's PrePaint with the iframe's id on it.

isMainFrame and isOutermostMainFrame are not about the main thread. isMainFrame is true when the frame has no parent and false when an out-of-process iframe's renderer did the work. isOutermostMainFrame additionally turns false for the root of a fenced frame, which is the only case in which the two disagree.

Counting PrePaints does not count frames. It is written on every rendering update that gets past layout, including those with nothing dirty, more than once when a ResizeObserver or a similar step sends the lifecycle round again, and once per hit test, including every mouse move. A test harness that polls with requestAnimationFrame (puppeteer's waitForFunction does by default) keeps a page producing them. Sum the long ones instead.

Not every PrePaint belongs to a frame. A hit test, including your own elementFromPoint, runs it on demand inside the task that asked, dirty or not, and it is on that task's critical path. In DevTools it sits directly before a Hit test slice under the calling script or input event.

Not every LayoutShift is inside one, and not every one inside is from a frame. A shift that happens while a pointer or mouse button is held down is held back and written when the pointer is released, from input handling, outside any PrePaint; these carry had_recent_input and DevTools ignores them. A shift can also be detected by a hit test's PrePaint, which puts the LayoutShift in the middle of a script task.

The bar has nothing under it. The two phase slices inside it, LocalFrameView::RunCompositingInputsLifecyclePhase and LocalFrameView::RunPrePaintLifecyclePhase, are on blink,benchmark, which a Performance recording does not ask for. The only child DevTools shows is LayoutShift, an instant.

Old traces say UpdateLayerTree, and it was not always the same slice. A parser that spans Chrome versions needs both names; Lighthouse's task groups list both for that reason. From Chrome 97 to 101 UpdateLayerTree wraps the same work as today's PrePaint. Up to Chrome 96, where CompositeAfterPaint was still off by default, the same slice also ran the old compositing update, compositing inputs and compositing assignments, which modern Chrome does in Layerize after paint, so those durations are not comparable with a modern PrePaint. DevTools' CLS culprits insight matches only the name PrePaint, so on a trace older than Chrome 102 it has nothing to anchor root causes to.

DevTools pairs shifts with PrePaint by time alone. The culprits insight checks whether a shift's timestamp falls inside a PrePaint, and picks "the next PrePaint" after a font or animation, with no check of process, frame or kind. On a page with cross-site iframes, where two renderers run their lifecycles concurrently, a shift can in principle be attributed through the wrong renderer's PrePaint, and a hit-test or iframe PrePaint that happens to come first can leave a real culprit uncredited. That is from the source; it was not reproduced.

{
  "name": "PrePaint",
  "cat": "devtools.timeline",
  "ph": "X",
  "ts": 1102923261,
  "dur": 32,
  "tdur": 27,
  "tts": 28446,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "data": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "isMainFrame": true,
      "isOutermostMainFrame": true,
      "page": "14A831DCB73EB1205B67CDB89FC6EBD7"
    }
  }
}

See also UpdateLayerTree · Layout · Paint · Layerize · LayoutShift · HitTest · BeginMainThreadFrame · PaintImage

categories

devtools.timeline

usage

moderate

duration

typical

undeclared args

args.data.frame, args.data.isMainFrame, args.data.isOutermostMainFrame, args.data.page

references

inspector_trace_events.cc, document.cc, local_dom_window.cc, local_frame_view.cc

Chrome's compositor rasterizes one tile of a layer: it plays back the drawing commands recorded for that tile.

Spec

The compositor's TileManager writes RasterTask around the playback of one tile's recorded display list into that tile's raster buffer, on a raster worker thread: drawing the pixels there under software raster, or serializing the drawing commands for the GPU process under GPU raster.

Arguments

Observed 140,457 times on 182 of 300 sites.

Behaviour

Paint only records drawing commands. The compositor, cc, cuts each compositor layer into tiles, rectangles it can rasterize and cache independently, and schedules one raster task per tile that needs pixels: tiles that are new, that scrolled into the area cc keeps ready, or whose content was invalidated. RasterTask wraps exactly one thing inside that task, the playback of the tile's recording through a raster buffer. Its parent, RasterizerTaskImpl::RunOnWorkerThread, is the whole task.

What that playback does depends on how Chrome is rasterizing, and it changes the event completely.

Software raster. Used when there is no usable GPU: headless Chrome with default flags, --disable-gpu, --disable-gpu-rasterization, or a blocklisted GPU. The renderer draws the pixels itself, and you see DisplayItemList::Raster nested inside. Several tasks run in parallel on different workers; four or five ran side by side in these captures. Tiles come from a fixed default size, 256 by 256 pixels here.

GPU raster. The normal case on a desktop or phone with a working GPU, and out of process: the renderer does not draw. The task serializes the tile's drawing commands into the command buffer for the GPU process (RasterImplementation::RasterCHROMIUM nested inside), and the GPU process turns them into pixels later in RasterDecoderImpl::DoRasterCHROMIUM, on its own main thread, CrGpuMain. cc runs these tasks strictly one at a time. Tiles are sized from the viewport instead: as wide as it, and a quarter of its height rounded up, never less than 256 pixels tall (1216 by 256 on a 1200 by 900 viewport). The same page produced about a quarter as many tasks. On one fixture page the renderer's RasterTasks added up to 5 ms under GPU raster and 276 ms under software raster on the same machine, and the GPU process spent 7 ms on the pixels: more than all the RasterTasks together.

In the renderer the tasks run on Chrome's shared thread pool, on threads named ThreadPoolForegroundWorker. The browser process writes RasterTask as well, on a thread named CompositorTileWorker1, while it rasterizes Chrome's own interface.

The event is written as a begin and an end. Chrome's JSON export turns a finished pair into one X event with a duration, and writes a lone B for a task that was still running when recording stopped; stopping a trace in the middle of heavy raster produced one B per busy worker.

Derivations

Which compositor layer costs raster time, under software raster. Sum dur per layerId within the renderer process. With disabled-by-default-devtools.timeline.layers recorded, the trace also carries LayerTreeHostImpl:snapshot events whose active_tree.layers give each layer_id a layer_name, its compositing_reasons and an owner_node, the backend DOM node id of the element that owns the layer. Expect most of the time to land on one layer: everything that is not separately composited paints into the root scrolling layer, whose owner is the document.

Traps

Under GPU raster, RasterTask does not contain the rasterization. It covers packing the drawing commands into the command buffer; the pixels are made in the GPU process in RasterDecoderImpl::DoRasterCHROMIUM, on the gpu category, which neither a DevTools recording nor puppeteer's defaults include. Short RasterTasks on a real device do not mean the drawing was cheap.

Numbers from headless Chrome are software raster numbers. Headless Chrome with default flags reported "Software only" for rasterization, and --enable-gpu-rasterization --ignore-gpu-blocklist did not change that. A headless crawl measures raster the way a machine without a GPU would: more tasks, smaller tiles, running in parallel, and far more renderer time than the same page on a device with a GPU.

It is not on a thread called "Raster". The renderer's tasks run on ThreadPoolForegroundWorker threads, and the DevTools Performance panel shows them under "Thread pool", not "Raster". CompositorTileWorker1, which DevTools labels as a rasterizer thread, belongs to the browser process drawing Chrome's own interface, so filter by process before adding anything up.

tileResolution is not a low-resolution flag. Its values are HIGH_RESOLUTION and NON_IDEAL_RESOLUTION, and there is no low-resolution value. A tiling is non-ideal when its scale is no longer the one the layer wants, after a zoom or a scale change. cc takes raster work from the high-resolution tiling, with one transitional exception: tiles of an active-tree tiling that has gone non-ideal while its pending-tree twin is high resolution. So NON_IDEAL_RESOLUTION can appear, but pinch-zoom, page-scale and scale-transform captures all produced only HIGH_RESOLUTION.

tileId.id_ref is a memory address, not an id. It is the address of the tile object, and a new tile reuses the address of a freed one: 129 tasks in one capture shared 40 ids, with different sourceFrameNumber values on the same id. Pair it with sourceFrameNumber before counting re-rasters of "the same tile".

sourceFrameNumber is when the tile was created, not when it was rastered. It is the compositor commit number in effect when cc created the tile object, counted from 0 per compositor, so it repeats across processes. A tile that survives later commits keeps its number while the recording it plays back is the layer's current one, so the number can be older than the content drawn, and it says nothing about which displayed frame the pixels reached.

layerId does not lead to an element in DevTools. It is a compositor layer id, not a DOM node id, and LayerTreeHandler never reads RasterTask. What DevTools does instead is show a paint preview for a selected RasterTask by looking up tileId and sourceFrameNumber in a layer tree snapshot, which exists only with advanced paint instrumentation, and it matches that snapshot by the name cc::LayerTreeHostImpl, while Chrome 153 writes it as LayerTreeHostImpl:snapshot. Expect no preview from a current recording. The manual route through owner_node is in the derivations, and needs the page still open to turn that node id into an element.

A B event has no duration. It is a task that had not finished when recording stopped. Drop it, or treat its time as unknown, rather than reading it as zero.

The event is on both cc and disabled-by-default-devtools.timeline, and either one records it: a DevTools Performance recording, puppeteer's default categories, and a trace of cc alone all have it.

{
  "name": "RasterTask",
  "cat": "cc,disabled-by-default-devtools.timeline",
  "ph": "X",
  "ts": 1102928322,
  "dur": 35,
  "tdur": 33,
  "tts": 1420,
  "pid": 8178,
  "tid": 8209,
  "args": {
    "tileData": {
      "layerId": 37,
      "sourceFrameNumber": 1,
      "tileId": {
        "id_ref": "0x13f4017a89a0"
      },
      "tileResolution": "HIGH_RESOLUTION"
    }
  }
}

See also RasterizerTaskImpl::RunOnWorkerThread · ZeroCopyRasterBuffer::Playback · DisplayItemList::Raster · GPUTask · ImageDecodeTask · Paint · cc::LayerTreeHostImpl · ActivateLayerTree · DrawFrame

categories

cc, disabled-by-default-devtools.timeline

usage

high

duration

typical

references

frame_viewer_instrumentation.cc, tile_manager.cc, picture_layer_impl.cc, devtools_instrumentation.h, picture_layer.cc, layer_tree_host.h and 3 more

The compositor thread sends the main thread the task in which it will do its part of a frame.

Spec

Chromium's compositor, cc, posts a BeginMainFrame task from a renderer's compositor thread to its main thread, the task in which Blink will run requestAnimationFrame callbacks, style, layout and paint, and writes this instant on the compositor thread immediately after posting it.

Arguments

Observed 27,083 times on 182 of 300 sites.

Behaviour

Something has to ask for a main frame first, and usually it is the page. A requestAnimationFrame call, a DOM or style change or a main-thread animation tells cc that the main thread needs a frame. The compositor thread can ask too: when it scrolls the page itself it requests a main frame to hand the new scroll offset to the main thread, and it does the same when a composited animation has start or finish events to deliver. The need is a single flag, not a queue: twenty requestAnimationFrame calls and twenty style writes in one task produced one RequestMainThreadFrame. An idle page writes none, and neither does a running composited transform animation, which the compositor ticks and draws without the main thread.

The compositor thread's scheduler then decides when to act on it, and everything it holds back happens before this event. It sends a main frame only inside an impl frame, cc's name for the compositor's own work on one display refresh, at most one per refresh, and never while the previous main frame is still running on the main thread. It also holds off while the page is hidden, while main frame updates are deferred during loading, and while it is throttling. What that means in practice depends on what the page was doing:

• After idle, viz hands the compositor the most recent refresh the moment it starts listening again, so the event followed a requestAnimationFrame call by about half a millisecond in one capture.
• In a steady requestAnimationFrame loop it waits for the next refresh, a whole interval after the call.
• In a loop whose callbacks outlast a refresh, it goes out a few hundredths of a millisecond after the previous main frame's Commit starts, wherever that falls in the refresh.

When it does send, cc posts the task and writes this event. It is an instant on the renderer's Compositor thread. A compositor without its own thread has no call site: the browser draws its own UI that way, so every one of these belongs to a renderer, and a renderer run without a compositor thread, as in web tests, writes BeginMainThreadFrame with no RequestMainThreadFrame before it.

Because the scheduler will not send another main frame until the main thread has finished with the last one, this event and BeginMainThreadFrame strictly alternate for each layer tree: one request, then the start of that main frame on the main thread, then the next request. There are two ways to get a request with no start after it. The task can run and abort before BeginMainThreadFrame, because the page became hidden or rendering was deferred between the send and the run; one capture had this on the initial about:blank layer tree at the moment the page navigated away from it. Or the trace can end while the task is still waiting behind a long task.

Derivations

How long a main frame waited, split in two. When a requestAnimationFrame call was the trigger, the first RequestAnimationFrame (on devtools.timeline) after the previous main frame to this event is how long the compositor held the request: up to a refresh in a steady loop, which is the normal wait for vsync, or the whole previous main frame when frames run long. This event to the next BeginMainThreadFrame on the same process and layer tree is how long the task sat in the main thread's queue. A frame that started late for the first reason needs shorter frames; one that started late for the second needs shorter tasks, or fewer of them queued at once. Both events are in a Performance panel recording. A request that came from a style change or from the compositor writes no RequestAnimationFrame, so only the second half is measurable.

Traps

The gap to BeginMainThreadFrame is not only the main thread being busy. It is the time the task spent in Blink's compositor task queue, and Blink's scheduler decides the order. A task already running is never interrupted: a rAF followed by a 300 ms busy loop gave a 299.6 ms gap. But the queue is also ordered by priority. The compositor queue normally has the same priority as timers, so work queued earlier runs first: five 10 ms timers queued during a steady rAF loop all ran before the main frame, which started 50 ms after the previous one ended. Once a task finishes 100 ms or more after the last main frame task ended, the scheduler raises the queue above timers and most other work, though still below input and render-blocking loading tasks, until the next main frame runs. With twenty 20 ms timers queued instead of five, the main frame started 100.1 ms after the previous one and jumped the remaining timers, and each of the next few main frames waited again, 100 to 120 ms apart, until the timers ran out. After an idle stretch the page already counts as starved, so the same twenty timers waited behind the main frame instead of in front of it. A run of gaps close to 100 ms is that rule at work, not a coincidence in your task lengths. From source, the queue is also raised to top priority after a click or key press until the next frame, and lowered below timers while the compositor thread is handling a scroll gesture, unless rendering is already starved; neither was captured for this entry.

The compositor's own delays are not in the gap. Waiting for the next refresh, waiting for the previous main frame, throttling and paint holding all happen before this event is written. Neither is it a vsync marker: after idle it is written almost immediately, and in a heavy loop it lands mid-refresh.

Pair on process and layerTreeId, not thread. This event is on the Compositor thread and BeginMainThreadFrame is on the main thread. layerTreeId is the id of the compositor's layer tree host, a counter local to each process that starts at 1, so an out-of-process iframe's renderer uses the same small numbers as the page's: in one capture the page's tree was 2 and the iframe's, in its own process, 1. It also changes across a navigation: an initial about:blank tree was 1 and the loaded page 2 in one trace. SetLayerTreeId carries the layer tree id and the frame id together. Take the next BeginMainThreadFrame on the same pair only if no second request comes first, which skips the aborted ones.

DevTools uses it as a switch, not a timestamp. The event is hidden in the flame chart unless "Show all events" is on in the Performance panel's settings. The frame model never reads its ts. It sets a flag that stops DrawFrame from closing frames until the main frame's Commit arrives, and it matches on layerTreeId alone, so a request from another process with the same number sets the flag for the page's frames too. On one capture, removing every RequestMainThreadFrame changed DevTools' frame count from 837 to 840.

Category. It is written only on disabled-by-default-devtools.timeline.frame, which DevTools records but a hand-written trace configuration has to ask for. SendBeginMainFrame, on cc,benchmark, is written a few microseconds earlier at the same moment and carries the begin-frame sequence number. A default Performance recording does not include it; with "Show all events" on, DevTools records every category that is not disabled by default, and it is there.

Your harness can create these. Puppeteer's page.waitForFunction() polls with requestAnimationFrame by default, so a page that is waiting idle requests a main frame every refresh for as long as the test waits.

{
  "name": "RequestMainThreadFrame",
  "cat": "disabled-by-default-devtools.timeline.frame",
  "ph": "I",
  "ts": 1102922942,
  "tts": 1523,
  "pid": 8257,
  "tid": 8278,
  "s": "t",
  "args": {
    "layerTreeId": 1
  }
}

See also BeginMainThreadFrame · RequestAnimationFrame · BeginFrame · Commit · DrawFrame · DroppedFrame · MainFrameAborted · SetLayerTreeId · SendBeginMainFrame

categories

disabled-by-default-devtools.timeline.frame

usage

moderate

references

devtools_instrumentation.h, proxy_impl.cc

Chrome notes that a page's styles have gone out of date and schedules a recalculation.

Spec

Blink's Document::ScheduleLayoutTreeUpdate moves a document from clean to waiting for a style and layout tree update, the moment the first out-of-date style is recorded, on the renderer's main thread.

Arguments

Observed 44,757 times on 182 of 300 sites.

Behaviour

Blink records a style change in two steps. First it marks the element involved and walks up its ancestors setting a bit on each: that happens for inline style writes, class or attribute changes that match a selector, and inserted nodes. At the end of that walk, unless the parent was already marked, it calls Document::ScheduleLayoutTreeUpdateIfNeeded, and that function returns straight away if the document already has an update pending. Only the call that finds no update pending gets through to ScheduleLayoutTreeUpdate, which moves the document's lifecycle to kVisualUpdatePending, Blink's state for "an update has been asked for and has not started", and writes this event.

So the event marks a transition, once per document, and not one invalidation. In one capture, twenty writes to one element's style in a single task produced one event, and toggling a class on five elements produced one. Everything after the first is silent until the recalculation runs. The recalculation is UpdateLayoutTree, and running it takes the document out of the pending state, so the next change writes a new event. That is why a loop that writes a style and then reads offsetHeight leaves one of these per iteration, each followed microseconds later by an UpdateLayoutTree inside the same task. Without the read, the recalculation waits for the next rendering update.

The per-element record, with a reason string and the element's name, is a different event on a different category: StyleRecalcInvalidationTracking, on disabled-by-default-devtools.timeline.invalidationTracking. Those twenty writes produced twenty of them.

Script is only one source. The HTML parser inserting nodes, a stylesheet finishing its download, a web font arriving, a change of viewport size and each main-thread tick of a CSS animation all make style out of date the same way. The trigger is also wider than style: anything that needs the layout tree rebuilt goes through the same call, including SVG <use> shadow trees, elements leaving the top layer and CSS counters. Changes inside a content-visibility: hidden subtree are the exception in the other direction: Blink postpones marking a hidden subtree until it is shown, and in a test capture neither an inline style write nor a class toggle inside one wrote an event.

Blink suppresses the event while style is already being recalculated and while layout is running, and writes none for an inactive document. It does not suppress it when no rendering update can follow: in a throttled frame, such as an off-screen cross-origin iframe, or before the document's render-blocking resources have loaded, the event is written but no frame is requested. In a capture with a slow stylesheet in the head, the parser wrote one event, the document then sat in the pending state until the sheet arrived 1.5 seconds later, and a script style write during that wait wrote nothing, because an update was already pending.

The payload is frame, the id of the document's frame, and nothing else unless disabled-by-default-devtools.timeline.stack is recorded. With that category on, every event gets a sampleTraceId, and it gets a stackTrace only if V8 was running JavaScript at that instant. That is the split you see in the arguments table: events started by script carry a stack, and events started by the parser, the network or the animation clock do not.

Derivations

Which line of JavaScript first made style dirty. stackTrace[0] is the call that took a clean document to pending, so in a trace full of forced recalculations each event names the write half of a write-then-read pair, and the UpdateLayoutTree right after it is the read. With disabled-by-default-v8.cpu_profiler recorded as well, sampleTraceId resolves against cpuProfile.trace_ids in ProfileChunk to a node in the profile's call tree, which is how DevTools rebuilds the full JavaScript stack above the event. In one capture every stackless event that resolved landed on (program): nothing was executing JavaScript, so Blink started that recalculation on its own. That is a positive answer where a missing stackTrace on its own is not.

Traps

reason, subtree and nodeId are never written. trace_engine declares all three on this event and Blink has no code that writes them: the payload builder takes only the frame, as it already did in 2015. They are the fields of StyleRecalcInvalidationTracking. If you want to know which element changed and why, record disabled-by-default-devtools.timeline.invalidationTracking and read those events instead.

The stack names the first change, not the expensive one. Only the invalidation that found no update pending writes an event, so a cheap style.width write followed by a class toggle on body in the same task is attributed entirely to the width write. The class toggle, which is the one that makes the recalculation large, leaves no trace here at all.

DevTools pairs by frame and by order, and never forgets. InitiatorsHandler keeps the last ScheduleStyleRecalculation for each frame id and links it to every UpdateLayoutTree that starts on that frame afterwards; it overwrites the entry when a new one arrives but never clears it after use, and there is no time limit. That link fills the recalculation's "Initiated by" row, its "First invalidated" stack and its "Pending for" time. It is right whenever a fresh event comes before the recalculation. It goes wrong when the event is written inside the recalculation, and a forced style update in script does that while CSS animations are running: an outdated animation is enough to make the forced update run, and the update services animations only after its UpdateLayoutTree has begun, so the animation's change writes a ScheduleStyleRecalculation a few microseconds into the slice. DevTools then links that recalculation to an older event, tens of milliseconds old in the real trace where this was seen, and credits the new one to the next recalculation. The test for a wrong link is structural: a ScheduleStyleRecalculation on the same frame falls inside the previous UpdateLayoutTree, or none falls between two of them. A long "Pending for" on its own proves nothing, because a recalculation held back by a render-blocking stylesheet is linked correctly and can show a wait of more than a second.

This event can also be what a Layout points at. When a layout invalidation happened inside a style recalculation that had an initiator, DevTools substitutes that initiator, so the arrow into a Layout can start here rather than at InvalidateLayout.

Record the right categories, or there is nothing to pair. This event is on disabled-by-default-devtools.timeline, and UpdateLayoutTree is on devtools.timeline, which is on by default. A trace made without the disabled category has every recalculation and none of these, and no recalculation in it has an initiator. sampleTraceId and stackTrace need disabled-by-default-devtools.timeline.stack as well, and with it on each event also takes a V8 CPU profiler sample it would not otherwise take.

Stack depth measures your recorder, not the page. V8 captures one frame unless a client has the Runtime domain enabled, and then up to 200. The same five-deep call chain came out as seven frames under Puppeteer and as one frame in a trace recorded from the command line with --trace-startup. The frames run top first, lineNumber and columnNumber count from one, and scriptId is a string.

An event does not promise a recalculation soon. In a throttled frame or before render-blocking resources have loaded, the event is written and no frame is requested, so the matching UpdateLayoutTree may be a long way off.

Filter on args.data.frame. Every document writes these, including iframes, about:blank pages and Chrome's own pages in other renderer processes, and DevTools' Frames track treats any of them on the main thread as a sign that a main-thread frame has begun.

{
  "name": "ScheduleStyleRecalculation",
  "cat": "disabled-by-default-devtools.timeline",
  "ph": "I",
  "ts": 1102950872,
  "tts": 45984,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "sampleTraceId": 6909218608594505,
      "stackTrace": [
        {
          "columnNumber": 81,
          "functionName": "note",
          "lineNumber": 24,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        },
        {
          "columnNumber": 5,
          "functionName": "",
          "lineNumber": 47,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        }
      ]
    }
  }
}

See also UpdateLayoutTree · StyleRecalcInvalidationTracking · ScheduleStyleInvalidationTracking · InvalidateLayout · Layout · Document::UpdateStyleAndLayout

categories

disabled-by-default-devtools.timeline

usage

moderate

undeclared args

args.data.sampleTraceId, args.data.stackTrace[].columnNumber, args.data.stackTrace[].functionName, args.data.stackTrace[].lineNumber, args.data.stackTrace[].scriptId, args.data.stackTrace[].url

references

source_location.cc, v8-stack-trace-impl.cc, v8-debugger.cc, document.cc

Blink records that the scroll position of the page, or of a scrollable element, has changed.

Spec

PaintLayerScrollableArea::UpdateScrollOffset applies a new scroll offset to one of Blink's scrollers, the viewport or an overflow box, on the renderer's main thread, whatever produced the change.

Arguments

Observed 1,043 times on 101 of 300 sites.

Behaviour

Every scroller Blink knows about keeps its own copy of its scroll offset, and ScrollLayer is written each time that copy actually changes. An offset set to the value it already has writes nothing. The name is older than tracing itself: DevTools' original Timeline had a ScrollLayer record, and the trace event kept it. The layer is Blink's own layer, today called the paint layer, the structure a scroller belongs to, not a compositor layer.

Most scrolling in Chrome is not applied on the main thread. A wheel, trackpad, keyboard or smooth-scroll animation is applied by the compositor thread, which moves the page on screen without waiting for Blink. At the start of each main-thread frame, LayerTreeHost::ApplyCompositorChanges hands Blink the offsets the compositor has reached since the last one, and each scroller that moved writes a ScrollLayer. So an ordinary threaded scroll produces one per frame, as the first thing in that frame's task, followed by BeginMainThreadFrame and the scroll event. A 600-pixel gesture on an idle page wrote one in each of its 32 frames.

Script writes them too, and on a different schedule. scrollTo, scrollBy, setting scrollTop, scrollIntoView with the default instant behaviour, and focus() on an element outside the viewport write one synchronously, inside the JavaScript that called them. With behavior: 'smooth' the call only starts an animation, which is handed to the compositor and comes back one frame at a time, exactly like a user scroll. Navigating to a #fragment, scroll anchoring (Blink shifting the offset to keep content still when something is inserted above it) and clamping (pulling the offset back when the content shrinks below it) each write one inside the next frame's rendering update. A scroll the main thread performs itself on behalf of the user would write one as well; that path is in the source, but no capture here could make Chrome take it.

The visual viewport, the part of the page you see after a pinch zoom, is not one of these scrollers. Panning it around the zoomed page writes nothing. Once the pan reaches the edge of the layout viewport and starts moving the page itself, the page's scroller changes and ScrollLayer on #document appears as usual.

Derivations

Which code scrolled the page. An instant script scroll writes its ScrollLayer inside the JavaScript that caused it, nested under that code's FunctionCall, so the enclosing FunctionCall names the function and its script and nodeName names the scroller. That is the quickest way to find the code behind an unexpected jump, a scroll restoration fight, a focus() that drags the page or a carousel setting scrollLeft. A ScrollLayer at the head of a frame, with no script above it, is the compositor reporting back and says nothing about who started the scroll. Smooth scrolls from script do not nest either: the call only starts the animation.

Traps

It cannot tell you whether scrolling is threaded. A compositor scroll, a script scroll and a main-thread scroll all write the same event with the same fields. One per frame during a scroll is the normal signature of a healthy threaded scroll, not of a fallback to the main thread.

The kind of scroll is recorded next to it, not on it. Blink writes it three times around each ScrollLayer: a Type instant on the blink category, another on input, and a SetScrollOffset instant on disabled-by-default-blink.debug whose type reads kCompositor, kProgrammatic, kAnchoring and so on. A default Performance recording captures none of them. Turning on the Performance panel's CSS selector stats setting adds disabled-by-default-blink.debug, so the SetScrollOffset instant then lands in the saved trace. It is also written for script scrolls that turn out to change nothing, so pair it with a ScrollLayer by timestamp rather than counting them.

It does not say where the scroller went. There is no offset and no delta on the event. The new x and y are on PaintLayerScrollableArea::UpdateScrollOffset (blink) and ScrollableArea::scrollOffsetChanged (input), neither of which a Performance recording captures.

Its timestamp is when Blink heard about the scroll, not when the user saw it. With the main thread blocked for 800 milliseconds, a threaded gesture scrolled the page for half a second on the compositor while the main thread wrote nothing, and the whole scroll then arrived as two ScrollLayers the moment the block ended. A gap in ScrollLayer during a scroll can mean the scroll was working fine.

A non-passive wheel listener looks the same. Given the same 800-millisecond block and a wheel listener without passive: true, the compositor could not start scrolling until the main thread had run the listener, so the page genuinely froze. The ScrollLayers landed at almost the same moment as in the threaded case. What differs is on the compositor thread, where the scroll updates are handled, in the input category, which DevTools does not record. Such a listener delays the start of a compositor scroll; it does not move the scroll onto the main thread, and neither does a scroll listener, which runs after the offset has already changed.

The root scroller is #document. When the page itself scrolls, nodeName is #document and nodeId is the document, not <html> or <body>. For an overflow box nodeName is Node::DebugName(): the tag followed by the id and every class, as in DIV id='box' class='scroller main'. Use it as a label, not a selector.

nodeId is only good for the live page. It is a DOMNodeId, the same number CDP calls a backendNodeId, handed out on first use: the document was 2 in one capture and 1 in another. It will not line up across two loads of the same page.

frame is the scroller's own frame. A scroll inside an iframe carries the iframe's frame id, not the page's.

dur is bookkeeping, not the cost of scrolling. The slice covers what Blink does right after taking the new offset: marking paint and the compositor's copy dirty and queueing the scroll event. That is tens of microseconds. Your scroll handlers run later in the frame, outside it.

DevTools calls the node "Layer root". The Summary pane links nodeId under that label, shared with Paint. It is the element that scrolled.

{
  "name": "ScrollLayer",
  "cat": "devtools.timeline",
  "ph": "X",
  "ts": 1104989335,
  "dur": 190,
  "tdur": 85,
  "tts": 219835,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "data": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "nodeId": 3,
      "nodeName": "#document"
    }
  }
}

See also BeginMainThreadFrame · EventDispatch · Commit · Paint

categories

devtools.timeline

usage

low

duration

typical

undeclared args

args.data.nodeName

references

node.cc, paint_layer_scrollable_area.cc

Chrome has just worked out the computed style of one element.

A DevTools Performance recording contains this event only with Enable CSS selector stats (slow) or Invalidation tracking turned on, which records disabled-by-default-devtools.timeline.invalidationTracking.

DevTools has no entry for this event in its trace model, so the Performance panel shows its raw name with no label and no explanation.

Spec

Blink's StyleResolver::ResolveStyle marks each style it finishes computing for one element or pseudo-element, the unit that the enclosing UpdateLayoutTree counts as elementCount, with an instant on the renderer's main thread, written only while disabled-by-default-devtools.timeline.invalidationTracking is recorded.

Arguments

Observed 3,114,328 times on 182 of 300 sites.

Behaviour

StyleResolver::ResolveStyle is the function that turns CSS into a computed style for one element: it matches rules and runs the cascade, or reuses a cached result, then layers any running animation values on top. When it has finished, it adds one to a per-document counter and, if the invalidation-tracking category is being recorded, writes this instant on the very next line. UpdateLayoutTree, the style recalculation slice, reports how far that counter moved while it ran as elementCount. The two have been kept in step deliberately since Chrome 138, so give each instant to the innermost UpdateLayoutTree on the same thread and the number matches elementCount exactly. It matched in every recalculation of every trace captured for this entry, synthetic pages and real ones. The word innermost matters: a child frame's document can be parsed, loaded and styled while the parent document's recalculation is still running, so its UpdateLayoutTree sits nested inside the parent's, with a different beginData.frame, and its instants fall inside both.

What both numbers count is resolutions, not elements. One element can appear more than once in a single recalculation. Every page's root <html> is resolved three times in its first recalculation, once for itself and once each for the ::spelling-error and ::grammar-error rules in Chrome's own stylesheet; an element with a ::selection rule gets a second one the same way; an element inserted with an @starting-style rule is resolved twice, once for its starting style and once for its real one; and an element with a styled scrollbar is resolved again for each scrollbar part, sometimes more than once per part. Pseudo-elements that Blink creates as nodes, ::before, ::after, ::marker, ::first-letter and ::backdrop, get events of their own, so an element with a ::before and an ::after adds three.

Some style changes write nothing at all. A handful of inherited properties are independent, meaning nothing else in a style depends on them: color, visibility, cursor, pointer-events, text-transform, interactivity, -webkit-rtl-ordering and a few table and list properties. When a parent changes only those, Blink copies each child's old style and writes the new values in without calling ResolveStyle. It does not take that shortcut for a child that is animating or transitioning, uses custom properties, sits inside a link, has text decorations or needs recalculating for its own reasons; those are resolved normally. In one capture, setting color on a parent of twenty children wrote one event and an elementCount of one, while setting font-size on it wrote twenty-one. Text nodes are never resolved this way, a text field's inner editor builds its style by hand, and a pseudo-element request that matches no rules returns before the counter and the event.

Some resolutions happen outside any UpdateLayoutTree, and those are written without being counted anywhere. getComputedStyle on an element inside a display: none subtree, or on a pseudo-element that has no box, resolves it on the spot, inside your script's task. Size container queries and anchor-positioning fallbacks resolve the affected elements again during layout, so their events sit inside a Layout slice. Custom scrollbar parts turn up in both places: resolved in the recalculation, then again in the layout that follows.

Anything that marks an element for style recalculation leads to one of these on the next update: an inline style write, a class change, a selector newly matching. Writing the value an element already has changes nothing and writes nothing. A CSS animation or transition on a property the main thread has to animate re-resolves its element on every frame: a width animation and a width transition each did, with no script on the page, and a font-size animation on a parent took every child with it. A transform animation or an opacity transition running on the compositor does not ask the main thread for frames, and on an otherwise idle page its element was not re-resolved frame by frame. Give the page any other reason to produce frames, even an empty requestAnimationFrame loop, and the same transform animation re-resolves its element on every one of them.

Derivations

Which elements a style recalculation actually resolved. UpdateLayoutTree gives you a number; these give you the nodes behind it, one per unit of that number. nodeId is the same id the DevTools Protocol calls backendNodeId, so DOM.describeNode or DOM.pushNodesByBackendIdsToFrontend turns it into an element while the page is still open.

Where a restyle started. Within one UpdateLayoutTree, an event whose parentNodeId was not itself resolved in the same recalculation is the top of a restyled subtree. In a capture that changed font-size on one parent of fifty children every frame, all fifty-one elements came out with the same per-node count, and this test picked out the parent alone in every frame. This is what the argument was added for: accounting for every element a subtree invalidation touched. The test names the place, not the reason: a CSS animation on the element gives the same root as a script writing to it. And Blink sometimes restyles pseudo-elements without their element, after a change near the root, so ::before, ::after and ::marker nodes, and pseudo requests on an element that was not itself resolved, can come out as roots. Resolve the ids before you trust one.

Style work done during layout. An event inside a Layout slice rather than an UpdateLayoutTree is a container query, an anchor-positioning fallback or a custom scrollbar part being resolved mid-layout. No other event names those elements, and no elementCount includes them.

Traps

pseudoId: 0 does not mean an ordinary element. ::before, ::after, ::marker and ::backdrop are resolved as nodes in their own right and write pseudoId 0, with nodeId set to the pseudo-element and parentNodeId to the element it belongs to. So do elements in a browser-built shadow tree, such as an input's placeholder. A non-zero value appears when Blink resolves a pseudo style through the originating element instead, and then nodeId is that element: ::first-line, ::selection and the other highlight pseudos, and each part of a custom scrollbar. getComputedStyle(el, '::before') on an element whose ::before has no box does the same, and that is the one way a non-zero ::before, ::after or ::marker value turns up. ::first-letter is the odd one out, non-zero with its own node. Resolve the id before you decide what it is.

pseudoId numbers belong to one Chrome build. The value is a position in Blink's PseudoId enum, and new pseudo-elements are inserted into the middle of it: ::selection is 9 in Chrome 135 to 140, 10 in 141 to 147, 11 in 148 to 150 and 12 in 151 to 153. Read it against computed_style_constants.h for the build that wrote the trace.

A count per nodeId names the element, not the cause. A script writing a style in requestAnimationFrame and a CSS animation on a main-thread property leave exactly the same one-event-per-frame pattern, and a single inherited change on a parent gives every descendant the same count as the parent. The event has no stack and no reason. For the cause, read StyleRecalcInvalidationTracking from the same category: for the same element it says Animation on an animation tick, and Inline CSS style declaration was mutated, with a stack, on a script write. ScheduleStyleRecalculation carries the stack of the first write too, once disabled-by-default-devtools.timeline.stack is recorded. And because ids are handed out per node object, a component that replaces its elements on every render never builds up a count at all: each new node gets a new id.

Your recorder can restyle the page. A composited transform or opacity animation is re-resolved every frame only while something else is producing frames. Puppeteer's waitForFunction polls with requestAnimationFrame by default, so a capture that waits that way shows those animations resolving on every frame when the same page left alone does not. In headless mode Puppeteer also passes --hide-scrollbars, and then custom scrollbar styles are never resolved at all.

The count is not the cost. There is no duration, and a style served from Blink's matched-properties cache, or an animation frame that reuses a cached base style, writes the same event as a full cascade. Use the UpdateLayoutTree duration for time, and CSS selector stats for where it went.

elementCount, and so this event, misses styles that changed without being resolved. The independent-property shortcut can restyle a whole subtree and report one element. Recording blink or blink_style adds counters to the end of Document::updateStyle, among them stylesChanged and independentInheritedStylesPropagated, which show the gap.

There is no frame id. Filter on the process and thread, and take the document from the enclosing UpdateLayoutTree's beginData.frame. Events outside any UpdateLayoutTree have no document you can read off the trace, and parentNodeId is 0 for the root element of every document, a frame's as well as the page's. In a trace recorded across the whole browser, other renderer processes, Chrome's own WebUI pages among them, write these too; nodeId comes from a counter each renderer process keeps for itself, so an id is meaningless outside the process that wrote it.

Recording it. DevTools adds the category when Invalidation tracking or Enable CSS selector stats is on. Nothing in DevTools reads the event, and the Performance panel draws it only with Show all events on. It is one event per resolved style, so a page's first recalculation alone can write thousands.

Older traces differ. Chrome 134 wrote this name with a single args.elementId. Chrome 134 to 137 wrote it before the early return for unmatched pseudo styles, so the events there could outnumber elementCount; Chrome 135 brought the current data fields. Until Chrome 139, nodeId was the element passed in: for content cloned into an SVG <use> that is the original rather than the clone, and for ::first-letter it is the element the letter belongs to. parentNodeId was the plain parent, 0 for anything at the top of a shadow tree.

{
  "name": "StyleResolver::ResolveStyle",
  "cat": "disabled-by-default-devtools.timeline.invalidationTracking",
  "ph": "I",
  "ts": 1102940676,
  "tts": 40052,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "nodeId": 2,
      "parentNodeId": 0,
      "pseudoId": 0
    }
  }
}

See also UpdateLayoutTree · StyleRecalcInvalidationTracking · ScheduleStyleRecalculation · SelectorStats · Layout · Animation

categories

disabled-by-default-devtools.timeline.invalidationTracking

usage

very high

references

style_resolver.cc, inspector_trace_events.cc, computed_style_constants.h

Chrome's compositor brings one of its layers up to date with the content most recently painted for it.

Spec

cc's PictureLayer::Update brings one picture layer up to date during the compositor's update-layers step, handing over the region invalidated since the last frame and, if the layer was invalidated or resized, taking the display list its content client supplies and checking whether it paints a single solid colour, on the main thread of the process that owns the layer tree.

Arguments

Observed 534,568 times on 182 of 300 sites.

Behaviour

The name belongs to cc, Chromium's compositor library, not to Blink. It is defined in cc's DevTools instrumentation header and written from exactly one place, PictureLayer::Update, as a begin and end pair carrying the layer's id and the id of the layer tree it belongs to. A picture layer is cc's layer type for content that is drawn from a recorded list of drawing commands, a display list, as against a texture, a video frame, an embedded surface or a single solid colour.

cc writes it during its update-layers step, which walks the layer tree and calls Update on every layer that is drawn, has content of its own and has a size. Whether the layer changed is not a condition: an untouched layer gets its UpdateLayer in every frame that reaches this step, and returns within a microsecond or so. Layers that exist only to hold a transform or a scroll position get none, and neither do cc's other layer types. That includes a composited layer whose paint is one flat colour: Blink hands cc a solid-colour layer for it, not a picture layer. Frames that were only asked to run animations or requestAnimationFrame callbacks, and changed nothing, never reach the step and write none.

In a renderer the step runs on the main thread, inside the Commit slice that ProxyMain::BeginMainFrame opens once Blink has finished its lifecycle:

BeginMainThreadFrame                instant: the main-thread frame starts
UpdateLayoutTree, Layout, PrePaint, Paint
Layerize                            Blink builds cc's display lists here
Commit
  LayerTreeHost::DoUpdateLayers     only with the cc category
    PictureLayer::Update            only with disabled-by-default-cc.debug
      UpdateLayer                   one per picture layer

In a Performance recording the two cc slices are not recorded, so UpdateLayer sits directly under Commit.

By then there is nothing left to paint. Blink converted its paint into a cc display list for each layer during Layerize. Inside the slice cc first takes the region Blink invalidated on the layer since the last frame, to send to the compositor thread with the commit. If the layer was neither invalidated nor resized, that is the whole call. Otherwise cc asks Blink's content client for the display list and gets back the one built during Layerize; if it is new, cc widens the invalidation when the recorded area changed, works out whether the list amounts to one solid colour, and emits a snapshot of it if a paint-instrumentation category is being recorded. Chromium's own comment on that step says that for Blink-backed layers, painting "amounts to copying the Blink display list".

The browser process writes it too. Chrome's own interface is drawn by a cc compositor running on the browser's main thread, outside any Commit slice, and there the content client really does paint: it records the interface's drawing inside the call. Those are the long UpdateLayer events. A recording of a page includes them, because DevTools adds the browser process to every page recording, and they appear whether Chrome runs headless or with a window. On a test page that stopped changing after load, and on a real article page during load and scroll, the browser's UpdateLayer events outnumbered the page's.

The event dates from June 2014, when the trace-based Timeline was being built. Its commit says it was added "so we can easily bind pictures to layers and related blink-side paint events". At that time PictureLayer::Update returned before opening the scope when nothing had changed, and inside the scope it asked WebKit to paint the layer's picture there and then. Reading it as a layer being painted describes that arrangement, not a web page in current Chrome.

Derivations

How many picture layers the page draws, from an ordinary recording. Count the UpdateLayer events inside one renderer Commit, on the same pid and thread. That is the number of picture layers with content in that frame. On a fixture with three promoted boxes and text in the page body it was four every frame, the three boxes and the document's scrolling background, while the layers that only hold a transform or scroll were left out. Three conditions. Solid-colour layers are not counted: on a second fixture whose page background was plain white, the document's background layer drew content but was a solid-colour layer and wrote no UpdateLayer. A Commit that holds none is a frame that never reached update-layers, not a page without layers, so take the count from a Commit that has any. And an out-of-process iframe has its own renderer, tree and Commits. The layer list itself, with a name for each layer, is only in LayerTreeHostImpl:snapshot, which needs a category DevTools records only with advanced paint instrumentation on; UpdateLayer is in every Performance recording.

Which layers took new content in a frame. An unchanged layer returns almost at once and one with a new display list does more work, so in bulk the long ones are the changed layers; the two ranges overlap by a few microseconds, so a single duration proves nothing. To be certain, record the cc category and look for RecordingSource::FinishDisplayItemListUpdate inside the slice. The same layerId then turns up in RasterTask's args.tileData.layerId in the same process, which is how to tie a raster task to the frame and layer that caused it.

Traps

It is not Blink, and it is not paint. In a renderer, the painting of a layer happened earlier, in Paint, and the conversion into cc's display list in Layerize. Adding up UpdateLayer durations does not give you paint cost. A long one in a renderer is a layer that took a new display list, or, if advanced paint instrumentation was on, mostly the cost of recording it (see below).

Many of them are Chrome's own UI. Filter on pid. The browser process has its own layer tree, every page recording includes it, and its UpdateLayer events are the ones that actually record drawing, so they are also the longest. On a quiet page, and even during an ordinary page load, they can outnumber the page's own.

Both ids are per process. layerId and layerTreeId come from counters that start at 1 in every process, so ids from different processes collide: in one capture the browser's UI tree and a cross-site iframe's renderer both had layerTreeId 1. Key on pid as well, and use SetLayerTreeId to find which tree belongs to which frame.

Some of them are instants. A few UpdateLayer records have ph I and "s": "t" instead of X and a dur. They come from the same call. Chrome records trace timestamps in whole microseconds, cutting each begin and end down to the microsecond, and when both land in the same one the slice has zero duration, which Perfetto's JSON exporter writes as an instant. They are the fastest calls, from the browser and from renderers alike. Treat them as zero-length slices, and read a dur of 1 as "under two microseconds", not as a measurement. A lone B with no end is a slice that was still open when the recording stopped.

Only a disabled-by-default category has it. UpdateLayer is on disabled-by-default-devtools.timeline. DevTools turns that on for every Performance recording; a custom trace that asks for devtools.timeline alone gets none.

The Performance panel hides it. DevTools records it, then gives it a hidden style, so no bar is drawn and its time shows up as self time of the Commit above it.

Advanced paint instrumentation makes it far longer. That checkbox adds disabled-by-default-devtools.timeline.picture, and with it on, every layer that took a new display list serializes that list into a cc::DisplayItemList:snapshot event inside this slice: cc plays the whole list back into a Skia picture and base64-encodes it. In two small fixtures the median for such layers went from about ten microseconds to about a millisecond, and the browser's grew as well. Layers that did not change were unaffected. Read durations from a recording without that setting.

DevTools does not use it for layer attribution any more. Its one consumer, trace_engine's LayerTreeHandler, keeps each UpdateLayer so that it can tell which layer a DisplayItemList snapshot on the same thread belongs to, and then looks for a Paint with that layerId to attach the snapshot to. Blink now writes layerId: 0 on every Paint, which the handler discards, so the pairing never succeeds: run over a Chrome 153 trace recorded with the paint-instrumentation categories, it matched nothing. It never read RasterTask, and it builds no layer tree; the tree DevTools shows for a trace comes from LayerTreeHostImpl snapshots.

{
  "name": "UpdateLayer",
  "cat": "disabled-by-default-devtools.timeline",
  "ph": "X",
  "ts": 1102926233,
  "dur": 460,
  "tdur": 372,
  "tts": 186859,
  "pid": 8178,
  "tid": 8178,
  "args": {
    "layerId": 29,
    "layerTreeId": 1
  }
}

See also Commit · Layerize · Paint · RasterTask · BeginMainThreadFrame · UpdateLayerTree

categories

disabled-by-default-devtools.timeline

usage

high

duration

very short

references

devtools_instrumentation.h, picture_layer.cc, frame_viewer_instrumentation.cc, tile_manager.cc

The old name for Chrome bringing its tree of compositing layers up to date after layout, in the step now called PrePaint.

Chrome no longer emits this event. The code that wrote it was found in the history and then found to have been deleted.

Spec

Blink's FrameView, later LocalFrameView, traced the part of a rendering update between layout and paint for one local frame root under this name, on the renderer's main thread, from Chrome 38 until Chrome 102 renamed it PrePaint.

Behaviour

Current Chrome does not write this event. No Chromium source uses the name for a trace event any more, and a recording on Chrome 153 with every default category and all the DevTools and cc debug categories switched on contained none. You meet it in a trace recorded by Chrome 101 or earlier, or in a tool built to read one.

Its last form, from Chrome 45 to 101, was a slice on devtools.timeline that Blink wrote on the renderer's main thread each time it ran the rendering lifecycle past layout for a local frame root (the main frame, or an iframe whose parent is rendered by another process), with a single argument, data.frame. That is normally once per frame, with two exceptions. The lifecycle runs in a loop, and a ResizeObserver callback that changes layout sends it round again, writing a second slice inside the same update. And by Chrome 101 every hit test, such as document.elementFromPoint(), ran the lifecycle up to this step and wrote one outside any frame, even when nothing on the page had changed.

The name describes the job it was built around. Before Chromium's CompositeAfterPaint project, Blink decided which elements got their own compositor layer before painting, then updated its tree of those layers to match, and that update is the layer tree in the name. What else sat inside the slice changed release by release:

Chrome 38-44   an instant, no duration, at the start of the compositing update
Chrome 45-56   compositing update, then paint invalidation
Chrome 57-58   the same, with the pre-paint step inside, though its tree
               walk only ran behind an experimental flag
Chrome 59-85   compositing update, then the pre-paint tree walk
Chrome 86-96   compositing inputs, pre-paint, compositing assignments
Chrome 97-98   the same calls, but compositing assignments no longer
               assigned layers
Chrome 99-101  compositing inputs and pre-paint only
Chrome 102     renamed PrePaint, same place in the code

The instant was a mistake. Blink revision r196226 (commit 6b5929fa9f in the old Blink repository, 07d4e5607d in Chromium's), in June 2015, turned it into a slice with the message "This was never meant to be an instant event, appears to be a typo", and r196147 a few days earlier moved it from disabled-by-default-devtools.timeline to plain devtools.timeline; both shipped in Chrome 45. CompositeAfterPaint moved the layer decision after paint and was switched on by default in Chrome 97, after which the compositing-assignments phase inside this slice stopped assigning layers, and Chrome 99 removed the call. From Chrome 99 the slice held exactly what the renamed event held in Chrome 102.

The rename is crrev.com/c/3519012, commit 3a09b7b7dd, "Add a Pre-Paint devtools timeline event (blink side)", by Philip Rogers, landed on 22 March 2022 and first shipped in Chrome 102. It changed the name on the same line, kept the category, and swapped the argument builder: UpdateLayerTree wrote only frame, PrePaint added isMainFrame and page, and isOutermostMainFrame followed in Chrome 105. The DevTools half landed six days earlier and taught the Performance panel the new name while keeping the old one.

There was an earlier UpdateLayerTree that was never a trace event. Before the DevTools Timeline was built on Chrome's tracing, Blink's InspectorTimelineAgent sent DevTools its own records over the DevTools protocol, and one record type had this name: from Chrome 36 a duration record around the same compositing update. For Chrome 38 to 41 both existed, on neighbouring lines of the same function. Blink revision r189656 (commit 59a9467588 in Chromium's repository) deleted the record type with the rest of the old Timeline in February 2015 ("Timeline is replaced with tracing"), so Chrome 42 onward has only the trace event. If you find the name in a DevTools timeline export from 2014, it is that record, in that tool's own format, and it will not be in any trace file.

Traps

One name, five different measurements. A trace from Chrome 38 to 44 has the event with no duration at all, so summing it gives zero, not a cheap step. From 45 to 58 it covers the compositing update and paint invalidation, and the pre-paint tree walk either ran after the slice closed or did not run by default. From 45 all the way to 96 it also contains the layer decisions that current Chrome makes after paint, in Layerize. Chrome 97 and 98 are layer-free, and only Chrome 99 to 101 match a Chrome 102 PrePaint exactly. Comparing durations across those boundaries compares the definition, not the page.

Renaming it to PrePaint is safe only for Chrome 97 to 101. Tools that want the modern name will accept the renamed event, but on older traces they are being handed a slice that includes, or lacks, other phases. It also carries only frame, never isMainFrame or page, and a parser that expects isOutermostMainFrame will miss it on PrePaint from Chrome 102 to 104 as well.

The category moved. From Chrome 45 it is on plain devtools.timeline; recording only disabled-by-default-devtools.timeline does not capture it. Only the Chrome 38 to 44 instant lives on the disabled-by-default category.

DevTools draws it and then ignores it. The Performance panel still labels it "Update layer tree" under Rendering. But the layout-shift handler collects only events named PrePaint, and the CLS culprits insight ties every root cause to one of those. On a trace older than Chrome 102 the layout shifts still appear, sitting inside this slice, but the culprits list stays empty. trace_engine declares the name and no type or arguments for it.

Lighthouse keeps both names in one bucket, but not the work. Its Rendering task group lists UpdateLayerTree and PrePaint side by side, with a comment pointing at the rename. It does not list Layerize, which falls through to its parent's group and ends up as Other. The layer-assignment time that sat inside UpdateLayerTree, and so counted as Rendering, up to Chrome 96 is Other in a current trace.

Look-alikes. UpdateLayer is a different event. UpdateLayerTreeHost is the name of methods in cc and in the browser's compositor, not an event, and Android.Compositor.UpdateLayerTree.Duration.Subsampled is a UMA histogram, not a trace event.

See also PrePaint · Layerize · CompositeLayers · Layout · Paint · UpdateLayer · LayoutShift

references

local_frame_view.cc

Chrome brings a document's styles, and the layout tree built from them, up to date.

Spec

Blink's Document::UpdateStyleAndLayoutTreeForThisDocument brings one document's computed styles up to date and rebuilds the parts of its layout tree that depend on them, together with the stylesheet, media query and invalidation work that has to happen first, on the renderer's main thread.

Arguments

Observed 42,674 times on 182 of 300 sites.

Behaviour

One event is one pass of Blink's style update over one document. Before it opens the slice, Blink checks whether anything is out of date, and if nothing is it returns without writing anything. So every event had work waiting, and a read against a clean document leaves no trace: ten getComputedStyle(body).color reads in a row wrote one event, for the first read, which found a running transition to advance, and nothing for the nine after it. Inactive documents, render-throttled frames (an off-screen cross-origin iframe, for example) and documents whose lifecycle is postponed are skipped the same way.

The slice covers more than matching selectors. In order, Blink advances animation timing, re-evaluates matchMedia lists, updates SVG <use> trees, turns any stylesheet that was added or changed into a rule set (Blink's indexed form of a stylesheet, built before any selector can be matched against it), handles counter styles, viewport units, env() and font changes, then walks the pending invalidation sets (the per-selector lists Blink uses to decide which elements a class, id or attribute change can affect) to mark those elements, then recalculates their styles, and finally rebuilds the layout tree, the tree of boxes that layout works on, for elements that gained or lost a box. Recording blink or blink_style shows the main stages as child slices: Document::updateActiveStyle, Document::updateStyle, and inside that Document::recalcStyle and Document::rebuildLayoutTree.

A recalculation is either scheduled or forced. A change writes ScheduleStyleRecalculation, and the next rendering update runs this pass after the requestAnimationFrame callbacks and before Layout. A forced pass happens when script reads something that needs current style, such as a property of getComputedStyle() or a geometry property like offsetHeight: Blink runs the pass there and then, inside the script's task. A style read only forces the pass if the element being read could be affected. Reading body's color after changing the width of one of its children forced nothing, and that change waited for the next frame. Blink also forces passes of its own with no script running, for example while handling input or dispatching an event. In a same-process iframe the parent document is brought up to date first, so a read in the iframe can write the parent's event, if the parent had work waiting, before the iframe's own. A single update can also write two in a row for the same document, when a ::backdrop or an element leaving the top layer needs another pass.

beginData is written as the slice opens. It always has frame, the id of the document's frame. With disabled-by-default-devtools.timeline.stack recorded, which DevTools does by default, every event also gets a sampleTraceId, and it gets a stackTrace only if V8 was running JavaScript at that moment. JavaScript is only on the stack when script caused the pass synchronously, so the stack is the mark of a recalculation forced by script. In four traces, three real sites and one older capture, every event with a stack sat inside a script-execution slice such as FunctionCall, EvaluateScript or v8.run, and every event without one did not. The script is not always the page's own: a browser extension's content script runs in the page's process, and a pass nested inside a forced one (the parent document of an iframe, or an SVG image's own document) carries the stack of the script that forced the outer pass. How many events in a recording carry a stack is therefore a property of the page's script and of what the recording did to the page, which is the split you see in the arguments table.

elementCount is written as the slice closes. It is how many times StyleResolver::ResolveStyle, the function that computes one style from scratch, completed for this document during the pass, read as the difference in a per-document counter. What that number does and does not include is in the traps below.

Derivations

Which line forced a recalculation, and how much forced style work each script caused. With the stack category recorded, the top frame of beginData.stackTrace is the JavaScript that asked, and its column points at the property read that did it: in getComputedStyle(el).color it is the .color, not the getComputedStyle() call, which on its own does nothing. DevTools' Function stack puts these frames over the top of the stack it rebuilds from the CPU profile, because profile frames carry where a function is declared and these carry where it was called from. Adding up the duration of stack-bearing events by the top frame's URL gives forced style time per script, including the tasks that stay under DevTools' warning threshold. That sum means something only in a recording without invalidation tracking or selector statistics (see the traps), and only if nested events are left out so no pass is counted twice; forced Layout is a separate event and a separate sum.

How far an invalidation reached. elementCount is how many styles Blink computed from scratch, and that is decided by invalidation, not by how many styles actually change. Adding a class to body with the rule .on #g div restyled every div on a test page, 1505 of them, because Blink keys the invalidation for that rule on the div in its last compound, and only the 500 inside #g changed. A rule keyed on a class, .on3 .h3, restyled exactly the 500 elements that carried it. Comparing elementCount with the number of elements you expected to change is a direct test of whether a selector or the element you toggle a class on is too broad. It works for class, id and attribute changes; add any ::before and ::after the elements have, and do not use it for a change to an inherited property, which the count mostly leaves out. With blink or blink_style recorded you do not have to know the expected number: counters on the nested Document::updateStyle split the same resolutions into stylesChanged and stylesUnchanged, 500 and 1005 in the body class example.

Which styles it counted. Record disabled-by-default-devtools.timeline.invalidationTracking and every counted resolution also writes a StyleResolver::ResolveStyle instant, with the node id, inside the slice. In every recalculation of two separate captures the number of those instants equalled elementCount, so they are the list the number stands for. A ::before or ::after shows up as a node of its own, with the originating element as parentNodeId and pseudoId 0, so pseudoId does not separate them from elements. The recording makes the slice many times longer (see the traps), so use it to find out what was restyled, not how long it took.

Traps

elementCount is not the number of elements whose style changed. It counts completed calls to StyleResolver::ResolveStyle, and those differ from changed elements in both directions. Every restyled element is counted whether or not its style came out different: of the 1505 in the body class example, 1005 were unchanged. Pseudo-elements are counted: turning on a ::before for 500 elements added 500. An element matching an @starting-style rule has its style resolved twice and counts twice. In the other direction, when only independent inherited properties change on a parent (color, visibility, pointer-events, cursor, text-transform and a few more), Blink copies them into children's existing styles without resolving them, and those children are not counted: setting color on a container of 500 plain divs counted 1, and setting it on a body whose divs had ::before pseudo-elements changed 2005 styles and counted 503, because pseudo-elements cannot take that shortcut. Elements inside a display: none subtree are not restyled at all, so a rule that only reaches into one counted 0, and when script asks for the computed style of such an element Blink resolves it on demand outside any UpdateLayoutTree, where no event counts it. DevTools shows the field as "Elements affected", which is wrong on both counts.

Container-query restyles are not in this event. When a size container changes size, Blink restyles the elements that depend on it from inside layout. Widening a container so that a @container rule flipped for 500 children wrote an UpdateLayoutTree with elementCount 1, the container, and all 500 resolutions happened inside the following Layout, which counts them nowhere.

Few elements and a long duration does not mean slow selectors. Adding a <style> of 5000 rules that matched nothing wrote a pass of about 3ms with elementCount 0; nearly all of it was RuleSet::addRulesFromSheet, building the rule set. Setting color on a container of 500 plain divs took about half a millisecond with elementCount 1, spent copying the new value into the 500 children. Invalidation walking, layout tree rebuilding and font updates are in the slice too, and real sites write zero-count passes of several hundred microseconds. Dividing the duration by elementCount gives a number with no meaning. Record blink or blink_style to see which stage the time went to, and read counters on the nested Document::updateStyle, which splits the work into styles changed, unchanged and propagated.

The categories you record change the duration, and slow the page too. On a test page, a class change that restyled about 2,000 elements took about 2ms timed from inside the page with nothing recording, and the UpdateLayoutTree slice read the same with DevTools' timeline and stack categories. Adding disabled-by-default-devtools.timeline.invalidationTracking made the slice read 20 to 26ms, about 8.5ms came with disabled-by-default-blink.debug, and 26 to 28ms with both, which is what DevTools' "Enable CSS selector stats (slow)" setting records. The page's own timer grew by the same amount, so this is work the recording adds to the main thread, not a fault in the timestamps. Invalidation tracking writes several records, with the selectors involved, for every element an invalidation set reaches, and its cost follows that reach rather than elementCount: a pass that resolved 503 styles with no invalidation set involved went from about 2.4 to 3.3ms. blink.debug switches on a clock read around every selector match attempt. The real-site traces behind this manual's figures were recorded with invalidation tracking on, so the durations they report for this event carry the same inflation. A recording made with either category is fine for finding out what was restyled and misleading about what it costs.

Selector stats are paired by order. The SelectorStats event is written just after the slice closes, and DevTools attaches each one to the last recalculation it saw, with no check of frame or time. Blink collects the statistics across all matching since the last dump, so matching done during layout for container queries is reported with the next recalculation. In two captures a recalculation that restyled nothing carried 1000 match attempts for #cq div, all of them from the layout before it.

elementCount can be missing. It is written when the slice ends, so a recalculation still running when the recording stopped is left as a B event with beginData and no count.

The stack depth depends on the recorder. Blink asks V8 for a short stack, which is one frame unless a client with the Runtime domain enabled is attached. The same three-deep call gave [inner] under Chrome's own --trace-startup and the full chain through puppeteer. A DevTools recording gets the deep version. lineNumber and columnNumber count from one; DevTools subtracts one before it shows them.

Some recalculations belong to other documents. An SVG image has a document of its own, and on one real page two of them loaded and ran their own style passes inside the page's recalculation, with an empty document URL and a full set of loading events. Because the page's script was still on the stack, those nested events carry the page's stackTrace. Chrome's own pages write these events too, in their own processes. An extension's content script runs in your page's process, and when it forces a recalculation the event is your page's, with the extension's script as the stack: in one trace a chrome-extension:// content script forced a pass over 327 of the page's elements. Filter on pid and beginData.frame before adding anything up, check the stack's URL before blaming your own code, and do not count nested slices twice.

DevTools finds forced recalculations without the stack, and counts more of them. Its forced reflow warning, which the Forced reflow insight is built from, counts Layout and UpdateLayoutTree slices nested inside any event it treats as JavaScript, whether or not they carry a stack, and reports a task only when those add up to thirty milliseconds. EventDispatch is on its list of JavaScript events, so a pass Blink forced while dispatching an event, with no script on the stack, is flagged as well.

The raw name is not the one DevTools uses. DevTools calls the event RecalcStyle in its code and "Recalculate style" on screen; a trace file has only UpdateLayoutTree. With blink or blink_style recorded there is also a Document::recalcStyle slice, which is only the recalculation stage inside this one.

{
  "name": "UpdateLayoutTree",
  "cat": "blink,devtools.timeline",
  "ph": "X",
  "ts": 1103040787,
  "dur": 83,
  "tdur": 76,
  "tts": 131537,
  "pid": 8257,
  "tid": 8257,
  "args": {
    "beginData": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "sampleTraceId": 6909218608593002,
      "stackTrace": [
        {
          "columnNumber": 39,
          "functionName": "",
          "lineNumber": 85,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        }
      ]
    },
    "elementCount": 1
  }
}

See also ScheduleStyleRecalculation · StyleResolver::ResolveStyle · StyleRecalcInvalidationTracking · StyleInvalidatorInvalidationTracking · SelectorStats · Document::updateStyle · Layout · Document::UpdateStyleAndLayout · Blink.ForcedStyleAndLayout.UpdateTime · ParseAuthorStyleSheet

categories

blink, devtools.timeline

usage

moderate

duration

long

undeclared args

args.beginData.stackTrace[].columnNumber, args.beginData.stackTrace[].functionName, args.beginData.stackTrace[].lineNumber, args.beginData.stackTrace[].scriptId, args.beginData.stackTrace[].url

references

document.cc, source_location.cc, v8-stack-trace-impl.cc, v8-debugger.cc, style_resolver.cc

Chrome styled an image whose CSS does not fix both its width and its height.

Spec

Blink's LayoutImage::StyleDidChange writes this instant on the renderer's main thread, during style recalculation, whenever an image box receives a computed style that LayoutImage::IsUnsizedImage judges to leave its dimensions open.

Arguments

Observed 8,564 times on 108 of 300 sites.

Behaviour

The check runs when an image box is given a style, not when it is laid out or when its file arrives. That happens when the box is created, when it is created again after the element comes back from display: none, and on every later restyle that hands the image a new computed style, including an inherited one: setting color on a wrapper wrote a second event for the unsized image inside it, while setting background on the same wrapper, which does not inherit, wrote nothing. A layout-only change, such as narrowing the image's container, writes nothing, and neither does the image finishing loading or failing to. So the count is not the number of unsized images; it is unsized images times the number of times each was restyled, and a real page can repeat the same node many times. In every capture the event sat inside UpdateLayoutTree, usually long before the image had loaded: a test image delayed by 1500ms had its event about 10ms after navigation.

The rule, from IsUnsizedImage, reads the computed style and nothing else. An image counts as sized when its width and its height are both a length, a percentage, or a calc() made only of those, or when it has a bare aspect-ratio: <ratio> and one of the two. auto, fit-content and the other sizing keywords do not count, aspect-ratio on its own does not count, and min- and max- sizes are not consulted. HTML width and height attributes count, because Blink turns them into CSS width and height as presentational hints, styles that any author rule overrides. They also produce aspect-ratio: auto w / h, and that form does not count: only a bare ratio does, so aspect-ratio: auto 4/3 in your own CSS does not count either. In a <picture>, a selected <source> that carries width or height replaces the <img>'s own. srcset, sizes and loading=lazy play no part; a lazy image far below the fold wrote its event without ever being fetched. An image under display: none, or inside something that is, has no box and writes nothing; visibility: hidden keeps the box and does write it.

The box can belong to more than <img>. <video>, <input type=image> and an <object> or <embed> holding an image use the same layout class, and so do list-style-image markers and anything given an image with content: url(), pseudo-elements included. SVG <image> and CSS background images do not.

The event is written on devtools.timeline, but only after Blink has checked that disabled-by-default-devtools.timeline is recording too. Both are in the Performance panel's default set. The invalidation tracking category has nothing to do with it: adding it changed neither the count nor which images were reported.

DevTools reads it in one place, the CLS culprits insight, and shows the result in two. For each rendering update that contains a layout shift, the insight takes the first PaintImage written after that update's PrePaint and asks whether any LayoutImageUnsized has the same nodeId. If one does, that image is recorded as a cause of every shift in the update. Select a shift in the Layout shifts track and the details pane lists it as "Unsized image" with a link to the node; the insight's Top culprits list, which covers only the worst cluster and stops at three, shows it as "Unsized image element" after web fonts, injected iframes and non-composited animations. Lighthouse's layout shift audit shows the same match as "Media element lacking an explicit size".

Traps

It flags images that cannot shift. The responsive pattern everyone recommends, width and height attributes with height: auto in CSS, whether beside width: 100% or the common max-width: 100% reset, is unsized by this rule, because height: auto overrides the height attribute and the ratio the attributes leave behind is the auto w / h form. Chrome still reserves the box from that ratio: in a test such an image loaded late without moving anything, and was reported anyway. The same goes for aspect-ratio: auto 4/3. Adding a bare aspect-ratio with the same ratio silences it. The event is a statement about the style, not a prediction of a shift.

It misses images that do shift. A percentage counts as sized even when it cannot resolve. height: 50% inside a parent whose height is auto behaves as auto in layout, so the image took its height from the file when it arrived and pushed the paragraph below it down, with no LayoutImageUnsized and no culprit in DevTools.

Lighthouse's unsized-images audit uses a different rule. It inspects the DOM and CSS itself and never reads this event. It accepts a width or height attribute even when CSS sets that axis to auto, so an image can pass that audit and still be reported here.

A recording that starts late has none. The event is written when the image is styled, so if you start recording after the page has loaded and then trigger the shift, the trace holds the shift and the image's paint but no LayoutImageUnsized, and DevTools cannot name the image as the cause. Record from a reload.

The culprit link is a guess by paint order. DevTools only looks at the first image painted after the shift, however much later that is, in any frame, and ignores when the LayoutImageUnsized was written. In a test, a banner inserted by script caused the only shift, no image painted for the next 900ms, and then a correctly reserved image that this rule flags arrived and was named as the cause. The other way round, two unsized images that shifted content in the same update produced one culprit, the one painted first.

nodeId can be 0, and then DevTools never names it. Images with no DOM node of their own, a ::before or ::after with content: url() or a list-style-image marker, report nodeId: 0, which resolves to nothing. Their PaintImage carries the host element's nodeId instead, so the culprit match can never succeed for them, even when they cause the shift. For the rest nodeId is a backend node id that DOM.describeNode resolves while the node is alive, and it may be a <video>, <input> or <object> rather than an <img>. The event has no URL; the PaintImage for the same nodeId has it.

Count elements, not events. One image restyled five times is five events. Deduplicate on nodeId within a renderer process before you count unsized images.

Both timeline categories are needed. A trace recorded with devtools.timeline alone, or with disabled-by-default-devtools.timeline alone, contains none of these, however many unsized images the page has.

{
  "name": "LayoutImageUnsized",
  "cat": "devtools.timeline",
  "ph": "I",
  "ts": 1109175726,
  "tts": 95991,
  "pid": 8475,
  "tid": 8475,
  "s": "t",
  "args": {
    "data": {
      "frameId": "9AE6572E1DCD19954F9F2627AE88998A",
      "nodeId": 16
    }
  }
}

See also LayoutShift · PaintImage · PrePaint · UpdateLayoutTree · StyleRecalcInvalidationTracking

categories

devtools.timeline

usage

moderate

references

layout_image.cc, identifiers_factory.cc

Chrome marked one piece of the page's layout tree as needing to be laid out again.

A DevTools Performance recording contains this event only with Enable CSS selector stats (slow) or Invalidation tracking turned on, which records disabled-by-default-devtools.timeline.invalidationTracking.

Spec

Blink's LayoutObject::SetNeedsLayout records one layout object, a box or text run in the layout tree, going from not needing to needing a full layout of its own, with the reason string its caller passed and the DOM node the object belongs to, on the renderer's main thread.

Arguments

Observed 1,256,445 times on 182 of 300 sites.

Behaviour

Every object in Blink's layout tree, the tree of boxes and text runs that mirrors the rendered part of the DOM, carries a bit that says it needs a full layout of its own. SetNeedsLayout sets that bit and writes this event only when the bit was clear, and laying the object out clears it again. So an object writes at most one of these between two layouts, whatever happens to it in between. In one capture, writing an element's width, forcing a style update with getComputedStyle, writing its height and forcing style again wrote one event: the second style update found the box already dirty. The same sequence with an offsetHeight read in the middle, which lays the box out, wrote two. (Twenty writes to width in one task also produce one event, for a simpler reason: style is recalculated once, after the last write.)

Only that call writes it. When Blink then marks the element's ancestors, it uses a different bit and writes nothing. Changes that only need a positioned box moved write nothing either: setting top or left on an absolutely positioned element, or top on a relatively positioned one, produced a Layout and no event. Nor do changes that only need a repaint or a compositor update, such as changing an existing transform, although adding or removing a transform writes Style changed. The event is written first, and the walk up the ancestors that may end in an InvalidateLayout comes after it in the same call.

The caller supplies reason, one of thirty fixed strings that Blink keeps for tracing only. It names the code path that did the marking, not the thing you changed. Added to layout is written for every layout object Blink creates and inserts, so every element and text node the parser builds writes one, as do anonymous boxes and pseudo-element boxes. Removed from layout is written for an object being removed that has been laid out before and is not already waiting for layout. Style changed means a style recalculation produced a new style whose difference needs a full layout; it does not say which property or rule. Text changed comes from changing a text node's data, and Size changed from replaced or embedded content, such as an image, canvas, video, iframe or SVG root, whose natural size changed. Attribute changed is narrower than it sounds: a handful of form control, frameset, table column, canvas and MathML attributes, such as size on an input or rows on a textarea. An ordinary attribute or class change, including an image's width attribute, reaches layout as Style changed. DOM changed comes only from a canvas transform change; adding and removing nodes is Added to layout and Removed from layout. Unknown includes whole-view relayouts, which is what a viewport resize produced, and Inspected by devtools is DevTools' element inspector dirtying a flex or out-of-flow box to draw its overlay.

Fonts changed comes from a walk over the whole layout tree that marks every object whose font fallback list Blink has thrown away, and which lists go depends on what changed. When a web font finishes loading, only the lists that were waiting on it go, so only the objects using that font are marked. Any other change to the page's set of fonts throws them all away: a stylesheet adding an @font-face rule, document.fonts.add(), or a loading font entering or leaving its block period. Then every object in the tree is marked. In a fixture, adding a FontFace for a family nothing used marked every layout object on the page, and the Layout that followed reported all of them dirty; the web font that one element did use marked three objects when it arrived.

nodeId and nodeName name the nearest DOM node that generated the object. Many layout objects have no node of their own, so Blink walks up the layout tree until it finds one. A text run names its own text node, as #text. The root of the layout tree names the document. An anonymous block Blink creates to wrap inline content names the element it sits in, and a ::before or ::after box, and the generated text inside it, name the element they belong to. Adding a block ::before to a div with text in it wrote three Added to layout events that all named the div: the pseudo-element box, its generated text, and the anonymous block that now wraps the div's own text. Some callers mark a parent or containing block on a child's behalf, and the event then names that ancestor. nodeName is the tag plus the element's id and classes as they were when the event was written. When no node exists anywhere up the chain, both fields are left out; which situations produce that has not been established.

stackTrace is captured on every event, whatever categories you record, and it is present exactly when JavaScript was running at the moment the object was marked. Where Blink marks the object decides that. Removing a node, changing a text node's data, setting canvas.width or an input's size mark objects synchronously, so the stack names the line that made the change. Writing a style, toggling a class, appending an element or writing inside a requestAnimationFrame callback leaves the marking to the style recalculation of the next rendering update, which runs with no script on the stack. A forced read such as offsetHeight or getComputedStyle pulls that recalculation into your task, and the stack then names the read. Elements the parser builds get no stack, unless a script forces layout while the page is still parsing: then every element parsed before that script carries its stack. Fonts, images arriving and CSS transitions had none in any capture. There is no sampleTraceId.

Derivations

Which objects a Layout had to lay out afresh, and why. These events, on the same frame since the previous Layout, name each object whose own layout was invalidated and the code path that did it. A wave of Fonts changed across the whole tree is a change to the page's set of fonts rather than to those elements, and a run of Added to layout and Removed from layout is DOM churn. The list is not the whole of Layout's dirtyObjects: that count also includes the ancestors marked on the way up and boxes waiting for a positioned move, which write none of these. No other event in the trace breaks a layout down by object.

Traps

The reason names the code path, and only the first one counts. Once an object is dirty, later invalidations of it write nothing until it has been laid out. In one capture, a canvas whose width changed after a style change wrote only Style changed, and an element whose style changed just before it was removed wrote no Removed from layout. And Style changed on a box can mean any property that affects layout.

Size changed on an image does not mean it was unsized. When an image's natural size arrives, Blink marks it for layout unless both its width and height are fixed, and always when it is a flex item. An image with width and height attributes and the usual height: auto wrote Size changed on arrival, as did one inside a flex container, though neither moved anything. LayoutImageUnsized is the event that flags images without dimensions.

nodeName is often not the element you changed. Anonymous boxes, pseudo-element boxes and their generated text all report the element they belong to, and callers that mark a parent or containing block report that ancestor. Changing only a ::before box's width wrote two Style changed events naming the host div, whose own box did not change. User-agent shadow content, such as a broken image's alt text, appears under internal ids you never wrote.

A stack is not proof that script did it, and no stack is not proof it did not. The stack is whatever was running when Blink marked the object. A style write or appendChild with nothing forcing it gets no stack, although your script caused it. The other way round, a parse-time script that reads offsetHeight forces layout of everything parsed so far, and in one capture every element above it carried that script's stack. A stack does not mean layout was forced either: removing a node or setting canvas.width carries one with no layout in the task. For forced reads the top frame is the read, not the write.

Recording this category changes the timings you are reading, in proportion to how many invalidations the page writes. Every one of these events asks V8 for a stack, and the category writes other per-element events alongside them. In one set of measurements, a forced update that created ten thousand layout objects took three to four times as long as under a normal DevTools recording. Nearly all of the extra time was inside UpdateLayoutTree, which grew roughly tenfold, and about half of it went on stacks because script was running. A class change restyling a few thousand elements grew the same way. Resizing a container of ten thousand objects, which marks one, cost nothing measurable, and Layout durations barely moved in any case. Do not read UpdateLayoutTree durations, or the time of script that forces them, from a trace that has these events.

Recording it. A DevTools recording has none unless the Invalidation tracking checkbox in the Performance section of DevTools' settings is on, which is not in the panel's own recording settings, or Enable CSS selector stats (slow) is on, which records the same category.

What DevTools shows. The event is not drawn in the flame chart unless Show all events is on. It appears when you select a Layout, under "Invalidations (N total)", grouped by reason, each row a link to the node and, when there is a stack, the script location of its top frame. DevTools keeps at most twenty per layout and drops duplicate rows, and it clears its pending list only after a Paint, so every forced layout in one task lists the invalidations of the ones before it as well: the fifth forced layout in a loop shows all five. It never attaches them to UpdateLayoutTree. The "First layout invalidation" stack and "Initiated by" link on a Layout come from InvalidateLayout, not from this event. LayoutShiftsHandler collects these events and their node ids, but nothing in DevTools reads what it collects: no layout shift culprit comes from this event.

nodeId belongs to one renderer process. It is a backend node id, resolvable through CDP only against the process that wrote it, and Chrome's own pages in other processes write these too. Filter on args.data.frame first.

Stack depth measures your recorder. V8 captures one frame unless a client has the Runtime domain enabled, and then up to 200. The frames run top first, lineNumber and columnNumber count from one, and scriptId is a string.

{
  "name": "LayoutInvalidationTracking",
  "cat": "disabled-by-default-devtools.timeline.invalidationTracking",
  "ph": "I",
  "ts": 1102950826,
  "tts": 45939,
  "pid": 8257,
  "tid": 8257,
  "s": "t",
  "args": {
    "data": {
      "frame": "14A831DCB73EB1205B67CDB89FC6EBD7",
      "nodeId": 14,
      "nodeName": "#text",
      "reason": "Removed from layout",
      "stackTrace": [
        {
          "columnNumber": 81,
          "functionName": "note",
          "lineNumber": 24,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        },
        {
          "columnNumber": 5,
          "functionName": "",
          "lineNumber": 47,
          "scriptId": "7",
          "url": "http://127.0.0.1:8801/"
        }
      ]
    }
  }
}

See also InvalidateLayout · Layout · UpdateLayoutTree · StyleRecalcInvalidationTracking · ScheduleStyleInvalidationTracking · LayoutImageUnsized · LayoutShift

categories

disabled-by-default-devtools.timeline.invalidationTracking

usage

very high

undeclared args

args.data.stackTrace[].columnNumber, args.data.stackTrace[].functionName, args.data.stackTrace[].lineNumber, args.data.stackTrace[].scriptId, args.data.stackTrace[].url

references

v8-debugger.cc, layout_invalidation_reason.h, capture_source_location.cc, node.cc, source_location.cc, v8-stack-trace-impl.cc and 1 more

Chrome notes that a change to an element may have put some styles out of date, and queues them to be checked.

A DevTools Performance recording contains this event only with Enable CSS selector stats (slow) or Invalidation tracking turned on, which records disabled-by-default-devtools.timeline.invalidationTracking.

Spec

Blink's RuleInvalidationData writes one instant for each invalidation set it finds after an element's class, id, attribute or pseudo-class state changes, just before PendingInvalidations decides what to mark or queue for the next style recalculation, on the renderer's main thread and only when disabled-by-default-devtools.timeline.invalidationTracking is recorded.

Arguments

Observed 70,330 times on 162 of 300 sites.

Behaviour

When Blink turns a stylesheet into a rule set it also compiles invalidation sets: for each class, id, attribute name and pseudo-class that appears in a selector, a note of what a change to it can affect, such as the element itself, its descendants that match .kid, or the siblings that follow it. When one of those features changes on an element, the style engine looks up the sets keyed on it and hands them to PendingInvalidations, which marks elements or queues work for the next UpdateLayoutTree. This event is written at the lookup, once for every set found. A class used in both .x .kid and .x + div has a descendant set and a sibling set, and toggling it wrote two events.

There are four versions of the payload, one per kind of change, and each adds exactly one key: changedClass, changedId, changedAttribute or changedPseudo. invalidatedSelectorId says which kind it is, as the string class, id, attribute or pseudo. Everything else is shared: frame, nodeId and nodeName for the element whose class, id, attribute or state changed, invalidationSet for the set that was found, and stackTrace when there is one.

Class, id and attribute events come from writes to the DOM. An id change looks up both the old id and the new one. Writing class is also an attribute change, so on a page with a selector on the class attribute, such as [class*=icon], one classList.add() writes changedClass events and a changedAttribute event for class as well. Setting a property through element.style counts as a change to the style attribute: it marks the element for recalculation directly, and it writes a changedAttribute: "style" event only when some selector tests [style], exactly as setAttribute('style', ...) does. When script inserts or removes an element beside siblings that + or ~ rules care about, Blink looks up the sibling sets for the classes, id and attributes those siblings already have, so an event can name a class nobody changed. Pseudo events come from state: :hover, :focus and :active, but only on elements whose style was flagged as depending on them, :disabled and :enabled on form controls, :defined as custom elements are defined, :first-child, :last-child and :only-child when script adds or removes children, and, going by the source, :link, :visited and :any-link on every link when the browser updates a document's visited links. For the structural ones the element is the sibling whose position changed: appending an <li> wrote last-child for the item that used to be last, not for the new one. The HTML parser does not write these for your document, because its insertions skip the sibling checks and it sets attributes before an element is in the document. Blink's own C++ does write them, for elements it owns: on real sites the built-in controls of a <video> and the placeholder inside an <input> wrote class, attribute and pseudo events while no script was running.

Many invalidations write nothing. A class that no selector mentions has no set, and toggling one wrote no event. Classes and ids that appear as the subject of a rule, as in .x { } or #x { }, are a special case. Each stylesheet counts them as it is parsed, classes and ids together and repeats included, and after the fiftieth Blink stops storing sets for them and adds them to a Bloom filter instead, a compact yes-or-probably lookup. A name found there invalidates the element without an event. Behind 49 such rules, a fiftieth class wrote an event and a fifty-first restyled its element and wrote nothing; a class in a second stylesheet started the count again and wrote one. :nth-child()-type positional invalidation, universal sibling rules such as div + .u, :has() invalidation of ancestors, adding or removing a stylesheet and, going by the source, ::part() all restyle elements without this event. The lookup is skipped entirely in an inactive document, during a style recalculation, and when the element's parent is already marked for a full subtree recalculation, which covers the whole document before its first style pass.

Because the event is written before scheduling decides anything, it can also be followed by nothing. Toggling a class on a display: none element wrote the event and no recalculation, because Blink drops descendant invalidation for an element that has no style. Going by the source, it also drops a sibling set when the element has no next sibling, and descendant sets when the element is already marked for a full subtree recalculation.

What happens next depends on the set. A set that covers the element itself marks it for recalculation on the spot, and a StyleInvalidatorInvalidationTracking with the reason "Invalidation set invalidates self" follows immediately. Descendant and sibling sets are queued on the element and walked at the start of the next UpdateLayoutTree, which writes a StyleInvalidatorInvalidationTracking for the element they were queued on and for each element they reach. Twenty class toggles in one task wrote twenty of these events and one recalculation.

stackTrace is there when JavaScript was running at the moment of the change, and only then. Script-made changes carry one; a hover from the mouse, focus from a click or the Tab key, a <details> opened by a click and Blink's own updates to its built-in controls do not. That is the split in the arguments table. Unlike the stack on ScheduleStyleRecalculation, this one does not need the disabled-by-default-devtools.timeline.stack category. How deep it goes depends on who is recording: Blink asks V8 for a one-frame stack unless a client with the Runtime domain enabled is attached to the page. The same three-deep call wrote one frame when the page was traced from the browser with nothing attached to it, and all three once a client attached and enabled Runtime. A recording made in DevTools gets the full chain.

Derivations

Which change queued the work a recalculation did, and how far it reached. The events before an UpdateLayoutTree name each element and class, id, attribute or pseudo-class that queued work in it and, when script did it, the line. Follow invalidationSet together with nodeId. A descendant or sibling set shows up in the recalculation as a StyleInvalidatorInvalidationTracking with the reason "Element has pending invalidation list" for the same nodeId, carrying the same value in invalidationList[].id, followed by one "Invalidation set matched ..." event with that id for each descendant or sibling the set reached. A set that covers the element itself writes "Invalidation set invalidates self" for the same nodeId straight away. Counting the matched events for one change says how many elements a single class toggle hit, and the selectors on them name the rules responsible. Neither half is enough alone: the invalidator events do not say what changed or who changed it, and this event does not say what it reached.

Traps

invalidatedSelectorId is not an id. It holds the kind of change, class, id, attribute or pseudo, and the value to look at is in the matching changed... key. reason appears in DevTools' type for this event and is never written. DevTools shows these events only in the Invalidations section of a Recalculate style event, grouped by that kind; it knows class, id and attribute, so every pseudo-class event, the most common kind on real sites, is filed under "unknown".

Older traces spell it differently. Up to Chrome 137, pseudo-class events carried invalidatedSelectorId: "attribute" and Blink's internal enum name in changedPseudo, such as PseudoHover, so DevTools listed them as an attribute change with no name; Chrome 138 switched to pseudo and hover. Up to Chrome 119, adding a stylesheet with type-selector rules could also write an event with invalidatedSelectorId: "ruleset" and no changed... key. Chrome 120 removed that call; the ruleset string is still defined in the source, and nothing writes it.

No event does not mean no invalidation. A plain .x { } class past the fiftieth subject class or id of its stylesheet, a new stylesheet, positional and universal sibling rules, :has() and the other paths above restyle elements without writing one. To see whether a change cost anything, look at the StyleRecalcInvalidationTracking and UpdateLayoutTree events, not at the absence of this one.

An event does not mean work. It is written before Blink decides whether to schedule anything. A change on a display: none element, or a sibling set on an element with no next sibling, writes the event and nothing after it.

The value named may not have changed, and the event does not say which way it went. Inserting a node beside .sib wrote changedClass: "sib" for an element whose class was untouched. Nothing records whether a class was added or removed. nodeName usually shows the element after the change, but not when the class attribute is emptied: className = '' on class='open x' wrote changedClass: "open" with nodeName still showing class='open x'. One change can also write several events: descendant and sibling sets, old and new id, and a changedAttribute: "class" event on top of the class events.

invalidationSet names a set, not a change or a rule. It is the memory address of Blink's InvalidationSet object, so it only compares within one renderer process. Every change that looks up the same set, on any element, carries the same value: toggling open on two different elements wrote the same address twice. Every set that only covers the element itself is one shared object, so a .selfonly { } class, a #selfid { } id and an li:last-child rule all wrote the same address. The address changes when a second stylesheet adds rules keyed on the same class, id, attribute or pseudo-class, because Blink then merges the two sets into a new object. Adding an unrelated stylesheet left the address as it was, and removing the second sheet brought the old address back.

Join on the address and the node, never the address alone. The shared self-invalidation address also appears on StyleInvalidatorInvalidationTracking events for changes that wrote nothing here: a class past the fiftieth in its stylesheet wrote "Invalidation set invalidates self" with that address and no event of its own, so an address-only join pins it on whichever earlier change used the same set. Positional and universal sibling invalidation write invalidator events with ids that no event here carries. And when two elements queued the same descendant set before one recalculation, the matched events that follow carry the same id, which does not say which element's change reached them.

The element may be one you never wrote. Blink's built-in controls live in shadow trees it manages, and their updates write these events with no stack: INPUT class='pause' and LABEL class='animated-1' were a <video>'s controls, DIV id='placeholder' was an <input>'s placeholder.

Stack positions count from one. lineNumber 29 and columnNumber 38 pointed at line 29, column 38 of the source counting from one. DevTools converts some events' stacks to count from zero before linking them, and this event is not on its list, so a link from the Invalidations section probably lands one line late; that is from reading DevTools' source and was not checked in the UI.

A run of these, each followed by a recalculation, is not in itself thrashing. One change per animation frame, each picked up by that frame's recalculation, draws the same picture and is fine. Thrashing is a recalculation forced inside a script's task by a read of style or layout, and it shows as an UpdateLayoutTree nested inside the script's slice, which needs no invalidation tracking to see. DevTools only warns about a forced reflow when the forced UpdateLayoutTree and Layout slices in one task add up to 30ms or more, so a loop of small forced recalculations gets no warning. In one capture, twenty class toggles each followed by an offsetWidth read wrote twenty of these and twenty recalculations inside the timer's task, together well under a millisecond. Find the pairs by the nesting, and use these events to name the write in each.

DevTools' Invalidations list attributes too much. It attaches every invalidation event to each recalculation in the same frame until the next Paint, not only to the first recalculation after it, and keeps the latest twenty per recalculation while counting all of them. In a loop of forced recalculations the last one lists writes the earlier ones had already handled. This is from DevTools' source, not from the UI.

The category changes what it measures. Recording disabled-by-default-devtools.timeline.invalidationTracking makes style passes longer, by less than two times to more than ten times across the captures behind this manual, and more the further the invalidation sets reach (see UpdateLayoutTree). Use a recording with these events to find out what changed and what it reached, and a recording without them to time it.

{
  "name": "ScheduleStyleInvalidationTracking",
  "cat": "disabled-by-default-devtools.timeline.invalidationTracking",
  "ph": "I",
  "ts": 1108824349,
  "tts": 460859,
  "pid": 8407,
  "tid": 8407,
  "s": "t",
  "args": {
    "data": {
      "changedClass": "jUHzNV",
      "frame": "2EA8810E92C12C680C55B2941251AA98",
      "invalidatedSelectorId": "class",
      "invalidationSet": "0x2764030ccf40",
      "nodeId": 130,
      "nodeName": "DIV class='Backdrop-styles__BackdropStyled-sc-9f7d4825-0 dya-dBg'",
      "stackTrace": [
        {
          "columnNumber": 8015,
          "functionName": "E",
          "lineNumber": 1,
          "scriptId": "46",
          "url": "https://static.files.bbci.co.uk/bbcdotcom/web/20260907-085256-bea8b058c0-web-3.21.0/_next/static/chunks/0y-nyl-getpga.js"
        },
        {
          "columnNumber": 91540,
          "functionName": "oq",
          "lineNumber": 1,
          "scriptId": "46",
          "url": "https://static.files.bbci.co.uk/bbcdotcom/web/20260907-085256-bea8b058c0-web-3.21.0/_next/static/chunks/0y-nyl-getpga.js"
        },
        {
          "columnNumber": 90771,
          "functionName": "oQ",
          "lineNumber": 1,
          "scriptId": "46",
          "url": "https://static.files.bbci.co.uk/bbcdotcom/web/20260907-085256-bea8b058c0-web-3.21.0/_next/static/chunks/0y-nyl-getpga.js"
        },
        "... [112 more items]"
      ]
    }
  }
}

See also StyleInvalidatorInvalidationTracking · StyleRecalcInvalidationTracking · UpdateLayoutTree · ScheduleStyleRecalculation · StyleResolver::ResolveStyle · SelectorStats · LayoutInvalidationTracking

categories

disabled-by-default-devtools.timeline.invalidationTracking

usage

moderate

undeclared args

args.data.stackTrace[].columnNumber, args.data.stackTrace[].functionName, args.data.stackTrace[].lineNumber, args.data.stackTrace[].scriptId, args.data.stackTrace[].url, args.data.changedPseudo

references

v8-debugger.cc, rule_invalidation_data.cc, invalidation_set.cc, capture_source_location.cc, source_location.cc, v8-stack-trace-impl.cc and 1 more

Chrome's count of how it matched each CSS selector against elements during one style recalculation.

A DevTools Performance recording contains this event only with Enable CSS selector stats (slow) turned on, which records disabled-by-default-blink.debug.

Spec

A complete event that Blink's ElementRuleCollector writes on the renderer main thread straight after each UpdateLayoutTree, listing every selector that was tried against an element in that renderer process since the previous such event, with its stylesheet, the number of elements it was tried on, how many of those a Bloom filter ruled out, how many it matched, and the time spent, recorded only under disabled-by-default-blink.debug.

Arguments

Behaviour

With disabled-by-default-blink.debug recorded, Blink swaps its selector-matching loop for an instrumented copy. For each element, it reads the clock around every candidate rule and adds the result to one table per renderer process, keyed by the selector's text and the stylesheet it came from. When a style pass ends, the code that closes UpdateLayoutTree empties that table into this event on the very next line. So you get one SelectorStats a few microseconds after every UpdateLayoutTree, next to it rather than inside it. A same-origin iframe runs its own pass and gets its own event. A style update with nothing to do writes neither event.

The table holds everything matched in that process since the last time it was emptied. That is usually just the pass that ended, but not always, because Blink also matches selectors outside a style pass and that work goes into the next event, whenever it comes. When a @container rule flipped for 200 children, the UpdateLayoutTree for that change showed 4 match attempts, because the children were restyled inside the following Layout. The 200 .cqk attempts turned up in the event after an unrelated style change 400ms later. A getComputedStyle() read of an element inside a display: none subtree wrote no events, and its match turned up in the next pass's event in the same way. The table is shared by every document in the process: the same read made inside a same-origin iframe turned up in the parent page's next event. If nothing was matched since the last event, it is written with empty args, which a pass with an elementCount of 0 does not guarantee.

A selector only gets a row if it was actually tried. Blink files every selector under its rightmost part (an id, a class, an attribute name, a tag, one of a few pseudo-classes such as :link and :focus, or "universal" when the rightmost part has none of these) and tries an element against only the selectors filed under that element's own id, classes, attributes and tag, the pseudo-classes it is in, and the universal ones. match_attempts is the number of elements a selector was tried on after that filtering. On a test page, .card:has(.hot) was tried twice, once for each .card, a selector for a class nobody used never appeared, and .list * was tried on all 814 elements the pass restyled. Each selector in a comma-separated list gets its own row. Two rules with the same selector text in the same stylesheet share a row.

fast_reject_count counts attempts rejected before the full selector check ran. A Bloom filter is a small bit set that can say for certain that something is absent. Blink keeps one for the tags, ids, classes and attribute names of the ancestors of the element being matched, and one for the element's own classes and attributes. .nope .item was rejected this way on all 400 .item elements because no ancestor had the class nope. match_count is the number of attempts that matched, including any @container condition the rule sits in. elapsed (us) is the total time of all attempts in microseconds, measured around the loop body for that selector: the filter check, the selector check, any @container condition, and recording the match. Building the style from the matched rules, invalidation and the layout tree are outside it.

style_sheet_id has the form style-sheet-<process id>-<n>, the id the DevTools CSS panel uses for that stylesheet. Rules from Chrome's built-in stylesheet appear as ua-style-sheet.

The event's own dur is the time spent writing the table into the trace and clearing it, from 1us up to most of a millisecond on a large page. It is not the matching time.

Derivations

Which selectors the Bloom filters cannot help with. match_attempts - match_count is the number of non-matches, and fast_reject_count is how many of those were rejected cheaply. The rest went through the full selector check before failing. DevTools shows 1 - fast_reject_count / (match_attempts - match_count) as "% of slow-path non-matches". A selector that is tried on many elements, matches few and scores near 100% is doing full checks for nothing. On a test page .item:nth-child(2n+1) scored 100%, because it names no ancestor and its pseudo-class gives the filters nothing to test, while the longer .nope .item scored 0%. The number of attempts shows where that work comes from: it depends on the selector's rightmost part, not on how long the selector is. On Wikipedia's CSS article the selectors with the most attempts all ended in *, :first-child, :last-child or :not(...), which files them as universal, and each was tried on nearly every element the load restyled, however long its left-hand side.

Traps

The recording makes style work several times slower, and the time column includes the cost of measuring. A forced full re-match (a class toggle on <html> with a html.zz * rule, forced with getComputedStyle) took 11.4ms on a 9,000-element test page with nothing recording and the same with DevTools' timeline categories, 77ms with disabled-by-default-blink.debug, and 90ms with both categories DevTools' setting records. On Wikipedia's CSS article it went from 11ms to 293ms and 305ms, and on a small 534-element page from 0.6ms to 3.7ms and 4.1ms. These are one machine, headless, one Chrome build. The page's own performance.now() grew by the same amount as the trace durations, so this is real main-thread work that the recording adds. Do not trust the duration of any style event in a trace recorded with this category.

elapsed (us) ranks selectors within one recording and is not a cost. Every attempt is timed between two clock readings, so each carries a fixed measuring cost of a clock read and the loop around it, about 20ns on the test machine. A selector that the filter rejected on every one of 11,488 attempts averaged 38ns per attempt. Rows with many cheap attempts are inflated most. On Wikipedia the column for one forced pass added up to more than the whole pass took with nothing recording; on the test page it came to about half. Nobody has checked that the order it gives matches the order without instrumentation.

Single values of elapsed (us) are noise. The clock is read in whole microseconds, so an attempt shorter than a microsecond reads 0, or 1 when a microsecond tick falls inside it. Over thousands of attempts those zeros and ones average out to a usable total. A row with a handful of attempts means little: one attempt of .item.one read 6us.

An event can carry work from before its pass, and from another document. The table is emptied only when a style pass ends, and there is one per renderer process. Selectors matched during Layout for container queries, on demand for getComputedStyle() inside display: none, or in a same-origin iframe outside its own pass, are reported with whichever pass the process runs next, which may have nothing to do with them. A pass with an elementCount of 1 that carries hundreds of attempts is the usual sign.

DevTools can attach the statistics to the wrong recalculation. Its handler attaches each SelectorStats to the last UpdateLayoutTree it read, from any thread or process. When an out-of-process iframe restyles at the same time as the page, the frame's statistics can appear under the page's recalculation and the other way round. When you work from the raw trace, pair each event with the UpdateLayoutTree just before it on the same pid and tid.

ua-style-sheet on one of your own selectors is Blink checking a stylesheet change, not a built-in rule. When a stylesheet is added or its rules change, Blink walks the elements and asks, for each, whether any of the changed rules could apply to it. That check runs without the context Blink uses to find the rule's stylesheet, so the lookup fails and the row is filed under ua-style-sheet. It stops at the first rule that matches and records nothing for that element, so these rows always show 0 matches and count only the elements where nothing matched. They appear on the pass after a stylesheet loads, is inserted, or is edited through the CSSOM.

Two stylesheets with the same contents are counted as one. Blink shares the parsed contents of a stylesheet loaded twice from the same URL, and the lookup returns one of the two. When a test page linked its stylesheet a second time, the whole pass was reported under the new sheet's id with both sheets' attempts added together, and nothing under the original. After one of them was edited through the CSSOM they got separate rows again. The ids are only linkable while DevTools is still attached to the page that created them, before it reloads. In a trace loaded from a file the Style sheet column cannot link them.

DevTools' setting records invalidation tracking as well. "Enable CSS selector stats (slow)" adds disabled-by-default-blink.debug and disabled-by-default-devtools.timeline.invalidationTracking. The tab's Invalidation count column is not in this event. DevTools works it out from the invalidation-tracking events and, for subtree invalidations, by counting descendants in the page's DOM as it is now, not as it was when the trace was recorded. Selecting a single recalculation always shows the Selector stats tab. Selecting a range totals it only when the viewer's own setting is on. The event itself is hidden in the flame chart.

The tab's explanation of slow-path non-matches is not quite right. Its tooltip blames selector complexity. The filters only know the tags, ids, classes and attribute names of the element and its ancestors, so a short selector that names no ancestor, such as .item:nth-child(2n+1), can never be ruled out early, while a long chain of ancestor classes can be rejected at once. The column also counts every attempt that neither matched nor was filtered out for any other reason: a one-class selector inside a @container block whose condition was false scored 100%, because the selector matched and the container condition did not.

The events are large. One Wikipedia load wrote 64 of them, about 1.7MB of JSON, with over 2,000 distinct selector and stylesheet pairs.

See also UpdateLayoutTree · StyleResolver::ResolveStyle · StyleInvalidatorInvalidationTracking · StyleRecalcInvalidationTracking · Layout · ParseAuthorStyleSheet

categories

disabled-by-default-blink.debug

references

element_rule_collector.cc

Chrome's style invalidator marked an element to have its style recalculated.

A DevTools Performance recording contains this event only with Enable CSS selector stats (slow) or Invalidation tracking turned on, which records disabled-by-default-devtools.timeline.invalidationTracking.

Spec

Blink records one step of applying an invalidation set: an element a set caught for style recalculation, or a node it reached that carries pending sets, written by PendingInvalidations when the DOM change is made and by StyleInvalidator at the start of the next style update, on the renderer's main thread.

Arguments

Observed 170,721 times on 166 of 300 sites.

Behaviour

When you change a class, id or attribute, Blink does not restyle the page. It looks up the invalidation set for what changed: a precomputed list of the classes, ids, tag names and attributes that rules keyed on that change can reach. For .on .x .y the set for class on holds y, the last compound. Blink schedules the set on the element that changed, which writes ScheduleStyleInvalidationTracking, and applies it later. This event records the applying.

It is written at two moments. The first is at the DOM change itself, in the same task. If a set says the element itself needs a new style, Blink marks it there and then and writes the reason Invalidation set invalidates self; if the set covers everything below the element, as a rule like .on * does, it writes Invalidation set invalidates subtree and marks the whole subtree. Each sits between the ScheduleStyleInvalidationTracking and the StyleRecalcInvalidationTracking of the same change, outside any UpdateLayoutTree.

The second is during the next style update. Inside UpdateLayoutTree, after stylesheet, media query and font work and before any style is recalculated, Blink walks the DOM and applies the pending sets. With the blink category recorded this walk is the Document::updateStyleInvalidationIfNeeded slice, and it closes before Document::updateStyle opens. The walk writes Element has pending invalidation list on each node where descendant sets were scheduled, then one event for every element a set catches, normally followed by a StyleRecalcInvalidationTracking for the same node. Sets for sibling rules such as .a + .b are applied without a pending-list event. If script forced the update, all of this happens inside the script's task.

A caught element is reported with the first feature that matched, tested in a fixed order: whole subtree, tag name, id, class, custom pseudo-element name, attribute, part, and a tree-counting dependency (sibling-index() or sibling-count()). That gives the reasons Invalidation set matched tagName, matched id, matched class, matched custom pseudo element name, matched attribute, matched part and Invalidation set invalidates tree-counting. selectorPart is the tag, id, class, attribute or custom pseudo-element name that matched; it is empty for self, subtree, part and tree-counting, and missing on the pending-list event. A reason string Invalidate custom pseudo-element is defined in Chromium but nothing writes it. Blink stops at the first descendant set that catches an element, but tests every sibling set, so one element can get more than one event.

invalidationList is the set that matched, or on the pending-list event every set scheduled on that node. Each entry is the whole set: its id, the flags that are true, and every class, id, tag name, attribute and custom pseudo-element name it holds, not only the one that caught this element. id is the set's address in memory, written by the same function as invalidationSet on ScheduleStyleInvalidationTracking, so the two are equal for the same set.

selectors and selectorCount come from a map Blink builds, only while tracing, from each feature in each invalidation set back to the selectors that put it there. Blink builds it when disabled-by-default-devtools.timeline.invalidationTracking or disabled-by-default-blink.debug is recorded, on the first invalidation after recording starts, so a recording started after the page loaded gets it too. Only the matched reasons and invalidates subtree look the map up; invalidates self, invalidates tree-counting and the pending-list event never carry the two fields. A lookup can also come back empty: rules written inside another rule with CSS nesting are never entered in the map, so an element caught by one gets its event without selectors.

So the number you see follows the reach of invalidation sets: one event per element caught, plus one per node that carried descendant sets. Elements the walk skips get nothing: everything below an element already marked for a whole-subtree restyle, and the children of an element with no computed style, such as one inside display: none.

Derivations

Which change restyled which elements. ScheduleStyleInvalidationTracking carries the script stack and the class, id or attribute that changed, and its invalidationSet equals the invalidationList id on the events the walk writes for that set. The id names a set, not a change: every element that got class on before the same style update scheduled the same set, so two functions each adding on to a different element produce two schedule events with two stacks and one id on every walk event. To split them, use the tree. The walk writes the pending-list event on the element that changed, with the schedule event's nodeId, and the matched events for that element's descendants follow it. Grouping those gives, for one classList.add, the elements it pulled into the restyle and the feature that pulled each one in, which the recalculation's elementCount only gives as a total. It stops working when one changed element is inside another that scheduled the same set, since either change would have caught the inner elements, and for the sets Blink applies without a schedule event (see the traps).

Which selectors cause broad restyles. Invalidation set invalidates subtree with its selectors names the rules that turn one class change into a restyle of everything below the element, such as .on * or a descendant rule ending in a pseudo-element. Counting matched events by selectorPart and selectors shows which feature catches the most elements; a selector whose last compound is loose, like .on .x .y, catches every .y under the element whether or not it is inside a .x, and tightening that compound is the fix. Use it to find what was caught, not what it cost (see the traps).

Traps

The selectors are not the rule that matched. selectors lists every selector that contributed the matched feature to that invalidation set, and nothing checks them against the element. With .on .x, .on span.x and .on .x .y on a page, adding on reported .on span.x for a div.x, and .on .x .y for a .y that was inside no .x at all. They tell you why Blink caught the element, not which rule now styles it. Each entry is Blink's own serialisation of one selector from the rule's selector list, not your source text: .q1>.q2 comes back as .q1 > .q2, and from .a, .b .c you get only .b .c. The order of the entries means nothing.

The feature reported is the first that matched, not the most specific. Tag names are tested before ids, ids before classes, classes before attributes. On one real page a div class='frb-button' was reported as matched tagName div, with twelve .mw-spinner-container > div:nth-child(n) selectors, though the same set also held its class frb-button.

There is no stack on this event. Neither of its builders asks for one, even when the event is written inside your script. For the script, read the ScheduleStyleInvalidationTracking before it, which has the stack of the change, or the StyleRecalcInvalidationTracking after it, which has a stack only when script was running at that moment: at the change itself, or in a recalculation that script forced.

Selector detail is missing on three reasons by design, and on nested CSS. invalidates self, invalidates tree-counting and Element has pending invalidation list never carry selectors. The other reasons carry them with invalidation tracking alone; the slow "Enable CSS selector stats" setting adds nothing to this event. But a rule written inside another rule with CSS nesting, such as .nest { & .nx {} }, is never entered in Blink's selector map, so the element it catches gets an event with no selectors.

style_sheet_id is not a file. It is style-sheet-<process>-<n>, the same string the DevTools protocol uses for a stylesheet, with n given out in the order sheets are first asked about, so the same sheet can have a different id in another recording. Nothing else in a trace file maps it to a URL; SelectorStats carries the same ids. A rule in a file pulled in with @import is reported under the sheet that imports it. ua-style-sheet means the browser's own stylesheet, and also any sheet that is not in the caught element's own tree scope: a page rule .pon ::part(p) that caught a span inside a shadow root, and a shadow root's ::slotted(.sl) rule that caught a span in the page, were both reported as ua-style-sheet.

id is an address, and it names a set, not an invalidation. Every element that schedules the same set gets the same id, and the set gets a new address when stylesheets change. Some sets have no ScheduleStyleInvalidationTracking to match: the shared set Blink uses for classes and ids that only ever style the element that has them, once a stylesheet has about fifty of those (Blink then keeps their names in a Bloom filter, which can also produce invalidates self for a class that no rule uses), the sets for :nth-child() and similar selectors, the tree-counting set, which Blink schedules on the parent when children are added or removed, and the descendant part of a sibling rule: for .s2 + .t2 .u2 the event on .u2 carries an id that no schedule event has. Blink always schedules the :nth-* sets and the tree-counting set together, so a child added or removed can bring events from either kind of rule.

An event is not a restyle. The pending-list event marks nothing. For a sibling rule with a descendant, like .s2 + .t2 .u2, the .t2 gets a matched class event only so Blink can look below it, and is not marked. One element can be caught by two sets and get two events and one recalculation mark, and an element in a slot can be reached twice and get two of each. The mark can be refused after the event is written: when the element's parent has no computed style Blink writes this event and then skips the element, and no StyleRecalcInvalidationTracking follows. The reverse happens too: an element whose container query depends on sibling-index() or sibling-count() is marked with no event of this name. Count restyles with elementCount or StyleResolver::ResolveStyle, not with this.

Two fields DevTools declares are never here. trace_engine types this event with subtree and extraData. Those belong to StyleRecalcInvalidationTracking, which is where the subtree flag lives: DevTools' SelectorStatsHandler says so in a comment, and pairs an event that has selectors with the next StyleRecalcInvalidationTracking for the same node that has subtree set. When the mark is refused that partner never comes, and the subtree invalidation is counted as a single node.

What DevTools does with it. Recalculate style shows an "Invalidations" section, grouped by reason, keeping only the last 20 per recalculation, with node links and no selectors. The selectors are used only for the "Invalidation count" column of selector stats. Two effects from reading its source, not checked in the panel: invalidations waiting for a recalculation are also given to a second recalculation in the same frame, and a subtree invalidation written at the DOM change is counted against the recalculation before it.

Recording it changes what it measures. The category makes restyle-heavy style passes run many times longer (see UpdateLayoutTree), and the first invalidation after recording starts also has Blink walk the page's active stylesheets again to build the selector map. Use a recording with it to find out what was caught and why, and a recording without it for how long style took.

{
  "name": "StyleInvalidatorInvalidationTracking",
  "cat": "disabled-by-default-devtools.timeline.invalidationTracking",
  "ph": "I",
  "ts": 1235492157,
  "tts": 207175,
  "pid": 10309,
  "tid": 10309,
  "s": "t",
  "args": {
    "data": {
      "frame": "614FC5655E48B642B0235ABCA128B0C6",
      "invalidationList": [
        {
          "attributes": ["collapsed", "active", "fixed", "position", "animatable"],
          "classes": ["hide-collapsed-panel", "devsite-concierge-panel", "devsite-concierge-panel-chat-input", "devsite-sidebar", "devsite-book-nav-toggle", "devsite-floating-action-buttons", "mobile-view-not-enabled", "devsite-concierge-menu-icon", "... [13 more items]"],
          "id": "0x109400913c00",
          "ids": ["gc-wrapper"],
          "tagNames": ["devsite-header", "devsite-footer-promos", "devsite-concierge", "devsite-panel", "google-codelab", "devsite-footer-linkboxes", "devsite-book-nav", "devsite-concierge-ai-panel", "... [3 more items]"]
        }
      ],
      "nodeId": 22,
      "nodeName": "SECTION class='devsite-wrapper'",
      "reason": "Invalidation set matched class",
      "selectorCount": 1,
      "selectorPart": "devsite-wrapper",
      "selectors": [
        {
          "selector": "body[ready] .devsite-wrapper",
          "style_sheet_id": "style-sheet-10309-1"
        }
      ]
    }
  }
}

See also ScheduleStyleInvalidationTracking · StyleRecalcInvalidationTracking · UpdateLayoutTree · SelectorStats · StyleResolver::ResolveStyle · LayoutInvalidationTracking

categories

disabled-by-default-devtools.timeline.invalidationTracking

usage

high

undeclared args

args.data.invalidationList[].allDescendantsMightBeInvalid, args.data.selectorCount, args.data.selectorPart, args.data.invalidationList[].tagNames[], args.data.invalidationList[].customPseudoNames[], args.data.invalidationList[].treeBoundaryCrossing, args.data.invalidationList[].attributes[], args.data.invalidationList[].ids[] and 3 more

references

invalidation_set.cc, style_invalidator.cc, invalidation_set_to_selector_map.h, identifiers_factory.cc, inspector_trace_events.h

Chrome records a request to recalculate one element's style, with the element and the reason.

A DevTools Performance recording contains this event only with Enable CSS selector stats (slow) or Invalidation tracking turned on, which records disabled-by-default-devtools.timeline.invalidationTracking.

Spec

Blink writes one instant event on the renderer's main thread for each call to Node::SetNeedsStyleRecalc, and for each node inserted under an element that already has a style, recording the node, whether the request covers the node alone or the node and every descendant, and a reason string.

Arguments

Observed 636,276 times on 182 of 300 sites.

Behaviour

Blink writes this event each time something asks for a node's style to be recalculated, and it writes it before it looks at what the node is already marked with. So one event is one request, not one change of state: five writes to the same element's style in one task wrote five events and cost one recalculated element, and a request on an element that was already marked for a bigger recalculation still wrote one. The only checks that come first are that the node is in an active document and that its parent already has a computed style. That second check is why nothing is written for nodes inside display: none, for nodes inserted during the initial parse, before the first style recalculation, and for the nodes inside a fragment that is inserted whole, which writes one event for its root. A second call site, for inserted nodes, behaves the same way and always writes the reason Node was inserted into tree. The node can be a text node, which shows up as #text.

Some callers skip the call when the node is already dirty, so not every conceivable request is recorded. A CSS animation marks an element only if it is clean, which comes out as one Animation event per animating element per frame, and none for an element that script had already marked before the tick. And once an invalidation set has marked an element for a subtree recalculation, Blink stops matching invalidation sets below it, so such a subtree invalidation is one event on its root however large the subtree is. Other callers do not stop: changing lang writes a subtree: true event for every element under it.

reason is one of 52 fixed strings in Blink's style_change_reason.cc. The ones you meet most: Related style rule means an invalidation set matched (Blink's per-selector lists of which class, id or attribute changes can affect which elements), either at once, for the element whose class or attribute changed, or later, for its descendants, when the style update walks the pending sets. Inline CSS style declaration was mutated is a write through el.style. Style rule change means a stylesheet was added or changed and Blink marked each element one of its rules could affect, one event per element, which is why CSS that arrives after the first style recalculation writes these in bulk. Attribute is a presentation attribute such as hidden or lang, or an attribute the element's style reads with attr(); an attribute used in a selector, such as [data-state], arrives as Related style rule. PseudoClass is a user-action pseudo-class on an element whose own style depends on it, a dir=auto change, or a lang change. Some changes are handled as a single subtree request on <html>, which is how Blink asks for every element to be recalculated: registering a custom property with CSS.registerProperty wrote one PropertyRegistration event, and adding a color-scheme meta tag wrote one PlatformColorChange event. Language, Zoom, Printing and Inspector work the same way.

subtree is true when the request was for the node and all of its descendants in the flat tree (the DOM with shadow trees and slotted children in place), and false for everything else. Under a subtree request Blink recalculates every descendant that has a style, and it does not stop early when a style comes out unchanged, as it does for a request on a single element. On a test page with 1500 elements, adding a class to body for the rule .on * { visibility: visible }, which changed nothing because everything was already visible, wrote one event and recomputed 1505 styles; the same toggle for a rule that matched only body recomputed one. Subtrees Blink never styles are left out: the children of a display: none element and of a content-visibility: hidden element were not recalculated.

extraData is written on every event and is an empty string unless there is something to add. For Attribute it is the attribute's name. For PseudoClass from a user action it is the pseudo-class, such as :hover, :active, :focus, :focus-visible or :focus-within. PseudoClass events from lang and dir=auto changes have it empty, and most pseudo-class changes never use PseudoClass at all: :checked, :disabled on a checkbox, or :hover on an ancestor in .menu:hover .item, reaches the affected element through an invalidation set and arrives as Related style rule.

stackTrace is present only if V8 was running JavaScript at the moment of the request, so it marks the requests that script made synchronously: style and attribute writes, class toggles that invalidate the element itself or its whole subtree, appendChild, setting lang. Parser insertions, real mouse and keyboard input and animation ticks carry none. Requests Blink defers to the style update are written inside that UpdateLayoutTree, not before it, and carry a stack only when script forced the update, even when script caused them: the same .on .x class toggle wrote stackless Related style rule events for its descendants when they were resolved in the next frame, and events whose top frame was the offsetHeight read when that read forced the update in the same task. A <style> element appended by script behaves the same way, because Blink applies new rules during the style update: its Style rule change events had no stack, unless a read forced the update.

Derivations