@grafana/faro-instrumentation-performance-timeline
v1.11.0
Published
Faro instrumentation to capture Browser Performance Timeline data.
Downloads
1,400
Readme
@grafana/instrumentation-performance-timeline
Faro instrumentation to capture Performance Timeline data.
❗️Warning: this package is experimental and may be subject to frequent and breaking changes. Use at your own risk.❗️
Installation
import { PerformanceTimelineInstrumentation } from '@grafana/faro-instrumentation-performance-timeline';
import { getWebInstrumentations, initializeFaro } from '@grafana/faro-react';
initializeFaro({
// ...
instrumentations: [
// Load the default Web instrumentations
...getWebInstrumentations(),
new PerformanceTimelineInstrumentation(),
],
});
Usage
What entry types can I capture?
The FaroPerformanceTimeline instrumentation is able to track all entry types as defined by PerformanceEntry: entryType property.
For each Performance Entry it sends an event named faro.performanceEntry
By default we track entries of type navigation and resource. These entry types allow you to track the load timings of the assets of your page or spa.
You can specify which entry types to track via the observeEntryTypes
array in the config.
This will also overwrite the default entry types. Since the usage of the default entry types is so
common, we provide them as a constant (DEFAULT_PERFORMANCE_TIMELINE_ENTRY_TYPES
) you can add
alongside your owen entries.
Example of how to specify entry types to track
Alongside the default entry types the example adds entries to track PerformanceEventTiming, mark and PerformanceMeasure.
new PerformanceTimelineInstrumentation({
observeEntryTypes: [
...DEFAULT_PERFORMANCE_TIMELINE_ENTRY_TYPES,
{ type: 'event', buffered: true },
{ type: 'mark', buffered: true },
{ type: 'measure', , buffered: true },
],
}),
Additionally you can add all config properties a respective PerformanceEntry provides.
For example if you want to change the duration threshold for PerformanceEventTiming
.
{ type: 'event', durationThreshold: 96, buffered: true },
Note: Browser support for entry types differs. In the case that one of your specified entries is not support Faro will log a message and does not register to track these entries.
How can I skip entries?
By URL
It is possible to skip capturing entries by URL. This is can be archived by specifying respective
URLs in the ignoredURLs
array.
By default Faro skips urls defined by the transports. Usually these are the receiver URLs.
Example of how to specify skip URLs
new PerformanceTimelineInstrumentation({
ignoredURLs: [...]
}),
Note:
This overwrites the default skip URLs.
By using the beforeEmit hook
You can use the beforeEmit hook to skip entries simply by returning false
for the desired entry.
For more information see Mutating or filtering performance entries
below.
Example: Skip back/forward navigation and page reloads to remove non human visible navigation
new PerformanceTimelineInstrumentation({
beforeEmit: (performanceEntryJSON) => {
const entryType = performanceEntryJSON.type;
const type = performanceEntryJSON.type;
if (entryType === 'navigation' && ['reload', 'back_forward'].includes(type)) {
return false;
}
return performanceEntryJSON;
},
});
Mutating or filtering performance entries
The Performance Timeline emits a lot of data which quickly adds up. Often users mutate Performance Entries to trim down the payload size of an entry, to further remove noise or if they need a filter which can not be achieved with the above config options.
Therefore we provide the beforeEmit
hook.
This hook triggers after all the other options mentioned above i. e. skipping entries by url.
The beforeEmit
hook receives the json representation of a performance entry as a parameter and
either returns the performance entry which shall be send to the backend or false
in case the
entire entry should be dropped.
beforeEmit: (performanceEntry: performanceEntryJSON: any) => Record<string, any> | false;
Note:
The JSON representation of the performance entry is the object returned by calling the toJSON()
function of the respective PerformanceEntry.
Config Options
observeEntryTypes: ObserveEntries[]
: The Performance Entry types which should be observed.resourceTimingBufferSize: number
: The size of the browser's resource timing buffer which stores the "resource" performance entries.maxResourceTimingBufferSize: number
: If resource buffer size is full, set this as the new.ignoredUrls?: Array<string | RegExp>
: URLs which should be ignored.beforeEmit?: (performanceEntryJSON: Record<string, any>) => Record<string, any> | false;
: Mutate a performance entry before emitting it. Parameter is the JSON representation of the PerformanceEntry. Return false if you want to skip an entire entry.