From e25b5e7e7003143caefcd90ad603356ba92b4d81 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Thu, 18 Mar 2021 17:00:42 -0700 Subject: [PATCH] docs: Add additional APM integration information (#4969) (#4970) --- docs/apm-package/apm-integration.asciidoc | 25 ++++----- docs/apm-package/configure.asciidoc | 51 +++++++++++++++++++ docs/apm-package/data-streams.asciidoc | 3 +- docs/apm-package/input-apm.asciidoc | 7 ++- .../docs/howto/load-index-templates.asciidoc | 2 +- .../docs/template-config.asciidoc | 2 +- docs/getting-started-apm-server.asciidoc | 2 +- 7 files changed, 71 insertions(+), 21 deletions(-) create mode 100644 docs/apm-package/configure.asciidoc diff --git a/docs/apm-package/apm-integration.asciidoc b/docs/apm-package/apm-integration.asciidoc index 20a3ffe5614..d99d3da4a97 100644 --- a/docs/apm-package/apm-integration.asciidoc +++ b/docs/apm-package/apm-integration.asciidoc @@ -19,11 +19,8 @@ When {agent} is assigned a policy with an APM input, Ready to jump in? Read through the <>, then head over to the -// Quick start guide: {fleet-guide}/getting-started-traces.html[Get application traces into the {stack}]. -// To do: this link will be uncommented when the other PR has been merged +quick start guide: {fleet-guide}/fleet-quick-start-traces.html[Get application traces into the {stack}]. -// is there a better name for this section? -// should I just group it into the limitations section? [discrete] [[apm-integration-architecture]] === Architecture @@ -50,14 +47,14 @@ Onboarding:: APM Server no longer writes an onboarding document when setting up. Incompatible with `apm_user` role:: -The built-in `apm_user` role is not compatible with the APM integration +The built-in {ref}/built-in-roles.html[`apm_user`] role is not compatible with the APM integration as it only provides read access to `apm-*` indices. The new data stream naming scheme does not follow this pattern, so users with the `apm_user` role will not be able to view `apm` data. - -// to do: link to {kibana-ref}/apm-app-users.html[users and roles] -// provide workaround for creating a new role that provides access to -// logs-*-*, metrics-*-*, and traces-*-* ++ +To grant a user access to APM data in Kibana, provide read access to the relevant +indices listed in <>. You may also wish to grant users +{kibana-ref}/apm-app-users.html[additional privileges] for features like spaces and machine learning. Standalone mode:: {fleet-guide}/run-elastic-agent-standalone.html[Standalone mode] is not currently supported. @@ -77,13 +74,13 @@ You must enroll a new {agent} to use the integration. Agents:: -// to do: add links to these docs {agent} and APM agents are different components: + -**{agent}** is a single, unified agent that you can deploy to hosts or containers to collect data and send it to the {stack}. +{fleet-guide}/fleet-overview.html[**{agent}**] is a single, +unified agent that you can deploy to hosts or containers to collect data and send it to the {stack}. Behind the scenes, {agent} runs APM Server to listen for `apm` data. + -**APM agents** are open source libraries written in the same language as your service. +{apm-overview-ref-v}/components.html[**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. @@ -122,6 +119,4 @@ include::./data-streams.asciidoc[] include::./input-apm.asciidoc[] -// to do: include section on RUM source map uploading - -// to do: include section on updating templates, pipelines, and index lifecycle management +include::./configure.asciidoc[] diff --git a/docs/apm-package/configure.asciidoc b/docs/apm-package/configure.asciidoc new file mode 100644 index 00000000000..4f54ea54be5 --- /dev/null +++ b/docs/apm-package/configure.asciidoc @@ -0,0 +1,51 @@ +[[apm-integration-configure]] +== Configure APM integration + +++++ +Configure +++++ + +experimental::[] + +Templates, pipelines, index lifecycle management, etc., +cannot be configured with APM Server or Fleet, and must instead be configured in {kib} or with +{es} APIs. + +[[apm-integration-templates]] +=== Index templates + +The APM integration loads default index templates into {es}. +These templates configure the APM data stream indices. +To view and edit these templates in {kib}, +select *Stack Management* / *Index Management* / *Index Templates*. +Search for `apm`. + +See {ref}/index-templates.html[index templates] for more information. + +[[apm-integration-pipelines]] +=== Pipelines + +The APM integration loads default ingest node pipelines into {es}. +These pipelines preprocess and enrich APM documents before indexing them. +To view and edit these pipelines in {kib}, +select *Stack Management* / *Index Node Pipelines*. +Search for `apm`. + +See {ref}/ingest.html[ingest node pipelines] for more information. + +[[apm-integration-ilm]] +=== Index lifecycle management (ILM) + +The index lifecycle management (ILM) feature in {es} allows you to automate the +lifecycle of your APM Server indices as they grow and age. +ILM is enabled by default, and a default policy is applied to all APM indices. + +To view and edit these index lifecycle policies in {kib}, +select *Stack Management* / *Index Lifecycle Management*. +Search for `apm`. + +See {ref}/getting-started-index-lifecycle-management.html[manage the index lifecycle] for more information. + +// to do +// [[apm-integration-sourcemaps]] +// === RUM Source maps diff --git a/docs/apm-package/data-streams.asciidoc b/docs/apm-package/data-streams.asciidoc index 70d9b46d267..2add00f17d2 100644 --- a/docs/apm-package/data-streams.asciidoc +++ b/docs/apm-package/data-streams.asciidoc @@ -5,8 +5,7 @@ experimental::[] {agent} uses data streams to store append-only time series data across multiple indices while giving users a single named resource for requests. -If you're new to data streams, see the [Fleet user guide] to learn more. -// to do: add a link to the Fleet user guide data stream docs +If you're new to data streams, see the {fleet-guide}/data-streams.html[Fleet user guide] to learn more. `apm` input data is divided into three types: diff --git a/docs/apm-package/input-apm.asciidoc b/docs/apm-package/input-apm.asciidoc index 92894340634..2a97575641e 100644 --- a/docs/apm-package/input-apm.asciidoc +++ b/docs/apm-package/input-apm.asciidoc @@ -3,9 +3,13 @@ [[input-apm]] == APM input settings +++++ +Input settings +++++ + experimental::[] -To configure the APM integration, open {kib} and select: +To edit the APM integration input settings, open {kib} and select: **Fleet** / **Integrations** / **Elastic APM** / **Add Elastic APM**. Expand the carrot to view all settings. @@ -15,6 +19,7 @@ A limited number of settings are currently supported. ==== Templates, pipelines, index lifecycle management, etc., cannot be configured with APM Server or Fleet, and must instead be configured with {kib} or {es}. +<>. // Configuration via the `apm-server.yml` file is no longer supported. ==== diff --git a/docs/copied-from-beats/docs/howto/load-index-templates.asciidoc b/docs/copied-from-beats/docs/howto/load-index-templates.asciidoc index e8c6cf6f1eb..885432a2671 100644 --- a/docs/copied-from-beats/docs/howto/load-index-templates.asciidoc +++ b/docs/copied-from-beats/docs/howto/load-index-templates.asciidoc @@ -1,7 +1,7 @@ [id="{beatname_lc}-template"] == Load the {es} index template -{es} uses {ref}/indices-templates.html[index templates] to define: +{es} uses {ref}/index-templates.html[index templates] to define: * Settings that control the behavior of your indices. The settings include the lifecycle policy used to manage indices as they grow and age. diff --git a/docs/copied-from-beats/docs/template-config.asciidoc b/docs/copied-from-beats/docs/template-config.asciidoc index 44dfd6d8194..5699a46dd76 100644 --- a/docs/copied-from-beats/docs/template-config.asciidoc +++ b/docs/copied-from-beats/docs/template-config.asciidoc @@ -7,7 +7,7 @@ ++++ The `setup.template` section of the +{beatname_lc}.yml+ config file specifies -the {ref}/indices-templates.html[index template] to use for setting +the {ref}/index-templates.html[index template] to use for setting mappings in Elasticsearch. If template loading is enabled (the default), {beatname_uc} loads the index template automatically after successfully connecting to Elasticsearch. diff --git a/docs/getting-started-apm-server.asciidoc b/docs/getting-started-apm-server.asciidoc index f737d232034..79ea4b95e21 100644 --- a/docs/getting-started-apm-server.asciidoc +++ b/docs/getting-started-apm-server.asciidoc @@ -238,7 +238,7 @@ Full details are available in the {cloud}/ec-manage-apm-settings.html[APM user s It is recommend that you run the `setup` command before starting {beatname_uc}. The `setup` command sets up the initial environment, including the Elasticsearch index template, -and ILM write alias. In Elasticsearch, {ref}/indices-templates.html[index templates] +and ILM write alias. In Elasticsearch, {ref}/index-templates.html[index templates] are used to define field settings and mappings. IMPORTANT: The {kibana-ref}/xpack-apm.html[Kibana APM UI] relies on specific mappings.