Install the Agent

edit

There are multiple ways to add the APM RUM Agent to your web page:

Using Script Tags

edit

Synchronous / Blocking Pattern

edit

Add 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

edit

Loading 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

edit

Install 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

edit

By 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

edit

For 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

edit

For 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.