From 2a4e66d01bb6f3c41347f10651506ec7a9c647c3 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Fri, 29 Oct 2021 16:02:38 -0700 Subject: [PATCH] docs: link to new APM book (#1850) --- .../get-started-docker.asciidoc | 75 +++++++++---------- docs/en/glossary/glossary.asciidoc | 8 +- docs/en/install-upgrade/breaking.asciidoc | 11 ++- docs/en/install-upgrade/index.asciidoc | 2 +- .../install-upgrade/installing-stack.asciidoc | 5 +- docs/en/install-upgrade/overview.asciidoc | 2 +- .../install-upgrade/upgrading-stack.asciidoc | 3 +- 7 files changed, 49 insertions(+), 57 deletions(-) diff --git a/docs/en/getting-started/get-started-docker.asciidoc b/docs/en/getting-started/get-started-docker.asciidoc index 732e32c30..e7f8ff591 100644 --- a/docs/en/getting-started/get-started-docker.asciidoc +++ b/docs/en/getting-started/get-started-docker.asciidoc @@ -1,23 +1,23 @@ [[get-started-docker]] == Running the {stack} on Docker -The Elastic Docker registry contains Docker images for all the products in +The Elastic Docker registry contains Docker images for all the products in the {stack}: https://www.docker.elastic.co/. [float] [[run-stack-docker]] === Run with Docker Compose -To get the default distributions of {es} and {kib} up and running in Docker, +To get the default distributions of {es} and {kib} up and running in Docker, you can use Docker Compose. -. Create a `docker-compose.yml` file for the Elastic Stack. +. Create a `docker-compose.yml` file for the Elastic Stack. The following example brings up a three node cluster and Kibana so you can see how things work. This all-in-one configuration is a handy way to bring up your first dev cluster before you build a distributed deployment with multiple hosts. + ifeval::["{release-state}"=="unreleased"] -NOTE: Version {version} of {es} has not been released, +NOTE: Version {version} of {es} has not been released, so the sample compose file is not yet available for this version. See the {stack-gs-current}/get-started-docker.html[current version] for the latest sample files. endif::[] @@ -28,7 +28,7 @@ include::docker/docker-compose.yml[] -------------------------------------------- endif::[] // tag::docker-memory[] -. Make sure Docker Engine is allotted at least 4GiB of memory. +. Make sure Docker Engine is allotted at least 4GiB of memory. In Docker Desktop, you configure resource usage on the Advanced tab in Preference (macOS) or Settings (Windows). // end::docker-memory[] @@ -47,39 +47,39 @@ docker-compose up curl -X GET "localhost:9200/_cat/nodes?v&pretty" -------------------------------------------------- -. Open {kib} to load sample data and interact with the cluster: -http://localhost:5601. +. Open {kib} to load sample data and interact with the cluster: +http://localhost:5601. -When you're done experimenting, you can tear down the containers and +When you're done experimenting, you can tear down the containers and volumes by running `docker-compose down -v`. [float] [[get-started-docker-tls]] -=== Run in Docker with TLS enabled +=== Run in Docker with TLS enabled If {security-features} are enabled, you must configure Transport Layer Security (TLS) encryption for the {es} transport layer. While it is possible to use a trial license without setting up TLS, we advise securing your stack from the start. -To get an {es} cluster and {kib} up and running in Docker with security enabled, +To get an {es} cluster and {kib} up and running in Docker with security enabled, you can use Docker Compose: -. Create the following compose and configuration files. -These files are also available from the -https://github.com/elastic/stack-docs/blob/master/docs/en/getting-started/docker/[elastic/stack-docs] +. Create the following compose and configuration files. +These files are also available from the +https://github.com/elastic/stack-docs/blob/master/docs/en/getting-started/docker/[elastic/stack-docs] repository on GitHub. + -- ifeval::["{release-state}"=="unreleased"] -NOTE: Version {version} of {es} has not been released, +NOTE: Version {version} of {es} has not been released, so the sample compose and configuration files are not yet available for this version. See the {stack-gs-current}/get-started-docker.html[current version] for the latest sample files. endif::[] * `instances.yml` identifies the instances you need to create certificates for. * `.env` sets environment variables to specify the {es} version and -the location where the {es} certificates will be created. +the location where the {es} certificates will be created. * `create-certs.yml` is a Docker Compose file that launches a container to generate the certificates for {es} and {kib}. * `elastic-docker-tls.yml` is a Docker Compose file that brings up a three-node {es} cluster @@ -91,7 +91,7 @@ ifeval::["{release-state}"!="unreleased"] .`instances.yml`: ["source","yaml"] ---- -include::docker/instances.yml[] +include::docker/instances.yml[] ---- .`.env`: @@ -115,7 +115,7 @@ include::docker/elastic-docker-tls.yml[] <1> Generate and apply a trial license that supports Transport Layer Security. <2> Enable Transport Layer Security to encrypt client communications. <3> Enable Transport Layer Security to encrypt internode communications. -<4> Allow the use of self-signed certificates by not requiring hostname verification. +<4> Allow the use of self-signed certificates by not requiring hostname verification. endif::[] -- @@ -141,12 +141,12 @@ docker-compose -f elastic-docker-tls.yml up -d ---- IMPORTANT: At this point, {kib} cannot connect to the {es} cluster. -You must generate a password for the built-in `kibana_system` user, update the `ELASTICSEARCH_PASSWORD` -in the compose file, and restart to enable {kib} to communicate with the secured cluster. +You must generate a password for the built-in `kibana_system` user, update the `ELASTICSEARCH_PASSWORD` +in the compose file, and restart to enable {kib} to communicate with the secured cluster. -- -. Run the `elasticsearch-setup-passwords` tool to generate passwords for all built-in users, +. Run the `elasticsearch-setup-passwords` tool to generate passwords for all built-in users, including the `kibana_system` user. If you don't use PowerShell on Windows, remove the trailing `\`characters and join the lines before running this command. + @@ -157,18 +157,18 @@ docker exec es01 /bin/bash -c "bin/elasticsearch-setup-passwords \ auto --batch --url https://es01:9200" ---- -IMPORTANT: Make a note of the generated passwords. -You must configure the `kibana_system` user password in the compose file to enable {kib} to connect to {es}, -and you'll need the password for the `elastic` superuser to +IMPORTANT: Make a note of the generated passwords. +You must configure the `kibana_system` user password in the compose file to enable {kib} to connect to {es}, +and you'll need the password for the `elastic` superuser to log in to {kib} and submit requests to {es}. -- -. Set `ELASTICSEARCH_PASSWORD` in the `elastic-docker-tls.yml` compose file to the password +. Set `ELASTICSEARCH_PASSWORD` in the `elastic-docker-tls.yml` compose file to the password generated for the `kibana_system` user. + -- ifeval::["{release-state}"=="unreleased"] -NOTE: Version {version} of {es} has not been released, +NOTE: Version {version} of {es} has not been released, so the sample compose file is not yet available for this version. See the {stack-gs-current}/get-started-docker.html[current version] for the latest sample files. endif::[] @@ -210,23 +210,23 @@ docker-compose -f elastic-docker-tls.yml up -d ---- -- -. Open {kib} to load sample data and interact with the cluster: -https://localhost:5601. +. Open {kib} to load sample data and interact with the cluster: +https://localhost:5601. + -NOTE: Because SSL is also enabled for communications between {kib} and client browsers, -you must access {kib} via the HTTPS protocol. +NOTE: Because SSL is also enabled for communications between {kib} and client browsers, +you must access {kib} via the HTTPS protocol. -When you're done experimenting, you can tear down the containers, network, and +When you're done experimenting, you can tear down the containers, network, and volumes by running `docker-compose -f elastic-docker-tls.yml down -v`. [float] [[load-settings-file]] ==== Loading settings from a file -Specifying settings for {es} and {{kib}} directly in the compose file is a convenient way to get started, +Specifying settings for {es} and {{kib}} directly in the compose file is a convenient way to get started, but loading settings from a file is preferable once you get past the experimental stage. -For example, to use `es01.yml` as the configuration file for the `es01` {es} node, +For example, to use `es01.yml` as the configuration file for the `es01` {es} node, you can create a bind mount in the volumes section. ["source","yaml"] @@ -235,7 +235,7 @@ you can create a bind mount in the volumes section. - data01:/usr/share/elasticsearch/data - certs:$CERTS_DIR - ./es01.yml:/usr/share/elasticsearch/config/elasticsearch.yml ----- +---- Similarly, to load {kib} settings from a file, you overwrite `/usr/share/kibana/config/kibana.yml`: @@ -252,11 +252,4 @@ Similarly, to load {kib} settings from a file, you overwrite `/usr/share/kibana/ See the product-specific documentation for information about running a specific Elastic product in Docker: * {ref}/docker.html[Install {es} with Docker] -* {apm-server-ref}/running-on-docker.html[Running APM Server on Docker] -* {auditbeat-ref}/running-on-docker.html[Running {auditbeat} on Docker] -* {filebeat-ref}/running-on-docker.html[Running {filebeat} on Docker] -* {heartbeat-ref}/running-on-docker.html[Running {heartbeat} on Docker] -* {kibana-ref}/docker.html[Running {kib} on Docker] -* {logstash-ref}/docker.html[Running {ls} on Docker] -* {metricbeat-ref}/running-on-docker.html[Running {metricbeat} on Docker] -* {packetbeat-ref}/running-on-docker.html[Running {packetbeat} on Docker] +* {fleet-guide}/elastic-agent-container.html[Run Elastic Agent in a container] diff --git a/docs/en/glossary/glossary.asciidoc b/docs/en/glossary/glossary.asciidoc index 0dcdbe6e2..a9beca5df 100644 --- a/docs/en/glossary/glossary.asciidoc +++ b/docs/en/glossary/glossary.asciidoc @@ -429,9 +429,9 @@ point contribute to its outlier behavior. See [[glossary-feature-importance]] feature importance:: In supervised {ml} methods such as {regression} and {classification}, feature -importance indicates the degree to which a specific feature affects a +importance indicates the degree to which a specific feature affects a prediction. -See +See {ml-docs}/ml-dfa-regression.html#dfa-regression-feature-importance[{regression-cap} feature importance] and {ml-docs}/ml-dfa-classification.html#dfa-classification-feature-importance[{classification-cap} feature importance]. @@ -1140,7 +1140,7 @@ different spaces for each team, use case, or individual. See [[glossary-span]] span:: Information about the execution of a specific code path. -{apm-overview-ref-v}/transaction-spans.html[Spans] measure from the start to the end of an activity +{apm-guide-ref}/data-model-spans.html[Spans] measure from the start to the end of an activity and can have a parent/child relationship with other spans. //Source: Observability @@ -1243,7 +1243,7 @@ referenced in an ingest pipeline or in a pipeline aggregation to perform [[glossary-transaction]] transaction:: A special kind of <> that has additional attributes associated with it. -{apm-overview-ref-v}/transactions.html[Transactions] describe an event captured by an +{apm-guide-ref}/data-model-transactions.html[Transactions] describe an event captured by an Elastic <> instrumenting a service. //Source: Observability diff --git a/docs/en/install-upgrade/breaking.asciidoc b/docs/en/install-upgrade/breaking.asciidoc index 9ea5f6987..217938418 100644 --- a/docs/en/install-upgrade/breaking.asciidoc +++ b/docs/en/install-upgrade/breaking.asciidoc @@ -2,7 +2,7 @@ == Breaking changes Before you upgrade, you must review the breaking changes for each product you -use and make the necessary changes so your code is compatible with {version}. +use and make the necessary changes so your code is compatible with {version}. ** <> ** <> @@ -26,10 +26,10 @@ Upgrade Assistant provides information about which {dfeeds} need to be updated. APM ++++ -This list summarizes the most important breaking changes in APM. -For the complete list, go to {apm-get-started-ref}/apm-breaking-changes.html[APM breaking changes]. +This list summarizes the most important breaking changes in APM. +For the complete list, go to {apm-guide-ref}/apm-breaking.html[APM breaking changes]. -include::{apm-repo-dir}/apm-breaking-changes.asciidoc[tag=notable-v8-breaking-changes] +include::{apm-repo-dir}/apm-breaking.asciidoc[tag=notable-v8-breaking-changes] [[beats-breaking-changes]] === Beats breaking changes @@ -37,7 +37,7 @@ include::{apm-repo-dir}/apm-breaking-changes.asciidoc[tag=notable-v8-breaking-ch Beats ++++ -This list summarizes the most important breaking changes in Beats. +This list summarizes the most important breaking changes in Beats. For the complete list, go to {beats-ref}/breaking-changes.html[Beats breaking changes]. include::{beats-repo-dir}/release-notes/breaking/breaking-8.0.asciidoc[tag=notable-breaking-changes] @@ -176,4 +176,3 @@ the complete list, go to {logstash-ref}/breaking-changes.html[Logstash breaking changes]. include::{ls-repo-dir}/static/breaking-changes.asciidoc[tag=notable-breaking-changes] - diff --git a/docs/en/install-upgrade/index.asciidoc b/docs/en/install-upgrade/index.asciidoc index 58ab9d95d..e2dbddc65 100644 --- a/docs/en/install-upgrade/index.asciidoc +++ b/docs/en/install-upgrade/index.asciidoc @@ -1,7 +1,7 @@ [[elastic-stack]] = Installation and Upgrade Guide -:apm-repo-dir: {apm-server-root}/docs/guide +:apm-repo-dir: {apm-server-root}/docs :beats-repo-dir: {beats-root}/libbeat/docs :es-repo-dir: {elasticsearch-root}/docs/reference :hadoop-repo-dir: {elasticsearch-hadoop-root}/docs/src/reference/asciidoc diff --git a/docs/en/install-upgrade/installing-stack.asciidoc b/docs/en/install-upgrade/installing-stack.asciidoc index ecdc02b4b..448ffc4b6 100644 --- a/docs/en/install-upgrade/installing-stack.asciidoc +++ b/docs/en/install-upgrade/installing-stack.asciidoc @@ -18,7 +18,7 @@ Install the Elastic Stack products you want to use in the following order: . Kibana ({kibana-ref}/install.html[install]) . Logstash ({logstash-ref}/installing-logstash.html[install]) . Beats ({beats-ref}/getting-started.html[install instructions]) -. APM Server ({apm-server-ref}/installing.html[install instructions]) +. APM ({apm-guide-ref}/apm-quick-start.html[install instructions]) . Elasticsearch Hadoop ({hadoop-ref}/install.html[install instructions]) Installing in this order ensures that the components each product depends @@ -33,7 +33,7 @@ official hosted {es} and {kib} offering from Elastic. The {ess} is available on both AWS and GCP. Installing on {ecloud} is easy: a single click creates an {es} cluster -configured to the size you want, with or without high availability. The +configured to the size you want, with or without high availability. The subscription features are always installed, so you automatically have the ability to secure and monitor your cluster. {kib} can be enabled on a cluster with a click, and a number of popular plugins are readily available. @@ -43,4 +43,3 @@ information, see https://www.elastic.co/pricing/. You can {ess-trial}[try out the {ess} for free]. For more information, see {cloud}/ec-getting-started.html[Getting Started with {ecloud}]. - diff --git a/docs/en/install-upgrade/overview.asciidoc b/docs/en/install-upgrade/overview.asciidoc index b9fd464ec..8057e3d15 100644 --- a/docs/en/install-upgrade/overview.asciidoc +++ b/docs/en/install-upgrade/overview.asciidoc @@ -7,7 +7,7 @@ to simplify the installation and upgrade process. The full stack consists of: * {beats-ref}/index.html[Beats {branch}] -* {apm-server-ref}/index.html[APM Server {branch}] +* {apm-guide-ref}/index.html[APM {branch}] * {ref}/index.html[Elasticsearch {branch}] * {hadoop-ref}/index.html[Elasticsearch Hadoop {branch}] * {kibana-ref}/index.html[Kibana {branch}] diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 4fe54631f..1aeadd002 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -61,9 +61,10 @@ on the cluster during the upgrade process. For more information, see .. Java API Client: {java-api-client}/installation.html#maven[dependency configuration] .. Logstash: {logstash-ref}/upgrading-logstash.html[upgrade instructions] .. Beats: {beats-ref}/upgrading.html[upgrade instructions] -.. APM Server: {apm-server-ref}/upgrading.html[upgrade instructions] +.. APM: {apm-guide-ref}/upgrade.html[upgrade instructions] .. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions] + [WARNING] ==== If using {agent} in 7.12 or lower, your {agent}s will automatically be unenrolled