repository·main·Indexed 43 days ago
https://github.com/elastic/apm-agent-rum-jsA client-side monitoring tool for capturing real user experience data, including performance metrics, errors, and distributed traces from web browsers. It provides a comprehensive API for initializing the agent, managing custom transactions and spans, enriching data with user and custom contexts, and integrating with frameworks like Angular via the @elastic/apm-rum-angular package.
The Elastic APM Real User Monitoring (RUM) JavaScript Agent tracks performance metrics and errors in web applications. It uses browser timing APIs (Navigation Timing, Resource Timing, Paint Timing, User Timing, etc.) to capture:
XMLHttpRequest and Fetch.apm.startTransaction(). Transactions can be auto-instrumented (like page loads or route changes) or custom-created by the developer.The Span API allows you to track specific units of work within a transaction. You acquire an instance of the Span object by calling the apm.startSpan() method on your Agent instance.
const span = apm.startSpan({ name: 'span_name' });A Span measures the duration of a single event. A span begins when it is created and continues until span.end() is called. To obtain a Span object, use the apm.startSpan() method.
// Example pattern for using a span
const span = apm.startSpan({ name: 'my-event', type: 'custom' });
// ... perform work ...
span.end();The RUM agent captures the overall user experience of page loading as part of a page-load transaction. This includes resource timing information as Spans and navigation marks to create a waterfall view.
Key metrics captured include:
domainLookupEnd - domainLookupStart).connectEnd - connectStart).responseEnd - requestStart).tagsdomInteractive - domLoading).domContentLoadedEventEnd - domContentLoadedEventStart).loadEventEnd - loadEventStart).transaction.marks.agent.timeToFirstByte.Note: The page-load transaction is measured relative to the fetchStart timestamp from the Navigation Timing API. To accurately measure the duration of the load event, use the Fire load event Span or the transaction mark transaction.marks.agent.domComplete in the Elasticsearch document.
Agent API provides all functions and properties for managing the RUM agent. You obtain an instance of the Agent object (commonly referred to as apm in documentation) by initializing the agent. This can be done either by including a script element on your page or by requiring the elastic-apm-rum module in a Node.js environment.When the RUM agent initiates its first POST request to a different origin, the browser performs a preflight OPTIONS request. This request must succeed for the actual data transmission to proceed. If RUM support is not enabled in the APM Server, this check will fail.
If you are using a proxy between the agent and the APM Server, ensure your proxy handles the following headers:
Request headers (from browser/proxy):
Access-Control-Request-Headers: Content-TypeAccess-Control-Request-Method: POSTOrigin: [request-origin]Response headers (from proxy/server):
Access-Control-Allow-Headers: Content-TypeAccess-Control-Allow-Methods: POST, OPTIONSAccess-Control-Allow-Origin: [request-origin]sendCredentialsIf you have enabled the sendCredentials configuration option in the RUM agent, your proxy or server response must include the following header to allow authenticated requests:
Access-Control-Allow-Credentials: true
Additionally, the Access-Control-Allow-Origin header must explicitly match the page's origin (it cannot be a wildcard * when credentials are sent).
// Required response headers when sendCredentials is true
Access-Control-Allow-Origin: [request-origin]
Access-Control-Allow-Credentials: trueThe agent captures responsiveness metrics to help understand how users perceive performance. Many of these are Core Web Vitals:
page-load in Chromium-based browsers.page-load (Chrome >77).First Input Delay span for page-load (Chrome >85).Total Blocking Time span.Longtask<name> spans for all managed transactions.performance.measure are recorded as spans by their measure name.For transactions other than standard page loads—such as Single Page Application (SPA) route changes or user-created transactions—breakdown metrics are calculated based on the associated spans within that transaction.
resource at 20% and http at 80%.The Elastic APM RUM agent provides an implementation of the OpenTracing API. The ElasticApmTracer translates OpenTracing API calls into Elastic APM data.
In this mapping:
Transaction.Span objects.