-
Notifications
You must be signed in to change notification settings - Fork 137
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] RUM JS documentation restructure (#512)
- Loading branch information
1 parent
777078a
commit fd2fe83
Showing
8 changed files
with
194 additions
and
179 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| This is a placeholder file. Release notes are published in CHANGELOG.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,159 +1,36 @@ | ||
| [[intro]] | ||
| == Introduction | ||
|
|
||
| Welcome to the APM Real User Monitoring (RUM) JavaScript Agent documentation. | ||
| The Elastic APM Real User Monitoring (RUM) JavaScript Agent provides detailed performance metrics and error tracking of your web applications. | ||
| It has built-in support for popular platforms and frameworks, and an API for custom instrumentation. | ||
|
|
||
| The Elastic APM RUM JavaScript agent sends performance metrics and errors to the APM Server. | ||
|
|
||
| NOTE: The APM JavaScript agent is compatible with APM Server v6.5+. | ||
|
|
||
| [float] | ||
| [[additional-components]] | ||
| === Additional Components | ||
|
|
||
| APM Agents work in conjunction with the {apm-server-ref-v}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana]. | ||
| Please view the {apm-overview-ref-v}/index.html[APM Overview] for details on how these components work together. | ||
|
|
||
| You will also need to {apm-server-ref-v}/rum.html[enable frontend endpoints in the `apm-server` configuration]. | ||
|
|
||
| [[getting-started]] | ||
| == Getting started | ||
|
|
||
| * <<using-package-managers>> | ||
| * <<using-script-tags>> | ||
| * <<using-production-build>> | ||
| * <<configuring-cors>> | ||
|
|
||
| [float] | ||
| [[using-package-managers]] | ||
| === Using Package Managers | ||
|
|
||
| Install the APM agent for JavaScript as a dependency to your application: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| npm install @elastic/apm-rum --save | ||
| ---- | ||
|
|
||
| Configure the agent: | ||
|
|
||
| [source,js] | ||
| ---- | ||
| 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: '' | ||
| }) | ||
| ---- | ||
|
|
||
| [float] | ||
| [[using-script-tags]] | ||
| === Using Script Tags | ||
|
|
||
| Add a <script> tag to the HTML page and use the `elasticApm` global object to load and initialize the agent: | ||
|
|
||
| NOTE: Please download the latest version of JavaScript agent from https://github.com/elastic/apm-agent-rum-js/releases/latest[GitHub] or | ||
| https://unpkg.com/@elastic/apm-rum/dist/bundles/elastic-apm-rum.umd.min.js[UNPKG] and host the file in your Server/CDN before deploying to production. | ||
|
|
||
| [source,html] | ||
| ---- | ||
| <script src="https://your-cdn-host.com/path/to/elastic-apm-rum.umd.min.js" crossorigin></script> | ||
| <script> | ||
| elasticApm.init({ | ||
| serviceName: '', | ||
| serverUrl: 'http://localhost:8200', | ||
| }) | ||
| </script> | ||
| ---- | ||
|
|
||
| NOTE: Currently the optimized(minified + gzipped) JavaScript bundle size is about 16KiB. | ||
|
|
||
|
|
||
| [float] | ||
| [[using-production-build]] | ||
| === Using Production Build | ||
|
|
||
| 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 | ||
|
|
||
| [float] | ||
| ==== Webpack | ||
| For optimized webpack production build, include the Environment/Define plugin in the webpack configuration. | ||
|
|
||
| [source, js] | ||
| ---- | ||
| const { EnvironmentPlugin } = require('webpack') | ||
| plugins: [ | ||
| new EnvironmentPlugin({ | ||
| NODE_ENV: 'production' | ||
| }) | ||
| ] | ||
| ---- | ||
|
|
||
| You can learn more about this in https://webpack.js.org/plugins/environment-plugin[Webpack documentation]. | ||
| The Agent also supports <<distributed-tracing-guide,distributed tracing>> for all outgoing requests. | ||
| This enables you to analyze performance throughout your microservice architecture -- all in one view. | ||
|
|
||
| [float] | ||
| ==== Rollup | ||
|
|
||
| For optimized rollup production build, include the replace plugin which ensures the right build environment is used. | ||
| [[how-it-works]] | ||
| === How does the Agent work? | ||
|
|
||
| [source, js] | ||
| ---- | ||
| const replace = require('rollup-plugin-replace') | ||
| The RUM Agent automatically instruments the following: | ||
|
|
||
| plugins: [ | ||
| replace({ | ||
| 'process.env.NODE_ENV': 'production' | ||
| }) | ||
| ] | ||
| ---- | ||
| * Page load metrics | ||
| * Load time of Static Assets | ||
| * API requests (XMLHttpRequest and Fetch) | ||
|
|
||
| [float] | ||
| [[configuring-cors]] | ||
| === Configuring CORS | ||
| The agent uses the https://developer.mozilla.org/en-US/docs/Web/API/Navigation_timing_API[Navigation Timing API] | ||
| and https://developer.mozilla.org/en-US/docs/Web/API/Resource_Timing_API[Resource Timing API] | ||
| available in the browser to instrument the page load performance and static assets load times. | ||
|
|
||
| If APM Server is deployed in an origin different than the page's origin, | ||
| you will need to configure Cross-Origin Resource Sharing (CORS). | ||
| To configure CORS, simply: | ||
| The agent automatically captures all outgoing http requests, | ||
| by instrumenting both XHR and Fetch API requests from the webpage to backend servers. | ||
|
|
||
| 1. {apm-server-ref-v}/configuration-rum.html[Enable RUM support] in APM Server. | ||
| 2. Adjust the {apm-server-ref-v}/configuration-rum.html#rum-allow-origins[`apm-server.rum.allow_origins`] configuration. | ||
| By default, APM Server allows all origins. | ||
| For all transactions, the agent automatically captures <<breakdown-metrics-docs, breakdown metrics>>. | ||
|
|
||
| [float] | ||
| ==== How CORS works | ||
|
|
||
| When the RUM agent makes it's initial `POST` request, the browser will check to see if it is a cross-origin request. | ||
| If it is, the browser automatically makes a preflight `OPTIONS` request to the server to ensure the original `POST` request is allowed. | ||
| If this `OPTIONS` check passes, then the original `POST` request is allowed. | ||
| This request will fail if RUM support is not configured in the APM Server. | ||
|
|
||
| If you use a proxy, the preflight request headers may be necessary for your configuration: | ||
|
|
||
| [source,js] | ||
| ---- | ||
| Access-Control-Request-Headers: Content-Type | ||
| Access-Control-Request-Method: POST | ||
| Origin: [request-origin] | ||
| ---- | ||
|
|
||
| The response should include these headers: | ||
| [[additional-components]] | ||
| === Additional Components | ||
|
|
||
| [source,js] | ||
| ---- | ||
| Access-Control-Allow-Headers: Content-Type | ||
| Access-Control-Allow-Methods: POST, OPTIONS | ||
| Access-Control-Allow-Origin: [request-origin] | ||
| ---- | ||
| APM Agents work in conjunction with the {apm-server-ref-v}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana]. | ||
| Please view the {apm-overview-ref-v}/index.html[APM Overview] for details on how these components work together. | ||
|
|
||
| TIP: To learn more about CORS, see the MDN page on | ||
| https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[Cross-Origin Resource Sharing]. | ||
| include::./set-up.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.