@grafana/faro-web-tracing
This package provides tools for integrating OpenTelemetry based tracing with the Faro for the web.
See quick start document for instructions how to set up and use.
Faro web tracing implementation.
This package provides tools for integrating OpenTelemetry based tracing with the Faro for the web.
See quick start document for instructions how to set up and use.
Breaking (@grafana/faro-web-sdk): User action events now have a standardized event name
(faro.user.action), with the specific user action name moved to a parameter for improved
consistency and filtering capabilities.
Migration note: If you previously filtered user action events by event name, update your
queries to use the new event name (faro.user.action) and filter by the userActionName
attribute for the specific action.
Breaking (@grafana/faro-web-sdk): Web vitals now always tracks attribution data. The
trackWebVitalsAttribution and webVitalsInstrumentation.trackAttribution configuration flags have
been removed. Attribution data is now collected by default and cannot be disabled.
Migration note: If you were using trackWebVitalsAttribution: false or
webVitalsInstrumentation: { trackAttribution: false } to disable attribution, remove these options
from your configuration. Attribution data will now always be included in web vitals measurements.
Breaking (@grafana/faro-web-sdk): Removed the trackUserActionsPreview option from Faro
configuration. User actions instrumentation is now always enabled by default (#1772).
Migration note: If you previously used trackUserActionsPreview: true or left it unset,
simply remove this option - no further action is required. If you had set
trackUserActionsPreview: false to disable user actions tracking, you now need to exclude the
UserActionInstrumentation from your instrumentations array manually.
Feature (@grafana/faro-web-sdk) [experimental]: Added navigation instrumentation to track soft
navigations (same-document navigations). The instrumentation monitors URL changes, DOM mutations,
HTTP requests, and user interactions to automatically detect and report navigation events with
details including fromUrl, toUrl, and duration. Enable by setting experimental.trackNavigation: true
in the configuration.
Fix (@grafana/faro-web-sdk): Fixed an issue where custom severity and custom trigger properties
were not being included in user action attributes (#1551)
@grafana/faro-web-sdk): Fixed an error when initializeFaro is called without any window
object present (#1643)@grafana/faro-web-tracing): fixed error with the web-tracing CDN bundle related to
incorrect dependency import of the getActiveUserAction API (#1500)@grafana/faro-web-sdk): Updated the web-vitals library to v5 (#1386)@grafana/faro-web-sdk): Added user actions to the API (#1384)Feature (@grafana/faro-web-sdk): Added user actions severity (#1418)
Chore (@grafana/faro-*): set default node version to lts/jod
@grafana/faro-web-sdk): Update webkitLineRegex to prevent the
function name capture group from matching URLsBreaking changes coming with Faro version 2
@grafana/faro-web-tracing
FaroSessionSpanProcessor which is replaced by the
FaroMetaAttributesSpanProcessor. While FaroSessionSpanProcessor wasn't used anymore,
it was kept for users using it in manual Faro + OTel setups.session_id attribute in favor of session.id.@grafana/faro-web-sdk
instrumentation-fetch, instrumentation-xhr, and instrumentation-performance-timeline
packages due to lack of maintenance. These packages remain available on NPM but are flagged as deprecated.Feature (@grafana/faro-web-sdk): Add CSP instrumentation (#1312)
Improvement (@grafana/faro-*): Rename userActionEventType to userActionTrigger for improved clarity (#1298)
Chore (@grafana/faro-web-sdk): Prevent tracking of custom collector URLs that don't match the Faro collector
URL structure (#1297)
@grafana/faro-core): Ensure first instrumentation gets properly removed (#1312)@grafana/faro-*): Remove Node.js 23 from build and test matrix as it's EoL (#1343)@grafana/faro-*): upgrade to yarn 4Improvement (@grafana/faro-web-sdk): don't attach user action context to http request when in halt mode (#1249)
Chore (@grafana/faro-*): Updated Node.js version support by removing Node.js 18 (EOL) and adding Node.js 24
LTS (#1259).
@grafana/faro-*): Revert "Changed Node.js version support by removing Node.js 18 because it is EOL" (#1195).Improvement (@grafana/faro-web-sdk): Track transfer size for resource requests
(#1169).
Fix (@grafana/faro-web-sdk): Fixed the ignored errors matching logic to properly identify
errors based on stack trace content (#1168).
Chore(deps): Changed Node.js version support by removing Node.js 18 because it is EOL (#1180).
Fix (@grafana/faro-web-sdk): Fixed incorrect calculation of TLS negotiation time in
performance metrics (#1156).
Improvement (@grafana/faro-web-sdk): Prevent negative values in performance timing measurements
(#1154).
Fix (@grafana/faro-web-tracing): Fixed an issue with HTTP request sidecar events not being
transmitted when using the CDN distribution (#1139).
Fix (@grafana/faro-react): Export the ExceptionEventExtended type from the package, allowing
users to import all necessary types from a single source (#1141).
@grafana/faro-web-sdk): Add option to preserve original JavaScript error objects,
making them accessible within the beforeSend function for advanced error handling (#1133).@grafana/faro-web-sdk): Enhanced web vitals monitoring by automatically tracking
attribution data by default (#991).@grafana/faro-web-sdk): Provide a function to start a user-action (#1115).@grafana/faro-*): Upgrade OpenTelemetry dependencies to v0.200.* (#1126).Feature (@grafana/faro-web-sdk): Alpha version of user actions instrumentation (#1101).
Fix (@grafana/faro-web-tracing): Fixed unexpected behavior in xhr instrumentation when custom
objects with a toString method were used as URLs (#1100).
Dependencies (@grafana/faro-*): Upgrade to TypeScript 5.8.2 (#1092)
@grafana/faro-core): Avoid sending empty attributes or context objects
when no data is provided (#1089)@grafana/faro-web-sdk): The ignored errors parser now also parses stack traces.
This is helpful, for example, to exclude all errors thrown by extensions (#1000).@grafana/faro-web-sdk): Provide a webVitalsInstrumentation.reportAllChanges option to report
all changes for web vitals (#981)@grafana/faro-web-sdk): Enhance user meta properties to align with OTEL semantic
conventions for user attributes (#990)@grafana/faro-web-tracing): Add user attributes to spans (#990)Improvement (@grafana/faro-web-tracing): Removed @opentelemetry/context-zone as it is not
required for the default instrumentations.
Users who need ZoneContextManager for additional OTEL instrumentations can inject it via the
web-tracing configuration.
initializeFaro({
// ...
instrumentations: [
// ...
new TracingInstrumentation({
contextManager: new ZoneContextManager(),
instrumentations: [
/* custom instruments */
],
}),
],
// ...
});@grafana/faro-web-sdk): Ensure all properties in attributes and context objects are
stringified when sending custom signals (#952)@grafana/faro-web-sdk): The optional context object in the pushError API now correctly
stringifies all provided values (#944)@grafana/faro-web-sdk): Corrected the setPage() API to update the page.id properly and
correctly merge with the active page metadata (#933)@grafana/faro-web-sdk): Provide APIs to send service.name override instructions to the
receiver (#893)@grafana/faro-web-sdk): Introduced setPage(meta) API to overwrite page metadata and
added an option to inject a custom pageId parser for generating custom pageIds continuously
(#923)Feature (@grafana/faro-web-sdk): Enables support to provide a custom serializer for console
error properties (#901)
Improvement (@grafana/faro-web-sdk): Send an event for service.name overrides (#903)
Improvement (@grafana/faro-*) Add required Node engines to package.json (#913)
Fix (faro demo): Add missing json files to Docker image (#925).
@grafana/faro-web-tracing): add duration to events from traces (#861)@grafana/faro-transport-otlp-http [experimental]): Prevent sending requests when the
endpoint URL is not configured (#827).@grafana/faro-web-tracing): upgrade otel deps (#763)@grafana/faro-web-sdk): Update Faro log parsing in console instrumentation to use Faro's
default log parser (#745)@grafana/faro-web-sdk): Guard console instrumentation stringifier against circular object
references for non-error logs (#742)@grafana/faro-web-sdk): Guard user session stringifier against circular object references (#715)Fix (@grafana/faro-web-sdk): Prevents circular references in objects sent via console.error
messages (#730)
Refactor (@grafana/faro-web-sdk): Provide config option to send log messages for console.error
calls (#731)
Feat (@grafana/faro-web-sdk): Provide a getIgnoreUrls() function to easily retrieve the
configured ignoreUrls (#732)
@grafana/faro-web-sdk): The console instrumentation now sends an Error signal
instead of a Log signal for console.error() calls (#703).@grafana/faro-web-sdk): The resource timings instrumentation now includes ttfb
(Time to First Byte) and visibilityState in faro.performance.resource timings (#708).@grafana/faro-*): Minor dependency updates.@grafana/faro-web-tracing): Enhance the xhr instrumentation to handle both URL objects and
strings seamlessly (#695).@grafana/faro-web-sdk): Isolated Faro instances now exclude the default collector
URLs of other instances by default (#684).Improvement (@grafana/faro-web-sdk): The pushError API now automatically includes error.cause
in the Faro exception context (#688).
Fix (@grafana/faro-transport-otlp-http [experimental]): add service.namespace attribute if set
(#687).
@grafana/faro-transport-otlp-http [experimental]): update semantic attributes
for browser (#684).browser.user_agent is replaced by user_agent.originalbrowser.os is replaced by browser.platformImprovement (@grafana/faro-web-sdk): don't automatically send a view_change event for the default
view (#647)
Dependencies (@grafana/faro-web-tracing): upgrade otel deps (#670)
deployment.environment is now deprecated and will be replaced by
deployment.environment.name.session_id is now deprecated and will be replaced by session.id@grafana/faro-core): upgrade otel deps (#670).@grafana/faro-transport-otlp-http [experimental]): upgrade otel deps (#670)enduser.id is replaced by user.idenduser.name is replaced by user.username,enduser.email is replaced by user.email,enduser.attributes is replaced by user.attributes,http.url is replaced by url.fulldeployment.environment is replaced by deployment.environment.name@grafana/faro-transport-otlp-http [experimental]): Properly consume response body (#664).Improvement (@grafana/faro-web-sdk): Provide and option to pass a correction timestamp via the
Faro API (#658).
Fix (@grafana/faro-web-sdk): Adjust the timestamp of a navigation or resource event to reflect
the actual time the event occurred, rather than the signal creation time. (#658).
Improvement: (@grafana/faro-web-tracing) The underlying XHR and Fetch instrumentation are now
configured to ignore network events by default. This behavior can be enabled back through the
options in the WebTracing class.
@grafana/faro-web-tracing): ensure that span status is always set to error for
erroneous xhr requests (#644).@grafana/faro-web-tracing): ensure that span status is always set to error for
erroneous fetch requests (#641).@grafana/faro-web-sdk): track web vitals attribution (#595).@grafana/faro-web-sdk): set span context for navigation events (#608).Feature (@grafana/faro-react): add helper functions to initialize React Router integration (#622).
Improvement (@grafana/faro-web-sdk): Auto extend a session if the Faro receiver indicates that a
session is invalid (#591).
Improvement (@grafana/faro-web-tracing): provide the app.namespace attribute in the app meta
which is attached as service.namespace to the resource attributes object (#627).
Dependencies (@grafana/faro-web-tracing): upgrade otel deps (#621).
@grafana/faro-core): upgrade otel deps (#621).Dependencies (@grafana/faro-transport-otlp-http [experimental]): upgrade otel deps (#621).
Fix (@grafana/faro-react): Mark react-router-dom peer dependency as optional (#617).
@grafana/faro-core): source map uploads - add bundleId to the MetaApp Meta object
(#476).@grafana/faro-web-sdk): track window dimensions via the browser meta (#594).@grafana/faro-web-sdk): If logArgsSerializer is set in the config
of initializeFaro, it will be forwarded to the core (#589).@grafana/faro-react): Fixed a type issue in react v6 router dependencies (#585).@grafana/faro-core): Config has now a parameter logArgsSerializer to set a custom serializer for
log arguments (#564). This is useful if log message args are complex and might produce [object Object] in the logs.@grafana/faro-web-tracing): Fix an import issue causing builds to fail (#581).@grafana/faro-react): Fix type issues in react data route wrapper withFaroRouterInstrumentation (#584).@grafana/faro-web-sdk): provide option to globally
exclude endpoint URLs from being tracked. This applies to the following instrumentations:
performance, xhr, fetch and web-tracing (#554).faro demo): Update Demo to pin docker images and replace Cortex by Mimir (#563).faro demo): Migrate demo Grafana agent to Grafana alloy@grafana/faro-web-sdk, @grafana/faro-web-tracing): Remove pre-release warning (#550).@grafana/faro-web-tracing): Remove redundant DocumentLoadInstrumentation.
Faro tracks page load data by default (#551).@grafana/faro-web-sdk): Performance instrumentation only tracks resource entries initiated
by calls to the fetch method or xhr-html requests. To track all resource entries set
trackResources: true (#560).@grafana/faro-web-sdk): Add parsing time to FaroNavigationTiming (#541).@grafana/faro-web-sdk): Get rid of structureClone. It caused breakage in some
sandboxed environments because of injected proxy objects (#536).@grafana/faro-web-sdk): Add K6 test ID to K6 meta if available in window.k6 object (#531).@grafana/faro-web-sdk): Add responseStatus to performance events (#526).@grafana/faro-web-sdk): Faro updates sessions in an infinite loop if DOM Storage is not
available (#519).@grafana/faro-react): Support instrumenting React Router v6 data routers (#518).@grafana/faro-web-sdk): Session started timestamp was reset on page-loads (#513).@grafana/faro-web-tracing): faro.trace.* attached spanContext from active span instead of
the respective child span (#510).@grafana/faro-web-sdk): Faro APIs now support adding a custom traceId and spanId to
signals (#510).@grafana/faro-web-tracing): Dedupe Faro trace events (#507).@grafana/faro-web-sdk): Enable Faro Navigation and Resource timings instrumentation by default (#482).@grafana/faro-web-tracing): Send a dedicated Faro event for traces of kind=client (#499).@grafana/faro-web-sdk): add duration property in faro.performance.resource timings and
rename property totalNavigationTime to duration in faro.performance.navigation timings (#490).@grafana/faro-web-sdk): crash when navigator.userAgentData is undefined (#494).@grafana/faro-web-tracing, @grafana/faro-core): Update OpenTelemetry dependencies (#475).@grafana/faro-web-sdk): add response time to performance timings (#465).@grafana/faro-web-tracing): Update instrumentation-document-load which prevents build.
from breaking (#467).@grafana/faro-web-sdk): instrument navigation and resource timings. As long as
this feature is in preview it is disabled by default (#434)@grafana/faro-web-tracing): Automatically add the value of the MetaApp environment
property to the resource attributes deployment.environment property (#453)@grafana/faro-web-sdk): change storage key prefix for Faro session to use reverse domain
notation (#432)@grafana/faro-core): make check for presence of Event more robust (#436)@grafana/faro-web-sdk): Multiple session_extend events were emitted if multiple
browsing contexts were open when a session was auto-extended (#428)@grafana/faro-web-sdk): guard against missing isSampled (#425)@grafana/faro-web-sdk): generateSessionId() was executed twice (#423)@grafana/faro-web-sdk): user defined session attributes added during initialize were not
picked up (#420)@grafana/faro-web-sdk): provide custom generateSessionId() function which Faro will use
instead of the internal sessionId generator if configured (#421).@grafana/faro-web-sdk): Fixed an issue where the session meta was missing in session
lifecyle events sent during the init phase (#417).@grafana/faro-web-sdk): Fixed an issue where the first calculated session was always part of the sample (#415).@grafana/faro-react): add missing peer dependency on react-dom (#400).@grafana/faro-core): remove unused @opentelemetry/api-metrics dependency (#401).@grafana/faro-web-tracing): remove unused @opentelemetry/sdk-trace-base dependency (#401).@grafana/faro-web-sdk): fixed a issue where session based sampling combined with batched mode
lead to dropped items, even if they were part of the sample (#402).@grafana/faro-web-sdk): Cleanup up session meta before sending it to not include Faro specific
attributes (#408).@grafana/faro-web-sdk): The new volatile session manager is enabled by default. The
old legacy session object is removed. This change is only breaking if you customized the old default
session management (#412).from*) and the destination route or view (to*) (#397).routeChange to
route_change. The url and route attributes sent with the event are renamed to toRoute and
toUrl.(#397).pushError behavior.pushError api.globalThis instead of global or window in case the SDK is used in webworkers.core packageExtension interface in core, web-sdk and react packagesgenShortID function in core, web-sdk and react packagesstarted property from MetaSession interfacefaro instance and they should not rely on
the global faro instance as it would break the isolation mode. Various APIs are passed individually (i.e.
this.api vs this.faro.api, this.unpatchedConsole vs this.faro.unpatchedConsole)EventAttributes exportSessionInstrumentation that sends session_start event on initialization or when new session is set.
SessionProcessor for OTel that will add session_id attribute to every span if available.agent.api.pushEvent method for capturing RUM events.FetchTransport will back off after receiving 429 Too Many Requests response. Events will be dropped during backoff period.
Backoff period respects Retry-After header if present.@grafana/agent-integration-react.initializeAgent was renamed to initializeGrafanaAgent.@grafana/agent-core to @grafana/agent-web and @grafana/agent-integration-react.agent.pause() and agent.unpause() to be able to temporarily stop.
ingesting events.agent.api.pushError method to push Error objects directly.@grafana/agent-tracing-web.ignoreErrors configuration option.initializeAgent() method specifically for web apps in @grafana/agent-web.