diff --git a/docs/guide/agent-server-compatibility.asciidoc b/docs/guide/agent-server-compatibility.asciidoc index a8b9ef6ba2f..11887398111 100644 --- a/docs/guide/agent-server-compatibility.asciidoc +++ b/docs/guide/agent-server-compatibility.asciidoc @@ -1,73 +1,37 @@ [[agent-server-compatibility]] -== Agent/Server compatibility +== Agent and Server compatibility -Below is a chart that outlines the compatibility between different versions of the APM agents and the APM Server. - -NOTE: APM Server version 6.5 introduced a new way for APM agents to communicate with the APM Server. -To take advantage of new features, -it is recommended that you update to the newest version of the applicable agent. - -[float] -[[go-compatibility]] -==== Go Agent Compatibility - -[options="header"] -|======================================================================= -|Agent Version |APM Server Version -|1.x |>= 6.5 -|======================================================================= - -[float] -[[java-compatibility]] -==== Java Agent Compatibility - -[options="header"] -|======================================================================= -|Agent Version |APM Server Version -|1.x |>= 6.5 -|======================================================================= - -[float] -[[nodejs-compatibility]] -==== Node.js Agent Compatibility - -[options="header"] -|======================================================================= -|Agent Version |APM Server Version -|1.x |6.2-6.x -|2.x |>= 6.5 -|======================================================================= - -[float] -[[python-compatibility]] -==== Python Agent Compatibility - -[options="header"] -|======================================================================= -|Agent Version |APM Server Version -|2.x, 3.x |6.2-6.x -|4.x |>= 6.5 -|======================================================================= - -[float] -[[ruby-compatibility]] -==== Ruby Agent Compatibility - -[options="header"] -|======================================================================= -|Agent Version |APM Server Version -|1.x |6.4-6.x -|2.x |>= 6.5 -|======================================================================= - -[float] -[[rum-compatibility]] -==== RUM Agent Compatibility +The chart below outlines the compatibility between different versions of the APM agents and the APM Server. [options="header"] -|======================================================================= -|Agent Version |APM Server Version -|0.x |6.3-6.4 -|1.x |6.4 -|2.x, 3.x, 4.x |>= 6.5 -|======================================================================= +|==== +|Agent |Agent Version |APM Server Version +// Go +.1+|**Go Agent** +|`1.x` |>= `6.5` + +// Java +.1+|**Java Agent** +|`1.x`|>= `6.5` + +// Node +.2+|**Node.js Agent** +|`1.x` |`6.2`-`6.x` +|`2.x` |>= `6.5` + +// Python +.2+|**Python Agent** +|`2.x`, `3.x` |`6.2`-`6.x` +|`4.x` |>= `6.5` + +// Ruby +.2+|**Ruby Agent** +|`1.x` |`6.4`-`6.x` +|`2.x` |>= `6.5` + +// RUM +.3+|**JavaScript RUM Agent** +|`0.x` |`6.3`-`6.4` +|`1.x` |`6.4` +|`2.x`, `3.x`, `4.x` |>= `6.5` +|==== diff --git a/docs/guide/apm-data-model.asciidoc b/docs/guide/apm-data-model.asciidoc index 1e89c256a54..634990aef03 100644 --- a/docs/guide/apm-data-model.asciidoc +++ b/docs/guide/apm-data-model.asciidoc @@ -1,12 +1,11 @@ [[apm-data-model]] == Data Model -Elastic APM agents capture different types of information from within their instrumented applications - namely `spans`, `transactions`, `errors`, and `metrics`. +Elastic APM agents capture different types of information from within their instrumented applications - namely `spans`, `transactions`, and `errors`. * <> * <> * <> -* <> [[transaction-spans]] === Spans @@ -110,27 +109,3 @@ via the `transaction.id`. include::../context.asciidoc[] Errors are stored in {apm-server-ref-v}/error-indices.html[error indices]. - -[[metrics]] -=== Metrics - -APM agents automatically pick up basic host-level metrics, -including system and process-level CPU and memory metrics. -Agent specific metrics are also available, -like {apm-java-ref-v}/metrics.html[JVM metrics] in the Java Agent, -and {apm-go-ref-v}/metrics.html[Go runtime] metrics in the Go Agent. - -Infrastructure and application metrics are important sources of information when debugging production systems, -which is why we've made it easy to filter metrics for specific hosts or containers in the Kibana {kibana-ref}/apm-ui.html[APM UI]. - -Metrics have the `processor.event` property set to `metric`. - -Metrics are stored in {apm-server-ref-v}/metricset-indices.html[metric indices]. - -For a full list of tracked metrics, see the relevant agent documentation: - -* {apm-go-ref-v}/metrics.html[Go] -* {apm-java-ref-v}/metrics.html[Java] -* {apm-node-ref-v}/metrics.html[Node.js] -* {apm-py-ref-v}/metrics.html[Python] -* {apm-ruby-ref-v}/metrics.html[Ruby] diff --git a/docs/guide/apm-doc-directory.asciidoc b/docs/guide/apm-doc-directory.asciidoc index f8c5dd93e80..1b569ba6a37 100644 --- a/docs/guide/apm-doc-directory.asciidoc +++ b/docs/guide/apm-doc-directory.asciidoc @@ -1,30 +1,40 @@ -[[doc-directory]] -== Documentation directory +[[components]] +== Components and documentation -The following sections are designed to guide you through the available Elastic APM documentation. +Elastic APM consists of four components: *APM Agents*, *APM Server*, *Elasticsearch*, and *Kibana*. + +image::images/apm-architecture-cloud.png[Architecture of Elastic APM] [float] -=== APM Overview +=== APM Agents -You're here! -The APM Overview is your launchpad for getting started with APM. -We recommend reading through this documentation to gain a deeper understanding of the Elastic APM ecosystem. +APM agents are open source libraries written in the same language as your service. +You may only need one, or you might use all of them. +You install them into your service as you would install any other library. +They instrument your code and collect performance data and errors at runtime. +This data is buffered for a short period and sent on to APM Server. -* <> -* <> -* <> -* <> -* <> +Each agent has its own documentation: -TIP: Want to skip straight to installation? -Simply use an existing cluster or grab a fresh installation of the Elastic Stack, -spin up an APM Server, and add a bit of code to instrument your app with agents. -Full details are available on the <> page. +* {apm-go-ref-v}/introduction.html[Go agent] +* {apm-java-ref-v}/intro.html[Java agent] +* {apm-node-ref-v}/intro.html[Node.js agent] +* {apm-py-ref-v}/getting-started.html[Python agent] +* {apm-ruby-ref-v}/introduction.html[Ruby agent] +* {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] [float] === APM Server -The APM Server receives data from APM agents and converts that data into Elasticsearch documents. +APM Server is an open source application that receives performance data from your APM agents. +It's a {apm-server-ref-v}/why-separate-component.html[separate component by design], +which helps keep the agents light, prevents certain security risks, and improves compatibility across the Elastic Stack. + +After the APM Server has validated and processed events from the APM agents, +the server transforms the data into Elasticsearch documents and stores them in corresponding +{apm-server-ref-v}/exploring-es-data.html[Elasticsearch indices]. +In a matter of seconds you can start viewing your application performance data in the Kibana APM UI. + The {apm-server-ref-v}/index.html[APM Server reference] provides everything you need when it comes to working with the server. Here you can learn about {apm-server-ref-v}/installing.html[installation], {apm-server-ref-v}/configuring-howto-apm-server.html[configuration], @@ -32,55 +42,24 @@ Here you can learn about {apm-server-ref-v}/installing.html[installation], {apm-server-ref-v}/monitoring.html[monitoring], and more. [float] -=== APM Agents +=== Elasticsearch -APM agents are open source libraries that you install into your services. -You may only need one, or you might use all of them. -Each agent has its own documentation: - -* {apm-go-ref}/introduction.html[Go agent] -* {apm-java-ref}/intro.html[Java agent] -* {apm-node-ref}/intro.html[Node.js agent] -* {apm-py-ref}/getting-started.html[Python agent] -* {apm-ruby-ref}/introduction.html[Ruby agent] -* {apm-rum-ref}/intro.html[JavaScript Real User Monitoring (RUM) agent] +{ref}/index.html[Elasticsearch] is a highly scalable open-source full-text search and analytics engine. +It allows you to store, search, and analyze large volumes of data quickly and in near real time. +Elasticsearch is used to store APM performance metrics and make use of its aggregations. [float] === APM Kibana UI -Application performance monitoring is all about visualizing data and detecting bottlenecks, so it's crucial you understand how to use the {kibana-ref}/xpack-apm.html[Kibana APM UI]. The following sections will help you get started: +{kibana-ref}/index.html[Kibana] is an open source analytics and visualization platform designed to work with Elasticsearch. +You use Kibana to search, view, and interact with data stored in Elasticsearch. + +Since application performance monitoring is all about visualizing data and detecting bottlenecks, +it's crucial you understand how to use the {kibana-ref}/xpack-apm.html[Kibana APM UI]. +The following sections will help you get started: * {kibana-ref}/apm-getting-started.html[Getting Started] * {kibana-ref}/apm-bottlenecks.html[Visualizing application bottlenecks] * {kibana-ref}/apm-ui.html[Using the APM UI] APM also has built-in integrations with Machine Learning. To learn more about this feature, refer to the Kibana UI documentation for {kibana-ref}/machine-learning-integration.html[Machine learning integration]. - -TIP: If you'd like to dive deeper into Kibana, the general {kibana-ref}/index.html[Kibana documentation] is also helpful. - -[float] -=== Troubleshooting - -If you run into trouble, there are three places you can look for help: -Troubleshooting documentation, GitHub repositories, and our discussion forum. - -[float] -==== Troubleshooting documentation - -The APM Server and some of the APM agents have troubleshooting guides: - -* {apm-server-ref-v}/troubleshooting.html[Server troubleshooting] -* {apm-java-ref}/trouble-shooting.html[Java agent troubleshooting] -* {apm-node-ref}/troubleshooting.html[Node.js agent troubleshooting] -* {apm-rum-ref}/troubleshooting.html[RUM troubleshooting] - -[float] -==== GitHub repositories - -Elastic APM is open source! Our https://github.com/elastic?utf8=%E2%9C%93&q=apm[GitHub repositories] have a plethora of knowledge available in the form of code, issues, and PRs. - -[float] -==== Discussion forum - -For additional questions and feature requests, -visit our https://discuss.elastic.co/c/apm[discussion forum]. diff --git a/docs/guide/apm-release-notes.asciidoc b/docs/guide/apm-release-notes.asciidoc index 53077842f3e..048239f0cbc 100644 --- a/docs/guide/apm-release-notes.asciidoc +++ b/docs/guide/apm-release-notes.asciidoc @@ -30,7 +30,7 @@ No significant changes. [float] ==== New features -* Elastic APM agents now automatically record certain <>. +* Elastic APM agents now automatically record certain infrastructure and application metrics. * Elastic APM agents support the W3C Trace Context. All agents now have <>. * <> is generally available. diff --git a/docs/guide/distributed-tracing.asciidoc b/docs/guide/distributed-tracing.asciidoc index cdccae149c3..b7579efde8d 100644 --- a/docs/guide/distributed-tracing.asciidoc +++ b/docs/guide/distributed-tracing.asciidoc @@ -1,6 +1,9 @@ [[distributed-tracing]] == Distributed tracing +Together, <> and <> form a `Trace`. +Traces are not events, but group together events that have a common root. + Elastic APM supports distributed tracing. Distributed tracing enables you to analyze performance throughout your microservices architecture all in one view. This is accomplished by tracing all of the requests - from the initial web request to your front-end service - to queries made to your back-end services. @@ -11,4 +14,4 @@ The APM UI in Kibana also supports distributed tracing. The Timeline visualization has been redesigned to show all of the transactions from individual services that are connected in a trace: [role="screenshot"] -image::distributed-tracing.jpg[distribute tracing in the UI] +image::images/apm-distributed-tracing.png[Distributed tracing in the APM UI] diff --git a/docs/guide/distributed-tracing.jpg b/docs/guide/distributed-tracing.jpg deleted file mode 100644 index 99f641043cb..00000000000 Binary files a/docs/guide/distributed-tracing.jpg and /dev/null differ diff --git a/docs/guide/images/apm-architecture-cloud.png b/docs/guide/images/apm-architecture-cloud.png new file mode 100644 index 00000000000..6bc7001fb9f Binary files /dev/null and b/docs/guide/images/apm-architecture-cloud.png differ diff --git a/docs/guide/images/apm-architecture-diy.png b/docs/guide/images/apm-architecture-diy.png new file mode 100644 index 00000000000..d4e96466081 Binary files /dev/null and b/docs/guide/images/apm-architecture-diy.png differ diff --git a/docs/guide/images/apm-distributed-tracing.png b/docs/guide/images/apm-distributed-tracing.png new file mode 100644 index 00000000000..ba9b308d227 Binary files /dev/null and b/docs/guide/images/apm-distributed-tracing.png differ diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc index 9d5d8115063..92d6cf0b617 100644 --- a/docs/guide/index.asciidoc +++ b/docs/guide/index.asciidoc @@ -9,20 +9,26 @@ endif::[] [[gettting-started]] = APM Overview -include::./apm-doc-directory.asciidoc[] - include::./overview.asciidoc[] +include::./apm-doc-directory.asciidoc[] + include::./install-and-run.asciidoc[] include::./apm-data-model.asciidoc[] include::./distributed-tracing.asciidoc[] +include::./rum.asciidoc[] + include::./opentracing.asciidoc[] include::./agent-server-compatibility.asciidoc[] +include::./troubleshooting.asciidoc[] + include::./apm-breaking-changes.asciidoc[] -include::./apm-release-notes.asciidoc[] \ No newline at end of file +include::./apm-release-notes.asciidoc[] + +include::./redirects.asciidoc[] diff --git a/docs/guide/install-and-run.asciidoc b/docs/guide/install-and-run.asciidoc index fa4350a291d..8e5383eba28 100644 --- a/docs/guide/install-and-run.asciidoc +++ b/docs/guide/install-and-run.asciidoc @@ -1,69 +1,70 @@ [[install-and-run]] == Install and run -This page is designed to make it easy to install and run the components of Elastic APM. -Simply follow the step-by-step links below, and you'll be up and running in no time. -Let's get started. - -[TIP] -============== -You can skip having to install {es}, {kib}, and APM Server by using our +The easiest way to get started with Elastic APM is by using our https://www.elastic.co/cloud/elasticsearch-service[hosted {es} Service] on Elastic Cloud. The {es} Service is available on both AWS and GCP, and automatically configures APM Server to work with {es} and {kib}. -Additional {cloud}/ec-manage-apm-settings.html[APM user settings] are also available. -https://www.elastic.co/cloud/elasticsearch-service/signup[Try out the {es} -Service for free]. -============== +[float] +=== Hosted Elasticsearch Service -* <> -* <> -* <> -* <> -* <> -* <> +image::images/apm-architecture-cloud.png[Install Elastic APM on cloud] + +Skip managing your own {es}, {kib}, and APM Server by using our +https://www.elastic.co/cloud/elasticsearch-service[hosted {es} Service] on +Elastic Cloud. + +https://www.elastic.co/cloud/elasticsearch-service/signup[Try out the {es} Service for free], +then jump straight to <>. [float] [[before-installation]] -=== Before you begin +=== Install the stack yourself + +image::images/apm-architecture-diy.png[Install Elastic APM yourself] -* See the https://www.elastic.co/support/matrix[Elastic Support Matrix] -for information about supported operating systems and product compatibility. +If you'd rather install the stack yourself, first see the https://www.elastic.co/support/matrix[Elastic Support Matrix] for information about supported operating systems and product compatibility. We recommend you use the same version of Elasticsearch, Kibana, and APM Server. -* Verify that your system meets the -https://www.elastic.co/support/matrix#matrix_jvm[minimum JVM requirements] for {es}. -* The following links assume you're using the current version of the Elastic Stack. -If you're not, it's easy to adjust the version of the documentation after you land on each page. -[float] +* <> +* <> +* <> +* <> + [[install-elasticsearch]] -=== Install and run Elasticsearch +=== Step 1: Install Elasticsearch -You'll need to install an Elasticsearch cluster, and make sure it's up and running: +// This will move to tagged regions so we can pull the installation instructions +// here (instead of linking out) -* {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install Elasticsearch] -* {stack-gs}/get-started-elastic-stack.html#_make_sure_elasticsearch_is_up_and_running[Make sure elasticsearch is up and running] +Install an Elasticsearch cluster, start it up, and make sure it's running. + +. Verify that your system meets the +https://www.elastic.co/support/matrix#matrix_jvm[minimum JVM requirements] for {es}. +. {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install Elasticsearch]. +. {stack-gs}/get-started-elastic-stack.html#_make_sure_elasticsearch_is_up_and_running[Make sure elasticsearch is up and running]. -[float] [[install-kibana]] -=== Install and run Kibana +=== Step 2: Install Kibana -Now we'll install Kibana and open up the web interface: +// This will move to tagged regions so we can pull the installation instructions +// here (instead of linking out) -* {stack-gs}/get-started-elastic-stack.html#install-kibana[Install Kibana] -* {stack-gs}/get-started-elastic-stack.html#_launch_the_kibana_web_interface[Launch the Kibana Web Interface] +Install Kibana, start it up, and open up the web interface: + +. {stack-gs}/get-started-elastic-stack.html#install-kibana[Install Kibana]. +. {stack-gs}/get-started-elastic-stack.html#_launch_the_kibana_web_interface[Launch the Kibana Web Interface]. [[apm-server]] -[float] -=== Install and run APM Server +=== Step 3: Install APM Server -You've made it to the fun part - Let's get APM Server up and running: +Install, set up, and run APM Server. -* {apm-server-ref-v}/installing.html[Install APM Server] -* {apm-server-ref-v}/setting-up-and-running.html[Set up and Run APM Server] +. {apm-server-ref-v}/installing.html[Install APM Server]. +. {apm-server-ref-v}/setting-up-and-running.html[Set up and Run APM Server]. -Use the config file if you need to change the default configuration that APM Server uses to connect to Elasticsearch, +Next, use the config file if you need to change the default configuration that APM Server uses to connect to Elasticsearch, or if you need to specify credentials: * {apm-server-ref-v}/configuring-howto-apm-server.html[Configuring APM Server] @@ -91,60 +92,51 @@ please see the full {apm-server-ref-v}/index.html[APM Server documentation]. Load APM dashboards directly in Kibana via the {kibana-ref}/apm-getting-started.html[APM - Getting started] page. [[agents]] -[float] -=== Install and configure APM agents +=== Step 4: Install APM agents Agents are written in the same language as your service. -Currently Elastic APM has agents for Go, Java, Node.js, Python, Ruby, and JavaScript RUM. - -// todo: fix this sentence -Setting up a new service to be monitored requires installing the agent, -and configuring it with the address of your APM Server and the service name. - -NOTE: Check the <> to ensure you're using agents that are compatible with your version of Elasticsearch. +Monitoring a new service requires installing the agent +and configuring it with the address of your APM Server, a secret token (if necessary), and a service name. -[cols="h,,,"] +[cols="h,,"] |======================================================================= |Agent -3+| More information +2+| .2+|Go -3+|The Go agent automatically instruments Gorilla and Gin, and has support for Go’s built-in net/http and database/sql drivers. -|{apm-go-ref}/introduction.html[Introduction] -|{apm-go-ref}/supported-tech.html[Supported technologies] -|{apm-go-ref}/configuration.html[Config] +2+|The Go agent automatically instruments Gorilla and Gin, and has support for Go’s built-in net/http and database/sql drivers. +|{apm-go-ref-v}/supported-tech.html[Supported technologies] +|{apm-go-ref-v}/getting-started.html[Getting started with the Go Agent] .2+|Java -3+|The Java agent automatically instruments Servlet API, Spring MVC, and Spring Boot out of the box. -|{apm-java-ref}/intro.html[Introduction] -|{apm-java-ref}/supported-technologies-details.html[Supported technologies] -|{apm-java-ref}/configuration.html[Config] +2+|The Java agent automatically instruments Servlet API, Spring MVC, and Spring Boot out of the box. +|{apm-java-ref-v}/supported-technologies-details.html[Supported technologies] +|{apm-java-ref-v}/setup.html[Set up the Java Agent] .2+|Node.js -3+|The Node.js agent automatically instruments Express, hapi, Koa, and Restify out of the box. -|{apm-node-ref}/intro.html[Introduction] -|{apm-node-ref}/supported-technologies.html[Supported technologies] -|{apm-node-ref}/configuring-the-agent.html[Config] +2+|The Node.js agent automatically instruments Express, hapi, Koa, and Restify out of the box. +|{apm-node-ref-v}/supported-technologies.html[Supported technologies] +|{apm-node-ref-v}/intro.html#get-started[Get started with the Node.js Agent] .2+|Python -3+|The Python agent automatically instruments Django and Flask out of the box. -|{apm-py-ref}/getting-started.html[Getting Started] -| -|{apm-py-ref}/configuration.html[Config] +2+|The Python agent automatically instruments Django and Flask out of the box. +|{apm-py-ref-v}/supported-technologies.html[Supported technologies] +|{apm-py-ref-v}/getting-started.html[Getting Started with the Python Agent] .2+|Ruby -3+|The Ruby agent automatically instruments Rails out of the box. -|{apm-ruby-ref}/introduction.html[Introduction] -|{apm-ruby-ref}/supported-technologies.html[Supported technologies] -|{apm-ruby-ref}/configuration.html[Config] +2+|The Ruby agent automatically instruments Rails out of the box. +|{apm-ruby-ref-v}/supported-technologies.html[Supported technologies] +|{apm-ruby-ref-v}/introduction.html#framework-support[Getting started with the Ruby Agent] .2+|RUM -3+|Real User Monitoring (RUM) captures user interactions with clients such as web browsers. -|{apm-rum-ref}/intro.html[Introduction] -| -|{apm-rum-ref}/configuration.html[Config] +2+|Real User Monitoring (RUM) captures user interactions with clients such as web browsers. +|{apm-rum-ref-v}/supported-technologies.html[Supported technologies] +|{apm-rum-ref-v}/getting-started.html[Getting started with the RUM Agent] + |======================================================================= +TIP: Check the <> to ensure you're using agents that are compatible with your version of Elasticsearch. + [[choose-service-name]] [float] ==== Choose a service name @@ -159,8 +151,46 @@ Make sure you choose a good service name before you get started. The service name can only contain alphanumeric characters, spaces, underscores, and dashes (must match `^[a-zA-Z0-9 _-]+$`). +[[configure-apm]] +=== Step 5: Configure APM + +Now that you're up and running with Elastic APM, you may want to adjust some configuration settings. +Luckily, there are many different ways to tweak and tune the Elastic ecosystem to adapt it to your needs. + + [float] -=== Next steps +==== Configure APM agents + +// Note about central config will go here +APM agents have a number of configuration options that allow you to fine tune things like +environment names, sampling rates, instrumentations, metrics, and more. + +|=== +|*Agent configuration documentation* +a| + +* {apm-go-ref-v}/configuration.html[Go Agent configuration] +* {apm-java-ref-v}/configuration.html[Java Agent configuration] +* {apm-node-ref}/configuring-the-agent.html[Node.js Agent configuration] +* {apm-py-ref-v}/configuration.html[Python Agent configuration] +* {apm-ruby-ref-v}/configuration.html[Ruby Agent configuration] +* {apm-rum-ref-v}/configuration.html[RUM Agent configuration] +|=== + +[float] +==== Configure Elastic Cloud + +If you're running APM Server in Elastic cloud, you can configure your own user settings right in the Elasticsearch Service Console. +Any changes are automatically appended to the `apm-server.yml` configuration file for your instance. + +Full details are available in the {cloud}/ec-manage-apm-settings.html[APM user settings] documentation. + +[float] +==== Configure a self installation + +If you've installed APM Server yourself, you can edit the `apm-server.yml` configuration file to make changes. +More information is available in {apm-server-ref-v}/configuring-howto-apm-server.html[configuring APM Server]. -You're now up and running with Elastic APM! -Don't forget to check out the <> and <> documentation to gain a deeper understanding of how Elastic APM works. +Don't forget to also read about +{apm-server-ref-v}/securing-apm-server.html[securing APM Server], and +{apm-server-ref-v}/monitoring.html[monitoring APM Server]. diff --git a/docs/guide/kibana-dashboard.png b/docs/guide/kibana-dashboard.png deleted file mode 100644 index 26506d8c6d5..00000000000 Binary files a/docs/guide/kibana-dashboard.png and /dev/null differ diff --git a/docs/guide/opentracing.asciidoc b/docs/guide/opentracing.asciidoc index a00265d8618..3b76e71499c 100644 --- a/docs/guide/opentracing.asciidoc +++ b/docs/guide/opentracing.asciidoc @@ -11,9 +11,9 @@ This means you can reuse your existing OpenTracing instrumentation to quickly an Not all features of the OpenTracing API are supported. In addition, there are some Elastic APM specific tags you should be aware of. Please see the relevant Agent documentation for more detailed information: -* {apm-go-ref}/opentracing.html[Go agent] -* {apm-java-ref}/opentracing-bridge.html[Java agent] -* {apm-node-ref}/opentracing.html[Node.js agent] -* {apm-py-ref}/opentracing-bridge.html[Python agent] -* {apm-ruby-ref}/opentracing.html[Ruby agent] -* {apm-rum-ref}/opentracing.html[JavaScript Real User Monitoring (RUM) agent] \ No newline at end of file +* {apm-go-ref-v}/opentracing.html[Go agent] +* {apm-java-ref-v}/opentracing-bridge.html[Java agent] +* {apm-node-ref-v}/opentracing.html[Node.js agent] +* {apm-py-ref-v}/opentracing-bridge.html[Python agent] +* {apm-ruby-ref-v}/opentracing.html[Ruby agent] +* {apm-rum-ref-v}/opentracing.html[JavaScript Real User Monitoring (RUM) agent] \ No newline at end of file diff --git a/docs/guide/overview.asciidoc b/docs/guide/overview.asciidoc index a83abf0706e..ac056ca27e0 100644 --- a/docs/guide/overview.asciidoc +++ b/docs/guide/overview.asciidoc @@ -2,85 +2,24 @@ == Overview Elastic APM is an application performance monitoring system built on the Elastic Stack. -It allows you to monitor software services and applications in real time, -collecting detailed performance information on response time for incoming requests, -database queries, calls to caches, external HTTP requests, -etc. -This makes it easier to pinpoint and fix performance problems quickly. +It allows you to monitor software services and applications in real time -- +collect detailed performance information on response time for incoming requests, +database queries, calls to caches, external HTTP requests, and more. +This makes it easy to pinpoint and fix performance problems quickly. Elastic APM also automatically collects unhandled errors and exceptions. Errors are grouped based primarily on the stacktrace, -so you can identify new errors as they appear and keep an eye on how many times specific errors happen. +so you can identify new errors as they appear and keep an eye on how many times specific errors happen. -NOTE: This guide will indiscriminately use the word "service" for both services and applications. - -[float] -[[components]] -== APM Components - -Elastic APM consists of four components: - -{apm-agents-ref}/index.html[*APM agents*] are open source libraries written in the same language as your service. -You install them into your service as you would install any other library. -They instrument your code and collect performance data and errors at runtime. -This data is buffered for a short period and sent on to APM Server. - -{apm-server-ref-v}/index.html[*APM Server*] is an open source application written in Go which typically runs on dedicated servers. -It listens on port 8200 by default and receives data from agents through a JSON HTTP API. -Then it creates documents from that data and stores them in Elasticsearch. - -{ref}/index.html[*Elasticsearch*] is a highly scalable open-source full-text search and analytics engine. -It allows you to store, search, and analyze big volumes of data quickly and in near real time. -Elasticsearch is used to store APM performance metrics and make use of its aggregations. - -{kibana-ref}/xpack-apm.html[*Kibana*] is an open source analytics and visualization platform designed to work with Elasticsearch. -You use Kibana to search, view, and interact with data stored in Elasticsearch. -You can use Kibana to visualize APM data by utilizing the dedicated APM UI bundled in Basic license, -or the pre-built, open source, -Kibana dashboards that can be loaded directly via the {kibana-ref}/apm-getting-started.html[APM Kibana UI]. - -image::apm-architecture.png[Architecture of Elastic APM] - -[float] -[[concepts]] -== APM Concepts +Ready to learn more about the Elastic APM ecosystem? Check out these helpful topics: -[float] -=== Events -APM agents capture different types of information from within their instrumented applications, known as events. -Events can be <>, <>, or <>. -These events are then streamed to the APM Server which validates and processes the events. +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> -View the APM <> for more information on events. - -[float] -=== Component communication -The APM Server is a {apm-server-ref-v}/why-separate-component.html[separate component by design] - it helps keep the agents light, -prevents certain security risks, -and improves compatibility across the Elastic and APM Stack. - -The {apm-server-ref-v}/intake-api.html[Intake API] is what we call the internal protocol that APM agents use to talk to the APM Server. -After the APM Server has validated and processed events from the APM agents (via the intake API), -the server transforms the data into Elasticsearch documents and stores them in corresponding {apm-server-ref-v}/exploring-es-data.html[Elasticsearch indices]. -In a matter of seconds you can start viewing your application performance data in Kibana. - -[float] -=== Real User Monitoring (RUM) -Real User Monitoring captures user interaction with clients such as web browsers. -The {apm-rum-ref-v}[JavaScript Agent] is Elastic’s RUM Agent. -To use it you need to {apm-server-ref-v}/rum.html[enable RUM support] in the APM Server. - -Unlike Elastic APM backend agents which monitor requests and responses, -the RUM JavaScript agent monitors the real user experience and interaction within your client-side application. -The RUM JavaScript agent is also framework-agnostic, which means it can be used with any frontend JavaScript application. - -You will be able to measure metrics such as "Time to First Byte", `domInteractive`, -and `domComplete` which helps you discover performance issues within your client-side application as well as issues that relate to the latency of your server-side application. - -[float] -=== Distributed Tracing -Together, transactions and spans form a `Trace`. -Traces are not events, but group together events that have a common root. - -All of our APM agents support <> out of the box. -Distributed tracing enables you to analyze performance throughout your microservices architecture all in one view. +NOTE: This guide will indiscriminately use the word "service" for both services and applications. diff --git a/docs/guide/redirects.asciidoc b/docs/guide/redirects.asciidoc new file mode 100644 index 00000000000..9aef62f4567 --- /dev/null +++ b/docs/guide/redirects.asciidoc @@ -0,0 +1,39 @@ +["appendix",role="exclude",id="redirects"] += Deleted pages + +The following pages do not exist. They may have moved, been deleted, or have not been created yet. + +[role="exclude",id="go-compatibility"] +=== Go Agent Compatibility + +This page has moved. Please see <>. + +[role="exclude",id="java-compatibility"] +=== Java Agent Compatibility + +This page has moved. Please see <>. + +[role="exclude",id="dotnet-compatibility"] +=== .NET Agent Compatibility + +This page has moved. Please see <>. + +[role="exclude",id="nodejs-compatibility"] +=== Node.js Agent Compatibility + +This page has moved. Please see <>. + +[role="exclude",id="python-compatibility"] +=== Python Agent Compatibility + +This page has moved. Please see <>. + +[role="exclude",id="ruby-compatibility"] +=== Ruby Agent Compatibility + +This page has moved. Please see <>. + +[role="exclude",id="rum-compatibility"] +=== RUM Agent Compatibility + +This page has moved. Please see <>. diff --git a/docs/guide/rum.asciidoc b/docs/guide/rum.asciidoc new file mode 100644 index 00000000000..b65fbf26e99 --- /dev/null +++ b/docs/guide/rum.asciidoc @@ -0,0 +1,12 @@ +[[rum]] +== Real User Monitoring (RUM) +Real User Monitoring captures user interaction with clients such as web browsers. +The {apm-rum-ref-v}[JavaScript Agent] is Elastic’s RUM Agent. +To use it you need to {apm-server-ref-v}/rum.html[enable RUM support] in the APM Server. + +Unlike Elastic APM backend agents which monitor requests and responses, +the RUM JavaScript agent monitors the real user experience and interaction within your client-side application. +The RUM JavaScript agent is also framework-agnostic, which means it can be used with any frontend JavaScript application. + +You will be able to measure metrics such as "Time to First Byte", `domInteractive`, +and `domComplete` which helps you discover performance issues within your client-side application as well as issues that relate to the latency of your server-side application. \ No newline at end of file diff --git a/docs/guide/troubleshooting.asciidoc b/docs/guide/troubleshooting.asciidoc new file mode 100644 index 00000000000..12d4108932c --- /dev/null +++ b/docs/guide/troubleshooting.asciidoc @@ -0,0 +1,27 @@ +[[troubleshooting]] +== Troubleshooting + +If you run into trouble, there are three places you can look for help. + +[float] +=== Troubleshooting documentation + +The APM Server and some of the APM agents have troubleshooting guides: + +* {apm-server-ref-v}/troubleshooting.html[Server troubleshooting] +* {apm-java-ref-v}/trouble-shooting.html[Java agent troubleshooting] +* {apm-node-ref-v}/troubleshooting.html[Node.js agent troubleshooting] +* {apm-rum-ref-v}/troubleshooting.html[RUM troubleshooting] + +[float] +=== Elastic Support + +We offer a support experience unlike any other. +Our team of professionals 'speak human and code', and love open source and making your day. +https://www.elastic.co/subscriptions[Learn more about subscriptions]. + +[float] +=== Discussion forum + +For additional questions and feature requests, +visit our https://discuss.elastic.co/c/apm[discussion forum]. \ No newline at end of file