diff --git a/changelogs/7.15.asciidoc b/changelogs/7.15.asciidoc index 64adbbfe59d..cfd6e6fd0fd 100644 --- a/changelogs/7.15.asciidoc +++ b/changelogs/7.15.asciidoc @@ -37,7 +37,7 @@ https://github.com/elastic/apm-server/compare/v7.14.2\...v7.15.0[View commits] - `network.connection_type` is now `network.connection.type` {pull}5671[5671] - `transaction.page` and `error.page` no longer recorded {pull}5872[5872] - experimental:["This breaking change applies to the experimental tail-based sampling feature."] `apm-server.sampling.tail` now requires `apm-server.data_streams.enabled` {pull}5952[5952] -- beta:["This breaking change applies to the beta <>."] The `traces-sampled-*` data stream is now `traces-apm.sampled-*` {pull}5952[5952] +- beta:["This breaking change applies to the beta APM integration."] The `traces-sampled-*` data stream is now `traces-apm.sampled-*` {pull}5952[5952] [float] ==== Bug fixes diff --git a/changelogs/8.0.asciidoc b/changelogs/8.0.asciidoc index 1afd7b8547e..6e17fa4daca 100644 --- a/changelogs/8.0.asciidoc +++ b/changelogs/8.0.asciidoc @@ -177,7 +177,7 @@ No significant changes. ==== Breaking Changes * APM Server now responds with 403 (HTTP) and PermissionDenied (gRPC) for authenticated but unauthorized requests {pull}5545[5545] * `sourcemap.error` and `sourcemap.updated` are no longer set due to failing to find a matching source map {pull}5631[5631] -* experimental:["This breaking change applies to the experimental <>."] Removed `service.name` from dataset {pull}5451[5451] +* experimental:["This breaking change applies to the experimental APM integration."] Removed `service.name` from dataset {pull}5451[5451] // [float] // ==== Bug fixes diff --git a/docs/apm-components.asciidoc b/docs/apm-components.asciidoc deleted file mode 100644 index c8f27e7c08e..00000000000 --- a/docs/apm-components.asciidoc +++ /dev/null @@ -1,91 +0,0 @@ -[[apm-components]] -== Components and documentation - -**** -There are two ways to install, run, and manage Elastic APM: - -* With the Elastic APM integration -* With the standalone (legacy) APM Server binary - -This documentation focuses on option one: the **Elastic APM integration**. -**** - -Elastic APM consists of four components: *APM agents*, the *Elastic APM integration*, *{es}*, and *{kib}*. -Generally, there are two ways that these four components can work together: - -APM agents on edge machines send data to a centrally hosted APM integration: - -[subs=attributes+] -include::./diagrams/apm-architecture-central.asciidoc[Elastic APM architecture with edge APM integrations] - -Or, APM agents and the APM integration live on edge machines and enroll via a centrally hosted {agent}: - -[subs=attributes+] -include::./diagrams/apm-architecture-edge.asciidoc[Elastic APM architecture with central APM integration] - -In addition, Elastic supports OpenTelemetry: - -[subs=attributes+] -include::./diagrams/apm-otel-architecture.asciidoc[Architecture of Elastic APM with OpenTelemetry] - -// Not sure which to choose? See the [blog post] - -[float] -=== APM Agents - -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: - -* {apm-go-ref-v}/introduction.html[Go agent] -* {apm-ios-ref-v}/intro.html[iOS agent] -* {apm-java-ref-v}/intro.html[Java agent] -* {apm-dotnet-ref-v}/intro.html[.NET agent] -* {apm-node-ref-v}/intro.html[Node.js agent] -* {apm-php-ref-v}/intro.html[PHP 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-integration]] -=== Elastic APM integration - -The APM integration receives performance data from your APM agents, -validates and processes it, and then transforms the data into {es} documents. -Removing this logic from APM agents help keeps them light, prevents certain security risks, -and improves compatibility across the {stack}. - -The Elastic integration runs on {fleet-guide}[{agent}]. {agent} is a single, unified way to add monitoring for logs, -metrics, traces, and other types of data to each host. -A single agent makes it easier and faster to deploy monitoring across your infrastructure. -The agent's single, unified policy makes it easier to add integrations for new data sources. - -[float] -=== {es} - -{ref}/index.html[{es}] is a highly scalable free and open full-text search and analytics engine. -It allows you to store, search, and analyze large volumes of data quickly and in near real time. -{es} is used to store APM performance metrics and make use of its aggregations. - -[float] -=== {kib} {apm-app} - -{kibana-ref}/index.html[{kib}] is a free and open analytics and visualization platform designed to work with {es}. -You use {kib} to search, view, and interact with data stored in {es}. - -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[{apm-app}] in {kib}. -The following sections will help you get started: - -* {apm-app-ref}/apm-ui.html[Set up] -* {apm-app-ref}/apm-getting-started.html[Get started] -* {apm-app-ref}/apm-how-to.html[How-to guides] - -APM also has built-in integrations with {ml-cap}. To learn more about this feature, -or the {anomaly-detect} feature that's built on top of it, -refer to {kibana-ref}/machine-learning-integration.html[{ml-cap} integration]. diff --git a/docs/apm-overview.asciidoc b/docs/apm-overview.asciidoc index 299726c529c..3ffa3ebb380 100644 --- a/docs/apm-overview.asciidoc +++ b/docs/apm-overview.asciidoc @@ -22,6 +22,5 @@ like JVM metrics in the Java Agent, and Go runtime metrics in the Go Agent. [float] === Give Elastic APM a try -Learn more about the <> that make up Elastic APM -// , -// or jump right into the <>. +Use the <> to quickly spin up an APM deployment. +Want to host everything yourself instead? See <>. \ No newline at end of file diff --git a/docs/apm-quick-start.asciidoc b/docs/apm-quick-start.asciidoc index 8b6c1e20e4f..62cf252e561 100644 --- a/docs/apm-quick-start.asciidoc +++ b/docs/apm-quick-start.asciidoc @@ -1,9 +1,23 @@ [[apm-quick-start]] -== Quick start +== Quick start with {ecloud} -// * Point to EA APT/YUM -// * Point to EA for running on Docker -// * Point to EA for directory layout -// * Point to EA for systemd +The easiest way to get started with Elastic APM is by using our +{ess-product}[hosted {es} Service] on {ecloud}. +The {es} Service is available on AWS, GCP, and Azure. +The {es} Service provisions the following components of the {stack}: + +* *{es}* -- A highly scalable free and open full-text search and analytics engine. +* *{kib}* -- An analytics and visualization platform designed to work with {es}. +* *Integrations Server* -- A combined *APM Server* and *Fleet-managed {agent}*. +** *APM Server* -- An application that receives, processes, and validates performance data from your APM agents. +** *Fleet-managed {agent}* -- A server that runs Fleet Server and provides a control plane for easily configuring and updating APM and other integrations. + +Don't worry--in order to get started, +you don't need to understand how all of these pieces work together! +When you use our hosted {es} Service, +simply spin-up your instance and point your *APM agents* towards it. + +[float] +== What will I learn in this guide? include::{obs-repo-dir}/observability/ingest-traces.asciidoc[tag=apm-quick-start] diff --git a/docs/configure/outputs/elasticsearch.asciidoc b/docs/configure/outputs/elasticsearch.asciidoc index 1766f4161c9..f39e7c818b9 100644 --- a/docs/configure/outputs/elasticsearch.asciidoc +++ b/docs/configure/outputs/elasticsearch.asciidoc @@ -320,7 +320,7 @@ output.elasticsearch: pipeline: my_pipeline_id ------------------------------------------------------------------------------ -For more information, see <>. +For more information, see <>. You can set the ingest node pipeline dynamically by using a format string to access any event field. For example, this configuration uses a custom field, @@ -410,7 +410,7 @@ With this configuration, all events with `log_type: critical` are sent to `sev2_pipeline`, and all other events are sent to `sev3_pipeline`. For more information about ingest node pipelines, see -<>. +<>. endif::[] diff --git a/docs/diagrams/apm-decision-tree.asciidoc b/docs/diagrams/apm-decision-tree.asciidoc new file mode 100644 index 00000000000..f169b8d9340 --- /dev/null +++ b/docs/diagrams/apm-decision-tree.asciidoc @@ -0,0 +1,51 @@ +++++ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+++++ \ No newline at end of file diff --git a/docs/images/bin-ov.png b/docs/images/bin-ov.png new file mode 100644 index 00000000000..7702dd7d765 Binary files /dev/null and b/docs/images/bin-ov.png differ diff --git a/docs/images/fm-ov.png b/docs/images/fm-ov.png new file mode 100644 index 00000000000..7aace8b2873 Binary files /dev/null and b/docs/images/fm-ov.png differ diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index af6d2ef65e5..98bc4bf8f0f 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -60,11 +60,9 @@ endif::[] include::apm-overview.asciidoc[] -include::apm-components.asciidoc[] - include::apm-quick-start.asciidoc[] -include::./legacy/setting-up-and-running.asciidoc[] +include::./legacy/getting-started-apm-server.asciidoc[] include::data-model.asciidoc[] @@ -80,6 +78,8 @@ include::input-apm.asciidoc[] include::configure/index.asciidoc[leveloffset=+1] +include::./legacy/setting-up-and-running.asciidoc[] + include::secure-comms.asciidoc[] include::monitor-apm-server.asciidoc[] @@ -92,45 +92,4 @@ include::upgrading.asciidoc[] include::release-notes.asciidoc[leveloffset=+1] -// TODO: Figure out if it's safe to remove everything between the *'s -// ******************************************************** -// ******************************************************** -:apm-ref-all: https://www.elastic.co/guide/en/apm/get-started/ - -// Overwrite links to the APM Overview and APM Server Ref. Point to APM Guide instead. -:apm-overview-ref-v: {apm-guide-ref} -:apm-guide-ref: {apm-guide-ref} -:apm-server-ref-v: {apm-guide-ref} -:apm-server-ref: {apm-guide-ref} -// ******************************************************** -// ******************************************************** - - -// Legacy APM Server Reference -// include::legacy/index.asciidoc[] - -// ifndef::apm-integration-docs[] -// [[apm-server]] -// = APM Server Reference -// endif::[] - -// ifdef::apm-integration-docs[] -// Overwrite links to the APM Overview and APM Server Ref. Point to APM Guide instead. -:apm-overview-ref-v: {apm-guide-ref} -:apm-guide-ref: {apm-guide-ref} -:apm-server-ref-v: {apm-guide-ref} -:apm-server-ref: {apm-guide-ref} - -// [[overview]] -// = Legacy APM Server Reference - -== BEGIN "LEGACY" REFERENCE - -include::./legacy/overview.asciidoc[] -// endif::[] - -include::./legacy/getting-started-apm-server.asciidoc[] - -// include::./legacy/breaking-changes.asciidoc[leveloffset=+1] - include::./legacy/redirects.asciidoc[] diff --git a/docs/legacy/copied-from-beats/docs/command-reference.asciidoc b/docs/legacy/copied-from-beats/docs/command-reference.asciidoc index 10dfcde31a2..ebad6878dd7 100644 --- a/docs/legacy/copied-from-beats/docs/command-reference.asciidoc +++ b/docs/legacy/copied-from-beats/docs/command-reference.asciidoc @@ -748,7 +748,7 @@ template, {ilm-init} policy, and write alias (if supported and configured). ifdef::apm-server[] *`--pipelines`*:: -Registers the <> definitions set in `ingest/pipeline/definition.json`. +Registers the <> definitions set in `ingest/pipeline/definition.json`. endif::apm-server[] *`--template`*:: diff --git a/docs/legacy/copied-from-beats/docs/repositories.asciidoc b/docs/legacy/copied-from-beats/docs/repositories.asciidoc index b5fa159796e..5bf4676f9ab 100644 --- a/docs/legacy/copied-from-beats/docs/repositories.asciidoc +++ b/docs/legacy/copied-from-beats/docs/repositories.asciidoc @@ -10,7 +10,7 @@ ////////////////////////////////////////////////////////////////////////// [[setup-repositories]] -=== Repositories for APT and YUM +==== Repositories for APT and YUM We have repositories available for APT and YUM-based distributions. Note that we provide binary packages, but no source packages. @@ -23,7 +23,7 @@ We use the PGP key https://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88 to sign all our packages. It is available from https://pgp.mit.edu. [float] -==== APT +===== APT ifeval::["{release-state}"=="unreleased"] @@ -103,7 +103,7 @@ sudo systemctl enable {beatname_pkg} endif::[] [float] -==== YUM +===== YUM ifeval::["{release-state}"=="unreleased"] diff --git a/docs/legacy/copied-from-beats/docs/shared-docker.asciidoc b/docs/legacy/copied-from-beats/docs/shared-docker.asciidoc index 6b720167db7..adc62f7a7a9 100644 --- a/docs/legacy/copied-from-beats/docs/shared-docker.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-docker.asciidoc @@ -1,5 +1,5 @@ [[running-on-docker]] -=== Run {beatname_uc} on Docker +==== Run {beatname_uc} on Docker Docker images for {beatname_uc} are available from the Elastic Docker registry. The base image is https://hub.docker.com/_/centos/[centos:7]. @@ -15,7 +15,7 @@ https://www.elastic.co/subscriptions[Subscriptions] page for information about Elastic license levels. [float] -==== Pull the image +===== Pull the image Obtaining {beatname_uc} for Docker is as simple as issuing a +docker pull+ command against the Elastic Docker registry. @@ -39,7 +39,7 @@ endif::[] ifndef::apm-server[] [float] -==== Run the {beatname_uc} setup +===== Run the {beatname_uc} setup Running {beatname_uc} with the setup command will create the index pattern and load visualizations @@ -125,7 +125,7 @@ using this syntax: endif::apm-server[] [float] -==== Configure {beatname_uc} on Docker +===== Configure {beatname_uc} on Docker The Docker image provides several methods for configuring {beatname_uc}. The conventional approach is to provide a configuration file via a volume mount, but @@ -133,7 +133,7 @@ it's also possible to create a custom image with your configuration included. [float] -===== Example configuration file +====== Example configuration file Download this example configuration file as a starting point: @@ -143,7 +143,7 @@ curl -L -O {dockerconfig} ------------------------------------------------ [float] -===== Volume-mounted configuration +====== Volume-mounted configuration One way to configure {beatname_uc} on Docker is to provide +{beatname_lc}.docker.yml+ via a volume mount. With +docker run+, the volume mount can be specified like this. @@ -261,7 +261,7 @@ the `-E output.elasticsearch.hosts` line with the Cloud ID and elastic password using the syntax shown earlier. [float] -===== Customize your configuration +====== Customize your configuration ifdef::has_docker_label_ex[] The +{beatname_lc}.docker.yml+ file you downloaded earlier is configured to deploy {beats} modules based on the Docker labels applied to your containers. See <> for more details. Add labels to your application Docker containers, and they will be picked up by the {beats} autodiscover feature when they are deployed. Here is an example command for an Apache HTTP Server container with labels to configure the {filebeat} and {metricbeat} modules for the Apache HTTP Server: @@ -287,7 +287,7 @@ The +{beatname_lc}.docker.yml+ downloaded earlier should be customized for your endif::[] [float] -===== Custom image configuration +====== Custom image configuration It's possible to embed your {beatname_uc} configuration in a custom image. Here is an example Dockerfile to achieve this: diff --git a/docs/legacy/getting-started-apm-server.asciidoc b/docs/legacy/getting-started-apm-server.asciidoc index 55718d6e38a..06a7f3d1471 100644 --- a/docs/legacy/getting-started-apm-server.asciidoc +++ b/docs/legacy/getting-started-apm-server.asciidoc @@ -1,34 +1,155 @@ [[getting-started-apm-server]] -== Getting started with APM Server +== Self manage APM Server ++++ -Get started +Self manage APM Server ++++ +TIP: The easiest way to get started with Elastic APM is by using our +{ess-product}[hosted {es} Service] on {ecloud}. +The {es} Service is available on AWS, GCP, and Azure. +See <> to get started in minutes. + +// TODO: MOVE THIS IMPORTANT: Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage APM index templates, {ilm-init} policies, and ingest pipelines. APM Server will only send data to {es} _after_ the APM integration has been installed. -The easiest way to get started with Elastic APM is by using our -{ess-product}[hosted {es} Service] on {ecloud}. -The {es} Service is available on AWS, GCP, and Azure, -and automatically configures APM Server to work with {es} and {kib}. +The APM Server receives performance data from your APM agents, +validates and processes it, and then transforms the data into {es} documents. +If you're on this page, then you've chosen to self-manage the Elastic Stack, +and you now must decide how to run and configure the APM Server. +There are two options, and the components required are different for each: + +* **<>** +* **<>** +// * **<>** [float] -=== Hosted {es} Service +[[setup-apm-server-binary]] +=== APM Server binary + +Install, configure, and run the APM Server binary wherever you need it. + +image::./images/bin-ov.png[APM Server binary overview] + +**Pros**: + +- Simplest self-managed option +- No addition component knowledge required +- YAML configuration simplifies automation + +**Supported outputs**: + +- {es} +- {ess} +- {ls} +- Kafka +- Redis +- File +- Console + +**Required components**: + +- APM agents +- APM Server +- {stack} + +**Configuration method**: YAML + +[float] +[[setup-fleet-managed-apm]] +=== Fleet-managed APM Server + +Fleet is a web-based UI in {kib} that is used to centrally manage {agent}s. +In this deployment model, use {agent} to spin up APM Server instances that can be centrally-managed in a custom-curated user interface. + +NOTE: Fleet-managed APM Server does not have full feature parity with the APM Server binary method of running Elastic APM. -Skip managing your own {es}, {kib}, and APM Server by using our -{ess-product}[hosted {es} Service] on -{ecloud}. +image::./images/fm-ov.png[APM Server fleet overview] -image::images/apm-architecture-cloud.png[Install Elastic APM on cloud] +// (outputs, stable APIs) +// not the best option for a simple test setup or if only interested in centrally running APM Server -{ess-trial}[Try out the {es} Service for free], -then see {cloud}/ec-manage-apm-settings.html[Add APM user settings] for information on how to configure Elastic APM. +**Pros**: + +- Conveniently manage one, some, or many different integrations from one central {fleet} UI. + +**Supported outputs**: + +- {es} +- {ess} + +**Required components**: + +- APM agents +- APM Server +- {agent} +- Fleet Server +- {stack} + +**Configuration method**: {kib} UI + +// [float] +// [[setup-apm-server-ea]] +// === Standalone Elastic Agent-managed APM Server +// // I really don't know how to sell this option +// Instead of installing and configuring the APM Server binary, let {agent} orchestrate it for you. +// Install {agent} and manually configure the agent locally on the system where it's installed. +// You are responsible for managing and upgrading {agent}. This approach is recommended for advanced users only. + +// **Pros**: + +// - Easily add integrations for other data sources +// useful if EA already in place for other integrations, and customers want to customize setup rather than using Fleet for configuration +// // TODO: +// // maybe get some more hints on this one from the EA team to align with highlighting the same pros & cons. + +// **Available on Elastic Cloud**: ❌ + +// This supports all of the same outputs as binary +// see https://github.com/elastic/apm-server/issues/10467 +// **Supported outputs**: + +// **Configuration method**: YAML + +// image::./images/ea-ov.png[APM Server ea overview] + +// @simitt's notes for how to include EA-managed in the decision tree: +// **** +// If we generally describe Standalone Elastic Agent managed APM Server then we should also add it to this diagram: +// Do you want to use other integrations? +// -> yes: Would you like to use the comfort of Fleet UI based management? -> yes: Fleet managed APM Server; -> no: Standalone Elastic Agent managed APM Server +// -> no: What is your prefered way of configuration? -> yaml: APM Server binary; -> Kibana UI: Fleet managed APM Server +// **** + +// Components required: + +// [options="header"] +// |==== +// | Installation method | APM Server | Elastic Agent | Fleet Server +// | APM Server binary | ✔️ | | +// // | Standalone Elastic Agent-managed APM Server | ✔️ | ✔️ | +// | Fleet-managed APM Server | ✔️ | ✔️ | ✔️ +// |==== [float] -=== Install and manage the stack yourself +=== Help me decide + +Use the decision tree below to help determine which method of configuring and running the APM Server is best for your use case. -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. +[subs=attributes+] +include::../diagrams/apm-decision-tree.asciidoc[APM Server decision tree] + + +=== APM Server binary + +This guide will explain how to set up and configure the APM Server binary. + +[float] +==== Prerequisites + +// tag::prereq[] +First, see the https://www.elastic.co/support/matrix[Elastic Support Matrix] for information about supported operating systems and product compatibility. You'll need: @@ -36,25 +157,18 @@ You'll need: * *{kib}* for visualizing with the APM UI. We recommend you use the same version of {es}, {kib}, and APM Server. - -image::images/apm-architecture-diy.png[Install Elastic APM yourself] - See {stack-ref}/installing-elastic-stack.html[Installing the {stack}] for more information about installing these products. -After installing the {stack}, read the following topics to learn how to install, -configure, and start APM Server: +// end::prereq[] -* <> -* <> -* <> -* <> +image::images/apm-architecture-diy.png[Install Elastic APM yourself] // ******************************************************* // STEP 1 // ******************************************************* [[installing]] -=== Step 1: Install +==== Step 1: Install NOTE: *Before you begin*: If you haven't installed the {stack}, do that now. See {stack-ref}/installing-elastic-stack.html[Learn how to install the @@ -189,16 +303,16 @@ See <> for deploying Docker containers. // ******************************************************* [[apm-server-configuration]] -=== Step 2: Set up and configure +==== Step 2: Set up and configure [float] -==== {ecloud} +===== {ecloud} If you're running APM in Elastic cloud, see {cloud}/ec-manage-apm-settings.html[Add APM user settings] for information on how to configure Elastic APM. [float] -==== Self installation +===== Self installation // This content is reused in the upgrading guide // tag::why-apm-integration[] @@ -207,7 +321,7 @@ Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage // end::why-apm-integration[] [float] -===== Install the APM integration +====== Install the APM integration // This content is reused in the upgrading guide // tag::install-apm-integration[] @@ -224,7 +338,7 @@ See {fleet-guide}/air-gapped.html[Air-gapped environments] for more information. // end::install-apm-integration[] [float] -===== Configure APM +====== Configure APM Configure APM by editing the `apm-server.yml` configuration file. The location of this file varies by platform--see the <> for help locating it. @@ -247,14 +361,14 @@ The user provided here needs the privileges required to publish events to {es}. To create a dedicated user for this role, see <>. All available configuration options are outlined in -{apm-server-ref-v}/configuring-howto-apm-server.html[configuring APM Server]. +{apm-guide-ref}/configuring-howto-apm-server.html[configuring APM Server]. // ******************************************************* // STEP 3 // ******************************************************* [[apm-server-starting]] -=== Step 3: Start +==== Step 3: Start In a production environment, you would put APM Server on its own machines, similar to how you run {es}. @@ -283,7 +397,7 @@ You can change the defaults in `apm-server.yml` or by supplying a different addr [float] [[running-deb-rpm]] -==== Debian Package / RPM +===== Debian Package / RPM For Debian package and RPM installations, we recommend the `apm-server` process runs as a non-root user. Therefore, these installation methods create an `apm-server` user which you can use to start the process. @@ -305,7 +419,7 @@ See the <> for a full directory layout // ******************************************************* [[next-steps]] -=== Step 4: Next steps +==== Step 4: Next steps // Use a tagged region to pull APM Agent information from the APM Overview If you haven't already, you can now install APM Agents in your services! @@ -330,3 +444,61 @@ include::{libbeat-dir}/repositories.asciidoc[] // Shared docker include::{libbeat-dir}/shared-docker.asciidoc[] + + +=== Fleet-managed APM Server + +This guide will explain how to set up and configure a Fleet-managed APM Server. + +[float] +==== Prerequisites + +You need {es} for storing and searching your data, and {kib} for visualizing and managing it. +When setting these components up, you need: + +include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/prereq.asciidoc[tag=self-managed] + +==== Step 1: Set up Fleet + +Use {fleet} in {kib} to get APM data into the {stack}. +The first time you use {fleet}, you'll need to set it up and add a +{fleet-server}: + +include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc[tag=self-managed] + +For more information, refer to {fleet-guide}/fleet-server.html[{fleet-server}]. + +==== Step 2: Add and configure the APM integration + +include::{obs-repo-dir}/observability/tab-widgets/add-apm-integration/content.asciidoc[tag=self-managed] + +==== Step 3: Install APM agents + +APM agents are written in the same language as your service. +To monitor a new service, you must install the agent and configure it with a service name, +APM Server host, and Secret token. + +* **Service name**: The APM integration maps an instrumented service's name–defined in each {apm-agent}'s configuration– +to the index that its data is stored in {es}. +Service names are case-insensitive and must be unique. +For example, you cannot have a service named `Foo` and another named `foo`. +Special characters will be removed from service names and replaced with underscores (`_`). + +* **APM Server URL**: The host and port that APM Server listens for events on. +This should match the host and port defined when setting up the APM integration. + +* **Secret token**: Authentication method for {apm-agent} and APM Server communication. +This should match the secret token defined when setting up the APM integration. + +TIP: You can edit your APM integration settings if you need to change the APM Server URL +or secret token to match your APM agents. + +include::./tab-widgets/install-agents-widget.asciidoc[] + +==== Step 4: View your data + +Back in {kib}, under {observability}, select APM. +You should see application performance monitoring data flowing into the {stack}! + +[role="screenshot"] +image::./guide/images/kibana-apm-sample-data.png[{apm-app} with data] diff --git a/docs/legacy/guide/images/kibana-apm-sample-data.png b/docs/legacy/guide/images/kibana-apm-sample-data.png new file mode 100644 index 00000000000..7aeb5f1ac37 Binary files /dev/null and b/docs/legacy/guide/images/kibana-apm-sample-data.png differ diff --git a/docs/legacy/tab-widgets/spin-up-stack.asciidoc b/docs/legacy/tab-widgets/spin-up-stack.asciidoc index 2c65a88d027..19dc1b9aa5a 100644 --- a/docs/legacy/tab-widgets/spin-up-stack.asciidoc +++ b/docs/legacy/tab-widgets/spin-up-stack.asciidoc @@ -30,7 +30,7 @@ Next, install, 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 {es}, or if you need to specify credentials: -* {apm-server-ref-v}/configuring-howto-apm-server.html[Configuring APM Server] +* {apm-guide-ref}/configuring-howto-apm-server.html[Configuring APM Server] ** {apm-server-ref-v}/configuration-process.html[General configuration options] ** {apm-server-ref-v}/configuring-output.html[Configure the {es} output] diff --git a/docs/overview.asciidoc b/docs/overview.asciidoc deleted file mode 100644 index 472f600d65a..00000000000 --- a/docs/overview.asciidoc +++ /dev/null @@ -1,28 +0,0 @@ -[[apm-overview]] -== Free and open application performance monitoring - -++++ -What is APM? -++++ - -Elastic APM is an application performance monitoring system built on the {stack}. -It allows you to monitor software services and applications in real-time, by -collecting 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 stack trace, -so you can identify new errors as they appear and keep an eye on how many times specific errors happen. - -Metrics are another vital source of information when debugging production systems. -Elastic APM agents automatically pick up basic host-level metrics and agent-specific metrics, -like JVM metrics in the Java Agent, and Go runtime metrics in the Go Agent. - -[float] -=== Give Elastic APM a try - -Learn more about the <> that make up Elastic APM, -or jump right into the <>. - -NOTE: These docs will indiscriminately use the word "service" for both services and applications.