Install the Agent
editInstall the Agent
editThere are multiple ways to add the APM RUM Agent to your web page:
-
Using Script Tags: Add a
<script>
tag to the HTML page. - Using Bundlers: Bundling the Agent package during the application’s build process
Using Script Tags
editSynchronous / Blocking Pattern
editAdd a <script> tag to load the bundle and use the elasticApm
global
object to initialize the agent:
<script src="https://<your-cdn-host>.com/path/to/elastic-apm-rum.umd.min-<version>.js" crossorigin></script> <script> elasticApm.init({ serviceName: '<instrumented-app>', serverUrl: '<apm-server-url>', }) </script>
Asynchronous / Non-Blocking Pattern
editLoading the script asynchronously ensures the agent script will not block other
resources on the page, however, it will still block browsers onload
event.
<script> ;(function(d, s, c) { var j = d.createElement(s), t = d.getElementsByTagName(s)[0] j.src = 'https://<your-cdn-host>.com/path/to/elastic-apm-rum.umd.min-<version>.js' j.onload = function() {elasticApm.init(c)} t.parentNode.insertBefore(j, t) })(document, 'script', {serviceName: '<instrumented-app>', serverUrl: '<apm-server-url>'}) </script>
Even though this is the recommended pattern, there is a caveat to be aware of. Because the downloading and initializing of the agent happens asynchronously, distributed tracing will not work for requests that occur before the agent is initialized.
Please download the latest version of RUM agent from GitHub or
UNPKG
and host the file in your Server/CDN before deploying to production. Remember to
use a proper versioning scheme and set a far future max-age
and immutable
in the cache-control
header, as the file never changes.
The debug messages are removed by default from the minified bundles. It is strongly recommended to use the unminified version for debugging purposes.
Using Bundlers
editInstall the Real User Monitoring APM agent as a dependency to your application:
npm install @elastic/apm-rum --save
Configure the agent:
import { init as initApm } from '@elastic/apm-rum' const apm = initApm({ // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space) serviceName: '', // Set custom APM Server URL (default: http://localhost:8200) serverUrl: 'http://localhost:8200', // Set service version (required for sourcemap feature) serviceVersion: '' })
Production Build
editBy default, RUM agent logs all the debug messages to the browser console. These logs are very useful in development. However, they make the RUM agent bundle size larger so you should make sure to use the optimized production version when deploying your application.
You can find instructions for building optimized code below for different bundlers.
Webpack
editFor optimized webpack production build, include the Environment/Define plugin in the webpack configuration.
const { EnvironmentPlugin } = require('webpack') plugins: [ new EnvironmentPlugin({ NODE_ENV: 'production' }) ]
You can learn more about this in Webpack documentation.
Rollup
editFor optimized rollup production build, include the replace plugin which ensures the right build environment is used.
const replace = require('rollup-plugin-replace') plugins: [ replace({ 'process.env.NODE_ENV': JSON.stringify('production') }) ]
Currently the optimized (minified + gzipped) agent bundle size is about 16KiB.