{"id":13527086,"url":"https://github.com/w3c/performance-timeline","last_synced_at":"2025-04-05T00:07:45.073Z","repository":{"id":21199548,"uuid":"24511341","full_name":"w3c/performance-timeline","owner":"w3c","description":"Performance Timeline","archived":false,"fork":false,"pushed_at":"2025-02-13T03:58:58.000Z","size":369,"stargazers_count":113,"open_issues_count":15,"forks_count":27,"subscribers_count":68,"default_branch":"gh-pages","last_synced_at":"2025-03-28T23:06:17.849Z","etag":null,"topics":["api","performance","performance-metrics","specification","web","web-application","webapp"],"latest_commit_sha":null,"homepage":"https://w3c.github.io/performance-timeline/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/w3c.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-26T18:48:58.000Z","updated_at":"2025-02-28T01:55:09.000Z","dependencies_parsed_at":"2024-01-13T21:39:29.367Z","dependency_job_id":"13d894d5-d859-4da4-8c0a-ec5339b8e51c","html_url":"https://github.com/w3c/performance-timeline","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3c%2Fperformance-timeline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3c%2Fperformance-timeline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3c%2Fperformance-timeline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3c%2Fperformance-timeline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w3c","download_url":"https://codeload.github.com/w3c/performance-timeline/tar.gz/refs/heads/gh-pages","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","performance","performance-metrics","specification","web","web-application","webapp"],"created_at":"2024-08-01T06:01:40.636Z","updated_at":"2025-04-05T00:07:45.059Z","avatar_url":"https://github.com/w3c.png","language":"HTML","readme":"Performance Timeline\n====================\n\n### Overview\n\nThe PerformanceTimeline specification defines ways in which web developers can measure specific aspects of their web applications in order to make them faster.\nIt introduces two main ways to obtain these measurements: via getter methods from the [Performance](https://w3c.github.io/hr-time/#sec-performance) interface and via the PerformanceObserver interface.\nThe latter is the recommended way to reduce the performance impact of querying these measurements.\n\n### PerformanceEntry\n\nA PerformanceEntry object can host performance data of a certain metric.\nA PerformanceEntry has 4 attributes: `name`, `entryType`, `startTime`, and `duration`.\nThis specification does not define concrete PerformanceEntry objects.\nExamples of specifications that define new concrete types of PerformanceEntry objects are [Paint Timing](https://github.com/w3c/paint-timing), [User Timing](https://github.com/w3c/user-timing), [Resource Timing](https://github.com/w3c/resource-timing), and [Navigation Timing](https://github.com/w3c/navigation-timing/).\n\n### Performance getters\n\nThe [Performance](https://w3c.github.io/hr-time/#sec-performance) interface is augmented with three new methods that can return a list of PerformanceEntry objects:\n\n* `getEntries()`: returns all of the entries available to the [Performance](https://w3c.github.io/hr-time/#sec-performance) object.\n* `getEntriesByType(type)`: returns all of the entries available to the [Performance](https://w3c.github.io/hr-time/#sec-performance) object whose `entryType` matches *type*.\n* `getEntriesByName(name, type)`: returns all of the entries available to the [Performance](https://w3c.github.io/hr-time/#sec-performance) object whose `name` matches *name*.\nIf the optional parameter *type* is specified, it only returns entries whose `entryType` matches *type*.\n\n#### Using the getters in JavaScript\n\nThe following example shows how `getEntriesByName()` could be used to obtain the first paint information:\n\n```javascript\n// Returns the FirstContentfulPaint entry, or null if it does not exist.\nfunction getFirstContentfulPaint() {\n  // We want the entry whose name is \"first-contentful-paint\" and whose entryType is \"paint\".\n  // The getter methods all return arrays of entries.\n  const list = performance.getEntriesByName(\"first-contentful-paint\", \"paint\");\n  // If we found the entry, then our list should actually be of length 1,\n  // so return the first entry in the list.\n  if (list.length \u003e 0)\n    return list[0];\n  // Otherwise, the entry is not there, so return null.\n  else\n    return null;\n}\n```\n\n### PerformanceObserver\n\nA PerformanceObserver object can notified of new PerformanceEntry objects, according to their `entryType` value.\nThe constructor of the object must receive a callback, which will be ran whenever the user agent is dispatching new entries whose `entryType` value match one of the ones being observed by the observer.\nThis callback is not run once per PerformanceEntry nor immediately upon creation of a PerformanceEntry.\nInstead, entries are 'queued' at the PerformanceObserver, and the user agent can execute the callback later.\nWhen the callback is executed, all queued entries are passed onto the function, and the queue for the PerformanceObserver is reset.\nThe PerformanceObserver initially does not observer anything: the `observe()` method must be called to specify what kind of PerformanceEntry objects are to be observed.\nThe `observe()` method can be called with either an 'entryTypes' array or with a single 'type' string, as detailed below.\nThose modes cannot be mixed, or an exception will be thrown.\n\n#### PerformanceObserverCallback\n\nThe callback passed onto `PerformanceObserver` upon construction is a `PerformanceObserverCallback`. It is a void callback with the following parameters:\n\n* `entries`: a `PerformanceObserverEntryList` object containing the list of entries being dispatched in the callback.\n* `observer`: the `PerformanceObserver` object that is receiving the above entries.\n* `hasDroppedEntries`: a `boolean` indicating whether `observer` is currently observing an `entryType` for which at least one entry has been lost due to the corresponding buffer being full. See the buffered flag [section](#buffered-flag).\n\n#### `supportedEntryTypes`\n\nThe static `PerformanceObserver.supportedEntryTypes` returns an array of the `entryType` values which the user agent supports, sorted in alphabetical order.\nIt can be used to detect support for specific types.\n\n#### `observe(entryTypes)`\n\nIn this case, the PerformanceObserver can specify various `entryTypes` values with a single call to `observe()`.\nHowever, no additional parameters are allowed in this case.\nMultiple `observe()` calls will override the kinds of objects being observed.\nExample of a call: `observer.observe({entryTypes: ['resource', 'navigation']})`.\n\n#### `observe(type)`\n\nIn this case, the PerformanceObserver can only specify a single type per call to the `observe()` method.\nAdditional parameters are allowed in this case.\nMultiple `observe()` calls will stack, unless a call to observer the same `type` has been made in the past, in which case it will override.\nExample of a call: `observer.observe({type: \"mark\"})`.\n\n#### `buffered` flag\n\nOne parameter that can be used with `observe(type)` is defined in this specification: the `buffered` flag, which is unset by default.\nWhen this flag is set, the user agent dispatches records that it has buffered prior to the PerformanceObserver's creation, and thus they are received in the first callback after this `observe()` call occurs.\nThis enables web developers to register PerformanceObservers when it is convenient to do so without missing out on entries dispatched early on during the page load.\nExample of a call using this flag: `observer.observe({type: \"measure\", buffered: true})`.\n\nEach `entryType` has special characteristics around buffering, described in the [registry](https://w3c.github.io/timing-entrytypes-registry/#registry). In particular, note that there are limits to the numbers of entries of each type that are buffered. When the buffer of an `entryType` becomes full, no new entries are buffered. A PerformanceObserver may query whether an entry was dropped (not buffered) due to the buffer being full via the `hasDroppedEntry` parameter of its callback.\n\n#### `disconnect()`\n\nThis method can be called when the PerformanceObserver should no longer be notified of entries any more.\n\n#### `takeRecords()`\n\nThis method returns a list of entries that have been queued for the PerformanceObserver but for which the callback has not yet run.\nThe queue of entries is also emptied for the PerformanceObserver.\nIt can be used in tandem with `disconnect()` to ensure that all entries up to a specific point in time are processed.\n\n#### Using the PerformanceObserver\n\nThe following example logs all [User Timing](https://github.com/w3c/user-timing), [Resource Timing](https://github.com/w3c/resource-timing) entries by using a PerformanceObserver which observers marks and measures.\n\n```javascript\n// Helper to log a single entry.\nfunction logEntry(entry =\u003e {\n  const objDict = {\n    \"entry type\":, entry.entryType,\n    \"name\": entry.name,\n    \"start time\":, entry.startTime,\n    \"duration\": entry.duration\n  };\n  console.log(objDict);\n});\n\nconst userTimingObserver = new PerformanceObserver(list =\u003e {\n  list.getEntries().forEach(entry =\u003e {\n    logEntry(entry);\n  });\n});\n\n// Call to log all previous and future User Timing entries.\nfunction logUserTiming() {\n  if (!PerformanceObserver.supportedEntryTypes.includes(\"mark\")) {\n    console.log(\"Marks are not observable\");\n  } else {\n    userTimingObserver.observe({type: \"mark\", buffered: true});\n  }\n  if (!PerformanceObserver.supportedEntryTypes.includes(\"measure\")) {\n    console.log(\"Measures are not observable\");\n  } else {\n    userTimingObserver.observe({type: \"measure\", buffered: true});\n  }\n}\n\n// Call to stop logging entries.\nfunction stopLoggingUserTiming() {\n  userTimingObserver.disconnect();\n}\n\n// Call to force logging queued entries immediately.\nfunction flushLog() {\n  userTimingObserver.takeRecords().forEach(entry =\u003e {\n    logEntry(entry);\n  });\n}\n```\n","funding_links":[],"categories":["HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3c%2Fperformance-timeline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw3c%2Fperformance-timeline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3c%2Fperformance-timeline/lists"}