Document PerformanceObserver's droppedEntriesCount

files/en-us/web/api/performanceobserver/performanceobserver/index.md

@@ -24,7 +24,13 @@ new PerformanceObserver(callback)
 ### Parameters
 
 - `callback`
-  - : A `PerformanceObserverCallback` callback that will be invoked when observed performance events are recorded. When the callback is invoked, its first parameter is a {{domxref("PerformanceObserverEntryList","list of performance observer entries", '', 'true')}} and the second parameter is the {{domxref("PerformanceObserver","observer")}} object.
+  - : A `PerformanceObserverCallback` callback that will be invoked when observed performance events are recorded. When the callback is invoked, the following parameters are available:
+    - `entries`
+      - : The {{domxref("PerformanceObserverEntryList","list of performance observer entries", '', 'true')}}.
+    - `observer`
+      - : The {{domxref("PerformanceObserver","observer")}} object that is receiving the above entries.
+    - `droppedEntriesCount` {{optional_inline}}
+      - : The number of buffered entries which got dropped from the buffer due to the buffer being full. See the [`buffered`](/en-US/docs/Web/API/PerformanceObserver/observe#parameters) flag.
 
 ### Return value
 
@@ -52,6 +58,26 @@ const observer = new PerformanceObserver(perfObserver);
 observer.observe({ entryTypes: ["measure", "mark"] });
 ```
 
+### Dropped buffer entries
+
+You can use {{domxref("PerformanceObserver")}} with a `buffered` flag to listen to past performance entries.
+There is a buffer size limit, though. The performance observer callback contains an optional `droppedEntriesCount` parameter that informs you about the amount of lost entries due to the buffer storage being full.
+
+```js
+function perfObserver(list, observer, droppedEntriesCount) {
+  list.getEntries().forEach((entry) => {
+    // do something with the entries
+  });
+  if (droppedEntriesCount > 0) {
+    console.warn(`${droppedEntriesCount} entries got dropped due to the buffer being full.`);
+  }
+}
+const observer = new PerformanceObserver(perfObserver);
+observer.observe({ type: "resource", buffered: true });
+```
+
+Usually, there are a lot of resource timing entries, and for these entries specifically, you can also set a larger buffer using {{domxref("performance.setResourceTimingBufferSize()")}} and watch for the {{domxref("Performance/resourcetimingbufferfull_event", "resourcetimingbufferfull")}} event.
+
 ## Specifications
 
 {{Specifications}}