diff --git a/docs/apm-components.asciidoc b/docs/apm-components.asciidoc index 1d9adaa02c0..412c667197c 100644 --- a/docs/apm-components.asciidoc +++ b/docs/apm-components.asciidoc @@ -1,12 +1,32 @@ [[apm-components]] -=== Components and documentation +== Components and documentation -Elastic APM consists of four components: *APM agents*, *Elastic Agent*, *Elasticsearch*, and *Kibana*. +**** +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**. +For standalone APM Server (legacy) documentation, please see the <> +and <>. +**** + +Elastic APM consists of four components: *APM agents*, the *Elastic APM integration*, *Elasticsearch*, and *Kibana*. +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: image::./images/apm-architecture.png[Architecture of Elastic APM] +Or, APM agents and the APM integration live on edge machines and enroll via a centrally hosted {agent}: + +image::./images/apm-architecture-two.png[Architecture of Elastic APM option two] + +Read on to learn more about each of these components! + [float] -==== APM Agents +=== 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. @@ -27,26 +47,28 @@ Each agent has its own documentation: * {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] [float] -==== Elastic Agent +[[apm-integration]] +=== Elastic APM integration -Elastic 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. - -The APM integration within Elastic Agent receives performance data from your APM agents, +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 Elastic 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] -==== Elasticsearch +=== Elasticsearch {ref}/index.html[Elasticsearch] 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. Elasticsearch is used to store APM performance metrics and make use of its aggregations. [float] -==== Kibana APM app +=== Kibana APM app {kibana-ref}/index.html[Kibana] is a free and open analytics and visualization platform designed to work with Elasticsearch. You use Kibana to search, view, and interact with data stored in Elasticsearch. diff --git a/docs/images/apm-architecture-two.png b/docs/images/apm-architecture-two.png new file mode 100644 index 00000000000..6f9473bdcf0 Binary files /dev/null and b/docs/images/apm-architecture-two.png differ diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index 5cb6513d017..97f19c953cc 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -1,5 +1,6 @@ include::./version.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] +include::./notices.asciidoc[] :apm-integration-docs: :apm-package-dir: {docdir}/apm-package @@ -45,8 +46,8 @@ include::upgrade.asciidoc[] include::release-notes.asciidoc[leveloffset=+1] -// This includes the legacy APM Overview +// Legacy APM Overview include::legacy/guide/index.asciidoc[] -// This includes the legacy APM Server Reference +// Legacy APM Server Reference include::legacy/index.asciidoc[] diff --git a/docs/legacy/agent-configuration.asciidoc b/docs/legacy/agent-configuration.asciidoc index 9fdec4c3f04..4fdb1d51897 100644 --- a/docs/legacy/agent-configuration.asciidoc +++ b/docs/legacy/agent-configuration.asciidoc @@ -5,6 +5,9 @@ Agent configuration ++++ +IMPORTANT: {deprecation-notice-api} +If you've already upgraded, see <>. + APM Server exposes an API endpoint that allows agents to query the server for configuration changes. More information on this feature is available in {kibana-ref}/agent-configuration.html[APM Agent configuration in Kibana]. diff --git a/docs/legacy/api-keys.asciidoc b/docs/legacy/api-keys.asciidoc index fe06a7a8494..f9a87cae6c5 100644 --- a/docs/legacy/api-keys.asciidoc +++ b/docs/legacy/api-keys.asciidoc @@ -2,6 +2,9 @@ [[beats-api-keys]] == Grant access using API keys +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, see <>. + Instead of using usernames and passwords, you can use API keys to grant access to {es} resources. You can set API keys to expire at a certain time, and you can explicitly invalidate them. Any user with the `manage_api_key` diff --git a/docs/legacy/apm-package/apm-integration.asciidoc b/docs/legacy/apm-package/apm-integration.asciidoc deleted file mode 100644 index 3feba1fa088..00000000000 --- a/docs/legacy/apm-package/apm-integration.asciidoc +++ /dev/null @@ -1,116 +0,0 @@ -[[apm-integration]] -== APM integration for {agent} - -++++ -APM integration ({agent}) -++++ - -beta::[] - -{agent} is a single, unified way to add monitoring for logs, metrics, and other types of data to each host. -The APM integration for {agent} assigns the APM input to a specified policy, -and installs {es} templates and ingest node pipelines for APM data. -When {agent} is assigned a policy with an APM input, -{agent} will run the APM Server binary locally and listen for APM data. - -[discrete] -[[apm-integration-get-started]] -=== Get started - -Ready to jump in? -Read through the <>, then head over to the -quick start guide: {observability-guide}/ingest-traces.html[Get application traces into the {stack}]. - -[discrete] -[[apm-integration-architecture]] -=== Architecture - -If RUM is enabled, you must run {agent} centrally. -If RUM is disabled, {agent} can be run on edge machines. To do this, -download and enroll an {agent} on the same machines that your instrumented services run on. - -[discrete] -[[apm-integration-limitations]] -=== Limitations - -IMPORTANT: This integration is still in beta and does not have feature parity with standalone APM. -Do not migrate production deployments. - -Data steams migration:: -Existing APM users will need to migrate to data streams to use the APM integration. -This change cannot be reverted, and impacts how APM Server and its indices are configured -- see <> and <>. -Additionally, users on {ece} require additional steps prior to migrating, like configuring TLS certificates for the connection between APM Server and {es}. - -Stack monitoring:: -<> is not yet available. - -Index lifecycle management (ILM):: -A default ILM policy, named `traces-apm.traces-default_policy` is created for all event types. -No default warm, cold, or delete data tiers are defined. -It is not possible to configure this policy in APM Server or {agent}– -it must be configured with {es} or {kib}. -See {ref}/example-using-index-lifecycle-policy.html[Customize built-in ILM policies] for more information. - -Onboarding:: -APM Server no longer writes an onboarding document when setting up. - -Standalone mode:: -{fleet-guide}/install-standalone-elastic-agent.html[Standalone mode] is not currently supported. -An {agent} with the APM integration enabled must be managed by fleet. - -Service names:: -Service names are case-insensitive and must be unique. -See <> for more information. - -Upgrading from prior {agent} versions:: -Due to changing API key permissions, an {agent} enrolled before version 7.12 is not compatible with the APM integration. -You must enroll a new {agent} to use the integration. - -[discrete] -[[apm-integration-terminology]] -=== Terminology - -Agents:: - -{agent} and APM agents are different components: -+ -{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-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. -This data is sent to APM Server. - -Central management/configuration:: - -// to do: add links to these docs -Fleet central management and APM agent central configuration are two different features -that can be accessed in {kib}: -+ -**Fleet central management** serves as the communication channel with your {agent}s; -agents check in for the latest updates on a regular basis. -+ -**APM agent central configuration** allows you to fine-tune your agent configuration from within the APM app. -Changes are automatically propagated to your APM agents, so there’s no need to redeploy your services. - - -[discrete] -[[apm-integration-versioning]] -=== Package versioning - -The APM package is versioned separately from the Elastic Stack. -In the future, we may align with Elastic Stack versioning. - -[discrete] -[[apm-integration-learn-more]] -=== Learn more - -* <> -* {fleet-guide}/fleet-overview.html[Fleet overview] - -include::./data-streams.asciidoc[] - -include::./configure.asciidoc[] \ No newline at end of file diff --git a/docs/legacy/apm-package/configure.asciidoc b/docs/legacy/apm-package/configure.asciidoc deleted file mode 100644 index fa17dd7d226..00000000000 --- a/docs/legacy/apm-package/configure.asciidoc +++ /dev/null @@ -1,51 +0,0 @@ -[[apm-integration-configure]] -== Configure APM integration - -++++ -Configure -++++ - -beta::[] - -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/legacy/apm-package/data-streams.asciidoc b/docs/legacy/apm-package/data-streams.asciidoc deleted file mode 100644 index e271c2f2dbd..00000000000 --- a/docs/legacy/apm-package/data-streams.asciidoc +++ /dev/null @@ -1,78 +0,0 @@ -[[apm-integration-data-streams]] -== Data streams - -**** -beta::[] - -Existing APM users need to migrate to data streams to use the APM integration. -The integration does not have feature parity with standalone APM. -Production deployments should not be migrated at this time. - -Migration limitations include: - -* This change cannot be reverted -* This change impacts how APM Server and its indices are configured -- see <> and <> -* Users on {ece} require additional steps prior to migrating, like configuring TLS certificates for the connection between APM Server and {es} -* Additional <> -**** - -[discrete] -[[apm-integration-naming-scheme]] -=== Data stream naming scheme - -{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-guide}/data-streams.html[Fleet and Elastic Agent Guide] to learn more. - -`apm` input data is divided into three types: - -Traces:: - -Traces are comprised of {apm-overview-ref-v}/apm-data-model.html[spans and transactions]. -Traces are stored in the following data stream: - -- Application traces: `traces-apm-` - -Metrics:: - -Metrics include application-based metrics and basic system metrics. -Metrics are stored in the following data streams: - -- Application defined metrics: `metrics-apm.app.-` -- APM internal metrics: `metrics-apm.internal-` -- APM profiling metrics: `metrics-apm.profiling-` - -Logs:: - -Logs include application error events and application logs. -Logs are stored in the following data streams: - -- APM error/exception logging: `logs-apm.error-` - -[discrete] -[[apm-integration-service-name]] -=== Service names - -The APM integration maps an instrumented service's name–defined in each APM agent's -configuration–to the index that its application defined metrics are stored in {es}. -Service names therefore must follow index naming rules: - -* 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 (`_`). -Special characters include: -+ -[source,text] ----- -'\\', '/', '*', '?', '"', '<', '>', '|', ' ', ',', '#', ':', '-' ----- - -[discrete] -[[apm-integration-namespace]] -=== Namespace - -There is no recommendation for what to use as your namespace; -it's intentionally flexible which allows greater control over how your data is indexed. -For example, you might create namespaces for each of your environments, -like `dev`, `prod`, `production`, etc. -Or, you might create namespaces that correspond to strategic business units within your organization. diff --git a/docs/legacy/common-problems.asciidoc b/docs/legacy/common-problems.asciidoc index a808c5a6886..623ac96f1b3 100644 --- a/docs/legacy/common-problems.asciidoc +++ b/docs/legacy/common-problems.asciidoc @@ -1,6 +1,8 @@ [[common-problems]] == Common problems +IMPORTANT: {deprecation-notice-data} + This section describes common problems you might encounter with APM Server. * <> diff --git a/docs/legacy/config-ownership.asciidoc b/docs/legacy/config-ownership.asciidoc index e14962098d3..ebd3ccfcb96 100644 --- a/docs/legacy/config-ownership.asciidoc +++ b/docs/legacy/config-ownership.asciidoc @@ -1,3 +1,4 @@ +[float] [[config-file-ownership]] ==== Configuration file ownership @@ -36,6 +37,7 @@ can only be writable by the owner but the permissions are "-rw-rw-r--" To correct this problem, use +chmod go-w /etc/{beatname_lc}/{beatname_lc}.yml+ to remove write privileges from anyone other than the owner. +[float] ===== Disabling strict permission checks You can disable strict permission checks from the command line by using diff --git a/docs/legacy/configuration-anonymous.asciidoc b/docs/legacy/configuration-anonymous.asciidoc index aad3787b7d7..6b3c1e12ca2 100644 --- a/docs/legacy/configuration-anonymous.asciidoc +++ b/docs/legacy/configuration-anonymous.asciidoc @@ -5,6 +5,9 @@ Anonymous authentication ++++ +IMPORTANT: {deprecation-notice-config} +If you're using {fleet} and the Elastic APM integration, please see <> instead. + Elastic APM agents can send unauthenticated (anonymous) events to the APM Server. This is useful for agents that run on clients, like the Real User Monitoring (RUM) agent running in a browser, or the iOS/Swift agent running in a user application. diff --git a/docs/legacy/configuration-process.asciidoc b/docs/legacy/configuration-process.asciidoc index 34370f3f6fb..dbb21b8589c 100644 --- a/docs/legacy/configuration-process.asciidoc +++ b/docs/legacy/configuration-process.asciidoc @@ -1,6 +1,9 @@ [[configuration-process]] == General configuration options +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, please see <> instead. + Example config file: ["source","yaml"] diff --git a/docs/legacy/configuration-rum.asciidoc b/docs/legacy/configuration-rum.asciidoc index e5661fdc855..7815ccadc01 100644 --- a/docs/legacy/configuration-rum.asciidoc +++ b/docs/legacy/configuration-rum.asciidoc @@ -5,6 +5,9 @@ Real User Monitoring (RUM) ++++ +IMPORTANT: {deprecation-notice-config} +If you're using {fleet} and the Elastic APM integration, please see <> instead. + The {apm-rum-ref-v}/index.html[Real User Monitoring (RUM) agent] captures user interactions with clients such as web browsers. These interactions are sent as events to the APM Server. Because the RUM agent runs on the client side, the connection between agent and server is unauthenticated. diff --git a/docs/legacy/configure-kibana-endpoint.asciidoc b/docs/legacy/configure-kibana-endpoint.asciidoc index 606727b27b2..fefa71ea2c2 100644 --- a/docs/legacy/configure-kibana-endpoint.asciidoc +++ b/docs/legacy/configure-kibana-endpoint.asciidoc @@ -5,6 +5,8 @@ Kibana endpoint ++++ +IMPORTANT: {deprecation-notice-config} + Configuring the Kibana endpoint is required for {kibana-ref}/agent-configuration.html[APM Agent configuration in Kibana]. You configure the endpoint in the `apm-server.kibana` section of the diff --git a/docs/legacy/configuring-ingest.asciidoc b/docs/legacy/configuring-ingest.asciidoc index 2795920a8f0..7da7174f33e 100644 --- a/docs/legacy/configuring-ingest.asciidoc +++ b/docs/legacy/configuring-ingest.asciidoc @@ -4,7 +4,7 @@ [[configuring-ingest-node]] == Parse data using ingest node pipelines -deprecated::[7.16.0,Users should now use the <>, which includes ingest node pipeline management. See <>] +deprecated::[7.16.0,Users should now use the <>, which includes ingest node pipeline management. If you've already upgraded, please see <> instead.] You can configure APM Server to use an {ref}/ingest.html[ingest node] to pre-process documents before indexing them in {es}. diff --git a/docs/legacy/configuring.asciidoc b/docs/legacy/configuring.asciidoc index 18dcef78e6b..b29be349e06 100644 --- a/docs/legacy/configuring.asciidoc +++ b/docs/legacy/configuring.asciidoc @@ -5,6 +5,9 @@ Configure ++++ +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, please see <> instead. + include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> @@ -54,6 +57,9 @@ include::./configuration-rum.asciidoc[] [[configuration-ssl-landing]] == SSL/TLS settings +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, please see <> instead. + SSL/TLS is available for: * <> (APM Agents) diff --git a/docs/legacy/copied-from-beats/docs/command-reference.asciidoc b/docs/legacy/copied-from-beats/docs/command-reference.asciidoc index cd98a25f457..8688d8f87d2 100644 --- a/docs/legacy/copied-from-beats/docs/command-reference.asciidoc +++ b/docs/legacy/copied-from-beats/docs/command-reference.asciidoc @@ -65,6 +65,8 @@ endif::[] Command reference ++++ +IMPORTANT: {deprecation-notice-config} + ifndef::no_dashboards[] {beatname_uc} provides a command-line interface for starting {beatname_uc} and performing common tasks, like testing configuration files and loading dashboards. @@ -129,6 +131,7 @@ endif::[] Also see <>. ifdef::apm-server[] +[float] [[apikey-command]] ==== `apikey` command @@ -259,6 +262,7 @@ Shows help for the `deploy` command. ----- endif::[] +[float] [[export-command]] ==== `export` command @@ -393,6 +397,7 @@ ifdef::serverless[] ----- endif::serverless[] +[float] [[help-command]] ==== `help` command @@ -426,6 +431,7 @@ Specifies the name of the command to show help for. ----- ifndef::serverless[] +[float] [[keystore-command]] ==== `keystore` command @@ -484,6 +490,7 @@ See <> for more examples. endif::[] ifeval::["{beatname_lc}"=="functionbeat"] +[float] [[package-command]] ==== `package` command @@ -604,6 +611,7 @@ endif::[] endif::[] ifndef::serverless[] +[float] [[run-command]] ==== `run` command @@ -733,7 +741,7 @@ Or: ----- endif::[] - +[float] [[setup-command]] ==== `setup` command @@ -858,6 +866,7 @@ endif::apm-server[] endif::[] // end::setup-command-tag[] +[float] [[test-command]] ==== `test` command @@ -946,6 +955,7 @@ Shows help for the `update` command. ----- endif::[] +[float] [[version-command]] ==== `version` command diff --git a/docs/legacy/copied-from-beats/docs/debugging.asciidoc b/docs/legacy/copied-from-beats/docs/debugging.asciidoc index 08cdc3f7152..ee564f6eb4b 100644 --- a/docs/legacy/copied-from-beats/docs/debugging.asciidoc +++ b/docs/legacy/copied-from-beats/docs/debugging.asciidoc @@ -9,6 +9,8 @@ //// include::../../libbeat/docs/debugging.asciidoc[] ////////////////////////////////////////////////////////////////////////// +IMPORTANT: {deprecation-notice-data} + By default, {beatname_uc} sends all its output to syslog. When you run {beatname_uc} in the foreground, you can use the `-e` command line flag to redirect the output to standard error instead. For example: diff --git a/docs/legacy/copied-from-beats/docs/getting-help.asciidoc b/docs/legacy/copied-from-beats/docs/getting-help.asciidoc index 2404de19a02..5dbbec5165c 100644 --- a/docs/legacy/copied-from-beats/docs/getting-help.asciidoc +++ b/docs/legacy/copied-from-beats/docs/getting-help.asciidoc @@ -9,6 +9,8 @@ //// include::../../libbeat/docs/getting-help.asciidoc[] ////////////////////////////////////////////////////////////////////////// +IMPORTANT: {deprecation-notice-data} + Start by searching the https://discuss.elastic.co/c/{discuss_forum}[{beatname_uc} discussion forum] for your issue. If you can't find a resolution, open a new issue or add a comment to an existing one. Make sure you provide the following information, and we'll help you troubleshoot the problem: diff --git a/docs/legacy/copied-from-beats/docs/howto/load-index-templates.asciidoc b/docs/legacy/copied-from-beats/docs/howto/load-index-templates.asciidoc index 885432a2671..9dcce04f900 100644 --- a/docs/legacy/copied-from-beats/docs/howto/load-index-templates.asciidoc +++ b/docs/legacy/copied-from-beats/docs/howto/load-index-templates.asciidoc @@ -1,6 +1,10 @@ [id="{beatname_lc}-template"] == Load the {es} index template +deprecated::[7.16.0,Users should now use the <> or configure <>. ] + +IMPORTANT: {deprecation-notice-data} + {es} uses {ref}/index-templates.html[index templates] to define: * Settings that control the behavior of your indices. The settings include the diff --git a/docs/legacy/copied-from-beats/docs/https.asciidoc b/docs/legacy/copied-from-beats/docs/https.asciidoc index af5020453c0..3a0a2675749 100644 --- a/docs/legacy/copied-from-beats/docs/https.asciidoc +++ b/docs/legacy/copied-from-beats/docs/https.asciidoc @@ -14,6 +14,8 @@ [[securing-communication-elasticsearch]] == Secure communication with Elasticsearch +IMPORTANT: {deprecation-notice-config} + When sending data to a secured cluster through the `elasticsearch` output, {beatname_uc} can use any of the following authentication methods: diff --git a/docs/legacy/copied-from-beats/docs/keystore.asciidoc b/docs/legacy/copied-from-beats/docs/keystore.asciidoc index 45eb297ac9c..6770f1ed5c0 100644 --- a/docs/legacy/copied-from-beats/docs/keystore.asciidoc +++ b/docs/legacy/copied-from-beats/docs/keystore.asciidoc @@ -12,6 +12,8 @@ [[keystore]] === Secrets keystore for secure settings +IMPORTANT: {deprecation-notice-installation} + ++++ Secrets keystore ++++ @@ -120,4 +122,3 @@ To remove a key from the keystore, use: ---------------------------------------------------------------- {beatname_lc} keystore remove ES_PWD ---------------------------------------------------------------- - diff --git a/docs/legacy/copied-from-beats/docs/loggingconfig.asciidoc b/docs/legacy/copied-from-beats/docs/loggingconfig.asciidoc index dabece8e98f..f2101abde84 100644 --- a/docs/legacy/copied-from-beats/docs/loggingconfig.asciidoc +++ b/docs/legacy/copied-from-beats/docs/loggingconfig.asciidoc @@ -17,6 +17,8 @@ Logging ++++ +IMPORTANT: {deprecation-notice-config} + The `logging` section of the +{beatname_lc}.yml+ config file contains options for configuring the logging output. ifndef::serverless[] @@ -173,7 +175,7 @@ endif::serverless[] By default, {beatname_uc} periodically logs its internal metrics that have changed in the last period. For each metric that changed, the delta from the value at the beginning of the period is logged. Also, the total values for all -non-zero internal metrics are logged on shutdown. Set this to false to disable +non-zero internal metrics are logged on shutdown. Set this to false to disable this behavior. The default is true. Here is an example log line: diff --git a/docs/legacy/copied-from-beats/docs/monitoring/monitoring-beats.asciidoc b/docs/legacy/copied-from-beats/docs/monitoring/monitoring-beats.asciidoc index f02a6dbd4bc..7a4638e0c43 100644 --- a/docs/legacy/copied-from-beats/docs/monitoring/monitoring-beats.asciidoc +++ b/docs/legacy/copied-from-beats/docs/monitoring/monitoring-beats.asciidoc @@ -6,6 +6,8 @@ Monitor ++++ +IMPORTANT: {deprecation-notice-monitor} + You can use the {stack} {monitor-features} to gain insight into the health of ifndef::apm-server[] {beatname_uc} instances running in your environment. diff --git a/docs/legacy/copied-from-beats/docs/monitoring/monitoring-internal-collection.asciidoc b/docs/legacy/copied-from-beats/docs/monitoring/monitoring-internal-collection.asciidoc index 3263777c9f4..eca58a9c2c1 100644 --- a/docs/legacy/copied-from-beats/docs/monitoring/monitoring-internal-collection.asciidoc +++ b/docs/legacy/copied-from-beats/docs/monitoring/monitoring-internal-collection.asciidoc @@ -16,6 +16,8 @@ Use internal collection ++++ +IMPORTANT: {deprecation-notice-monitor} + Use internal collectors to send {beats} monitoring data directly to your monitoring cluster. ifndef::serverless[] @@ -26,9 +28,9 @@ and maintain. endif::[] //Commenting out this link temporarily until the general monitoring docs can be -//updated. -//To learn about monitoring in general, see -//{ref}/monitor-elasticsearch-cluster.html[Monitor a cluster]. +//updated. +//To learn about monitoring in general, see +//{ref}/monitor-elasticsearch-cluster.html[Monitor a cluster]. . Create an API key or user that has appropriate authority to send system-level monitoring data to {es}. For example, you can use the built-in +{beat_monitoring_user}+ user or @@ -119,7 +121,7 @@ ifdef::serverless[] . Deploy {beatname_uc}. endif::[] -. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}]. +. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}]. include::shared-monitor-config.asciidoc[] diff --git a/docs/legacy/copied-from-beats/docs/monitoring/monitoring-metricbeat.asciidoc b/docs/legacy/copied-from-beats/docs/monitoring/monitoring-metricbeat.asciidoc index 47168cc1870..01f5533232e 100644 --- a/docs/legacy/copied-from-beats/docs/monitoring/monitoring-metricbeat.asciidoc +++ b/docs/legacy/copied-from-beats/docs/monitoring/monitoring-metricbeat.asciidoc @@ -6,7 +6,9 @@ Use {metricbeat} collection ++++ -In 7.3 and later, you can use {metricbeat} to collect data about {beatname_uc} +IMPORTANT: {deprecation-notice-monitor} + +In 7.3 and later, you can use {metricbeat} to collect data about {beatname_uc} and ship it to the monitoring cluster. The benefit of using {metricbeat} instead of internal collection is that the monitoring agent remains active even if the {beatname_uc} instance dies. @@ -27,8 +29,8 @@ concurrently. If you don't want to run two instances concurrently, use endif::[] //Commenting out this link temporarily until the general monitoring docs can be -//updated. -//To learn about monitoring in general, see +//updated. +//To learn about monitoring in general, see //{ref}/monitor-elasticsearch-cluster.html[Monitor a cluster]. //NOTE: The tagged regions are re-used in the Stack Overview. @@ -71,7 +73,7 @@ http.port: 5067 -- // tag::disable-beat-collection[] Add the following setting in the {beatname_uc} configuration file -(+{beatname_lc}.yml+): +(+{beatname_lc}.yml+): [source,yaml] ---------------------------------- @@ -79,7 +81,7 @@ monitoring.enabled: false ---------------------------------- // end::disable-beat-collection[] -For more information, see +For more information, see <>. -- @@ -138,7 +140,7 @@ endif::[] + -- // tag::enable-beat-module[] -For example, to enable the default configuration in the `modules.d` directory, +For example, to enable the default configuration in the `modules.d` directory, run the following command, using the correct command syntax for your OS: ["source","sh",subs="attributes,callouts"] @@ -146,9 +148,9 @@ run the following command, using the correct command syntax for your OS: metricbeat modules enable beat-xpack ---------------------------------------------------------------------- -For more information, see -{metricbeat-ref}/configuration-metricbeat.html[Configure modules] and -{metricbeat-ref}/metricbeat-module-beat.html[beat module]. +For more information, see +{metricbeat-ref}/configuration-metricbeat.html[Configure modules] and +{metricbeat-ref}/metricbeat-module-beat.html[beat module]. // end::enable-beat-module[] -- @@ -170,7 +172,7 @@ The `modules.d/beat-xpack.yml` file contains the following settings: #password: "secret" xpack.enabled: true ---------------------------------- - + Set the `hosts`, `username`, and `password` settings as required by your environment. For other module settings, it's recommended that you accept the defaults. @@ -179,7 +181,7 @@ By default, the module collects {beatname_uc} monitoring data from `localhost:5066`. If you exposed the metrics on a different host or port when you enabled the HTTP endpoint, update the `hosts` setting. -To monitor multiple +To monitor multiple ifndef::apm-server[] {beats} agents, endif::[] @@ -198,15 +200,15 @@ it via HTTPS. For example, use a `hosts` setting like `https://localhost:5066`. // end::configure-beat-module[] // tag::remote-monitoring-user[] -If the Elastic {security-features} are enabled, you must also provide a user -ID and password so that {metricbeat} can collect metrics successfully: +If the Elastic {security-features} are enabled, you must also provide a user +ID and password so that {metricbeat} can collect metrics successfully: -.. Create a user on the {es} cluster that has the -`remote_monitoring_collector` {ref}/built-in-roles.html[built-in role]. +.. Create a user on the {es} cluster that has the +`remote_monitoring_collector` {ref}/built-in-roles.html[built-in role]. Alternatively, if it's available in your environment, use the `remote_monitoring_user` {ref}/built-in-users.html[built-in user]. -.. Add the `username` and `password` settings to the beat module configuration +.. Add the `username` and `password` settings to the beat module configuration file. // end::remote-monitoring-user[] -- @@ -224,19 +226,19 @@ other purposes, run the following command: ---------------------------------------------------------------------- metricbeat modules disable system ---------------------------------------------------------------------- -// end::disable-system-module[] +// end::disable-system-module[] -- . Identify where to send the monitoring data. + + -- -TIP: In production environments, we strongly recommend using a separate cluster -(referred to as the _monitoring cluster_) to store the data. Using a separate -monitoring cluster prevents production cluster outages from impacting your -ability to access your monitoring data. It also prevents monitoring activities +TIP: In production environments, we strongly recommend using a separate cluster +(referred to as the _monitoring cluster_) to store the data. Using a separate +monitoring cluster prevents production cluster outages from impacting your +ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. -For example, specify the {es} output information in the {metricbeat} +For example, specify the {es} output information in the {metricbeat} configuration file (`metricbeat.yml`): [source,yaml] @@ -244,14 +246,14 @@ configuration file (`metricbeat.yml`): output.elasticsearch: # Array of hosts to connect to. hosts: ["http://es-mon-1:9200", "http://es-mon2:9200"] <1> - + # Optional protocol and basic auth credentials. #protocol: "https" #api_key: "id:api_key" <2> #username: "elastic" #password: "changeme" ---------------------------------- -<1> In this example, the data is stored on a monitoring cluster with nodes +<1> In this example, the data is stored on a monitoring cluster with nodes `es-mon-1` and `es-mon-2`. <2> Specify one of `api_key` or `username`/`password`. @@ -262,27 +264,27 @@ must access it via HTTPS. For example, use a `hosts` setting like IMPORTANT: The {es} {monitor-features} use ingest pipelines, therefore the cluster that stores the monitoring data must have at least one ingest node. -If the {es} {security-features} are enabled on the monitoring cluster, you -must provide a valid user ID and password so that {metricbeat} can send metrics -successfully: +If the {es} {security-features} are enabled on the monitoring cluster, you +must provide a valid user ID and password so that {metricbeat} can send metrics +successfully: -.. Create a user on the monitoring cluster that has the -`remote_monitoring_agent` {ref}/built-in-roles.html[built-in role]. +.. Create a user on the monitoring cluster that has the +`remote_monitoring_agent` {ref}/built-in-roles.html[built-in role]. Alternatively, if it's available in your environment, use the -`remote_monitoring_user` {ref}/built-in-users.html[built-in user]. +`remote_monitoring_user` {ref}/built-in-users.html[built-in user]. + TIP: If you're using index lifecycle management, the remote monitoring user requires additional privileges to create and read indices. For more information, see <>. -.. Add the `username` and `password` settings to the {es} output information in +.. Add the `username` and `password` settings to the {es} output information in the {metricbeat} configuration file. -For more information about these configuration options, see +For more information about these configuration options, see {metricbeat-ref}/elasticsearch-output.html[Configure the {es} output]. -- . {metricbeat-ref}/metricbeat-starting.html[Start {metricbeat}] to begin -collecting monitoring data. +collecting monitoring data. -. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}]. +. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}]. diff --git a/docs/legacy/copied-from-beats/docs/monitoring/shared-monitor-config.asciidoc b/docs/legacy/copied-from-beats/docs/monitoring/shared-monitor-config.asciidoc index 609c3c3eb09..c814a5a7fa7 100644 --- a/docs/legacy/copied-from-beats/docs/monitoring/shared-monitor-config.asciidoc +++ b/docs/legacy/copied-from-beats/docs/monitoring/shared-monitor-config.asciidoc @@ -14,6 +14,8 @@ [[configuration-monitor]] === Settings for internal collection +IMPORTANT: {deprecation-notice-monitor} + Use the following settings to configure internal collection when you are not using {metricbeat} to collect monitoring data. diff --git a/docs/legacy/copied-from-beats/docs/output-cloud.asciidoc b/docs/legacy/copied-from-beats/docs/output-cloud.asciidoc index 6ad8329ff7d..d270b6dc387 100644 --- a/docs/legacy/copied-from-beats/docs/output-cloud.asciidoc +++ b/docs/legacy/copied-from-beats/docs/output-cloud.asciidoc @@ -6,6 +6,8 @@ {ess} ++++ +IMPORTANT: {deprecation-notice-config} + ifdef::apm-server[] NOTE: This page refers to using a separate instance of APM Server with an existing {ess-product}[{ess} deployment]. diff --git a/docs/legacy/copied-from-beats/docs/outputconfig.asciidoc b/docs/legacy/copied-from-beats/docs/outputconfig.asciidoc index efb84fabbfa..2580b4f4509 100644 --- a/docs/legacy/copied-from-beats/docs/outputconfig.asciidoc +++ b/docs/legacy/copied-from-beats/docs/outputconfig.asciidoc @@ -18,6 +18,8 @@ Output ++++ +IMPORTANT: {deprecation-notice-config} + You configure {beatname_uc} to write to a specific output by setting options in the Outputs section of the +{beatname_lc}.yml+ config file. Only a single output may be defined. diff --git a/docs/legacy/copied-from-beats/docs/repositories.asciidoc b/docs/legacy/copied-from-beats/docs/repositories.asciidoc index 1b27a6c0b44..d265f7434f3 100644 --- a/docs/legacy/copied-from-beats/docs/repositories.asciidoc +++ b/docs/legacy/copied-from-beats/docs/repositories.asciidoc @@ -12,6 +12,8 @@ [[setup-repositories]] === Repositories for APT and YUM +IMPORTANT: {deprecation-notice-installation} + We have repositories available for APT and YUM-based distributions. Note that we provide binary packages, but no source packages. diff --git a/docs/legacy/copied-from-beats/docs/security/linux-seccomp.asciidoc b/docs/legacy/copied-from-beats/docs/security/linux-seccomp.asciidoc index 353580a728e..f1f58944067 100644 --- a/docs/legacy/copied-from-beats/docs/security/linux-seccomp.asciidoc +++ b/docs/legacy/copied-from-beats/docs/security/linux-seccomp.asciidoc @@ -1,6 +1,8 @@ [[linux-seccomp]] == Use Linux Secure Computing Mode (seccomp) +IMPORTANT: {deprecation-notice-config} + beta[] On Linux 3.17 and later, {beatname_uc} can take advantage of secure computing diff --git a/docs/legacy/copied-from-beats/docs/shared-directory-layout.asciidoc b/docs/legacy/copied-from-beats/docs/shared-directory-layout.asciidoc index 83b5c44cdde..ca7e18789f5 100644 --- a/docs/legacy/copied-from-beats/docs/shared-directory-layout.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-directory-layout.asciidoc @@ -12,6 +12,8 @@ [[directory-layout]] === Directory layout +IMPORTANT: {deprecation-notice-installation} + The directory layout of an installation is as follows: [cols="> in the configuration file. endif::serverless[] +[float] ==== Default paths {beatname_uc} uses the following default paths unless you explicitly change them. @@ -100,6 +103,7 @@ ifndef::win_only[] endif::win_only[] ifdef::mac_os[] +[float] ===== brew [cols="> for more details. Edit the configuration file and customize it to match your environment then re-deploy your {beatname_uc} container. endif::[] +[float] ===== Custom image configuration It's possible to embed your {beatname_uc} configuration in a custom image. diff --git a/docs/legacy/copied-from-beats/docs/shared-env-vars.asciidoc b/docs/legacy/copied-from-beats/docs/shared-env-vars.asciidoc index 496f6aa480c..98c80e9967d 100644 --- a/docs/legacy/copied-from-beats/docs/shared-env-vars.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-env-vars.asciidoc @@ -19,6 +19,9 @@ ifdef::standalone[] endif::[] +IMPORTANT: {deprecation-notice-config} +If you're using {fleet} and the Elastic APM integration, please see the {fleet-guide}[Fleet User Guide] instead. + You can use environment variable references in the config file to set values that need to be configurable during deployment. To do this, use: diff --git a/docs/legacy/copied-from-beats/docs/shared-instrumentation.asciidoc b/docs/legacy/copied-from-beats/docs/shared-instrumentation.asciidoc index 9b3d72bfd67..c47a9b35b1d 100644 --- a/docs/legacy/copied-from-beats/docs/shared-instrumentation.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-instrumentation.asciidoc @@ -5,6 +5,8 @@ Instrumentation ++++ +IMPORTANT: {deprecation-notice-config} + Libbeat uses the Elastic APM Go Agent to instrument its publishing pipeline. Currently, only the Elasticsearch output is instrumented. To gain insight into the performance of {beatname_uc}, you can enable this instrumentation and send trace data to APM Server. diff --git a/docs/legacy/copied-from-beats/docs/shared-kerberos-config.asciidoc b/docs/legacy/copied-from-beats/docs/shared-kerberos-config.asciidoc index 305df2e5df1..02ee8a5be30 100644 --- a/docs/legacy/copied-from-beats/docs/shared-kerberos-config.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-kerberos-config.asciidoc @@ -5,6 +5,8 @@ Kerberos ++++ +IMPORTANT: {deprecation-notice-config} + You can specify Kerberos options with any output or input that supports Kerberos, like {es}. The following encryption types are supported: diff --git a/docs/legacy/copied-from-beats/docs/shared-path-config.asciidoc b/docs/legacy/copied-from-beats/docs/shared-path-config.asciidoc index 33390ca7faa..7605cceea30 100644 --- a/docs/legacy/copied-from-beats/docs/shared-path-config.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-path-config.asciidoc @@ -17,6 +17,8 @@ Project paths ++++ +IMPORTANT: {deprecation-notice-config} + The `path` section of the +{beatname_lc}.yml+ config file contains configuration options that define where {beatname_uc} looks for its files. For example, {beatname_uc} looks for the Elasticsearch template file in the configuration path and writes diff --git a/docs/legacy/copied-from-beats/docs/shared-securing-beat.asciidoc b/docs/legacy/copied-from-beats/docs/shared-securing-beat.asciidoc index 6fe015665da..bdad0cb0bf4 100644 --- a/docs/legacy/copied-from-beats/docs/shared-securing-beat.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-securing-beat.asciidoc @@ -5,6 +5,9 @@ Secure ++++ +IMPORTANT: {deprecation-notice-config} +If you're using {fleet} and the Elastic APM integration, please see <> instead. + The following topics provide information about securing the {beatname_uc} process and connecting to a cluster that has {security-features} enabled. diff --git a/docs/legacy/copied-from-beats/docs/shared-ssl-config.asciidoc b/docs/legacy/copied-from-beats/docs/shared-ssl-config.asciidoc index ec0690397a5..870701eac9a 100644 --- a/docs/legacy/copied-from-beats/docs/shared-ssl-config.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-ssl-config.asciidoc @@ -9,6 +9,9 @@ endif::apm-server[] ifdef::apm-server[] == SSL output settings +IMPORTANT: {deprecation-notice-config} +If you're using {fleet} and the Elastic APM integration, please see the {fleet-guide}[Fleet User Guide] instead. + You can specify SSL options with any output that supports SSL, like {es}, {ls}, or Kafka. endif::[] @@ -388,7 +391,7 @@ supports SSL. [[server-certificate-authorities]] ==== `certificate_authorities` -The list of root certificates for client verifications is only required if +The list of root certificates for client verifications is only required if `client_authentication` is configured. If `certificate_authorities` is empty or not set, and `client_authentication` is configured, the system keystore is used. diff --git a/docs/legacy/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc b/docs/legacy/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc index 31cbf73fc62..d0a469c2605 100644 --- a/docs/legacy/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc @@ -13,6 +13,8 @@ [[configuring-ssl-logstash]] == Secure communication with Logstash +IMPORTANT: {deprecation-notice-config} + You can use SSL mutual authentication to secure connections between {beatname_uc} and Logstash. This ensures that {beatname_uc} sends encrypted data to trusted Logstash servers only, and that the Logstash server receives data from trusted {beatname_uc} clients only. diff --git a/docs/legacy/copied-from-beats/docs/shared-systemd.asciidoc b/docs/legacy/copied-from-beats/docs/shared-systemd.asciidoc index 66fadb0afec..3f3cf7a6898 100644 --- a/docs/legacy/copied-from-beats/docs/shared-systemd.asciidoc +++ b/docs/legacy/copied-from-beats/docs/shared-systemd.asciidoc @@ -1,6 +1,8 @@ [[running-with-systemd]] === {beatname_uc} and systemd +IMPORTANT: {deprecation-notice-config} + The DEB and RPM packages include a service unit for Linux systems with systemd. On these systems, you can manage {beatname_uc} by using the usual systemd commands. @@ -10,6 +12,7 @@ We recommend that the {beatname_pkg} process is run as a non-root user. Therefore, that is the default setup for {beatname_uc}'s DEB package and RPM installation. endif::apm-server[] +[float] ==== Start and stop {beatname_uc} Use `systemctl` to start or stop {beatname_uc}: @@ -37,7 +40,7 @@ sudo systemctl enable {beatname_pkg} sudo systemctl disable {beatname_pkg} ------------------------------------------------ - +[float] ==== {beatname_uc} status and logs To get the service status, use `systemctl`: diff --git a/docs/legacy/copied-from-beats/docs/template-config.asciidoc b/docs/legacy/copied-from-beats/docs/template-config.asciidoc index 5699a46dd76..11006586276 100644 --- a/docs/legacy/copied-from-beats/docs/template-config.asciidoc +++ b/docs/legacy/copied-from-beats/docs/template-config.asciidoc @@ -6,6 +6,8 @@ Elasticsearch index template ++++ +IMPORTANT: {deprecation-notice-config} + The `setup.template` section of the +{beatname_lc}.yml+ config file specifies the {ref}/index-templates.html[index template] to use for setting mappings in Elasticsearch. If template loading is enabled (the default), diff --git a/docs/legacy/copied-from-beats/outputs/codec/docs/codec.asciidoc b/docs/legacy/copied-from-beats/outputs/codec/docs/codec.asciidoc index 64068cbb971..53f69f8f7a2 100644 --- a/docs/legacy/copied-from-beats/outputs/codec/docs/codec.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/codec/docs/codec.asciidoc @@ -1,6 +1,8 @@ [[configuration-output-codec]] === Change the output codec +IMPORTANT: {deprecation-notice-config} + For outputs that do not require a specific encoding, you can change the encoding by using the codec configuration. You can specify either the `json` or `format` codec. By default the `json` codec is used. diff --git a/docs/legacy/copied-from-beats/outputs/console/docs/console.asciidoc b/docs/legacy/copied-from-beats/outputs/console/docs/console.asciidoc index f5dc1d97db5..37484eb8013 100644 --- a/docs/legacy/copied-from-beats/outputs/console/docs/console.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/console/docs/console.asciidoc @@ -5,9 +5,11 @@ Console ++++ +IMPORTANT: {deprecation-notice-config} + The Console output writes events in JSON format to stdout. -WARNING: The Console output should be used only for debugging issues as it can produce a large amount of logging data. +WARNING: The Console output should be used only for debugging issues as it can produce a large amount of logging data. To use this output, edit the {beatname_uc} configuration file to disable the {es} output by commenting it out, and enable the console output by adding `output.console`. diff --git a/docs/legacy/copied-from-beats/outputs/elasticsearch/docs/elasticsearch.asciidoc b/docs/legacy/copied-from-beats/outputs/elasticsearch/docs/elasticsearch.asciidoc index fbe9a918db3..75cf7c8793c 100644 --- a/docs/legacy/copied-from-beats/outputs/elasticsearch/docs/elasticsearch.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/elasticsearch/docs/elasticsearch.asciidoc @@ -5,6 +5,8 @@ Elasticsearch ++++ +IMPORTANT: {deprecation-notice-config} + The Elasticsearch output sends events directly to Elasticsearch using the Elasticsearch HTTP API. Example configuration: diff --git a/docs/legacy/copied-from-beats/outputs/fileout/docs/fileout.asciidoc b/docs/legacy/copied-from-beats/outputs/fileout/docs/fileout.asciidoc index a0979f92ef5..9ba0789ad42 100644 --- a/docs/legacy/copied-from-beats/outputs/fileout/docs/fileout.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/fileout/docs/fileout.asciidoc @@ -5,6 +5,8 @@ File ++++ +IMPORTANT: {deprecation-notice-config} + The File output dumps the transactions into a file where each transaction is in a JSON format. Currently, this output is used for testing, but it can be used as input for Logstash. diff --git a/docs/legacy/copied-from-beats/outputs/kafka/docs/kafka.asciidoc b/docs/legacy/copied-from-beats/outputs/kafka/docs/kafka.asciidoc index 026d0431345..85ab68517fc 100644 --- a/docs/legacy/copied-from-beats/outputs/kafka/docs/kafka.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/kafka/docs/kafka.asciidoc @@ -5,6 +5,8 @@ Kafka ++++ +IMPORTANT: {deprecation-notice-config} + The Kafka output sends events to Apache Kafka. To use this output, edit the {beatname_uc} configuration file to disable the {es} diff --git a/docs/legacy/copied-from-beats/outputs/logstash/docs/logstash.asciidoc b/docs/legacy/copied-from-beats/outputs/logstash/docs/logstash.asciidoc index 910551f9252..e643a496856 100644 --- a/docs/legacy/copied-from-beats/outputs/logstash/docs/logstash.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/logstash/docs/logstash.asciidoc @@ -5,6 +5,8 @@ Logstash ++++ +IMPORTANT: {deprecation-notice-config} + The {ls} output sends events directly to {ls} by using the lumberjack protocol, which runs over TCP. {ls} allows for additional processing and routing of generated events. diff --git a/docs/legacy/copied-from-beats/outputs/redis/docs/redis.asciidoc b/docs/legacy/copied-from-beats/outputs/redis/docs/redis.asciidoc index 31e6db65f96..d0b49b8e90a 100644 --- a/docs/legacy/copied-from-beats/outputs/redis/docs/redis.asciidoc +++ b/docs/legacy/copied-from-beats/outputs/redis/docs/redis.asciidoc @@ -5,6 +5,8 @@ Redis ++++ +IMPORTANT: {deprecation-notice-config} + The Redis output inserts the events into a Redis list or a Redis channel. This output plugin is compatible with the https://www.elastic.co/guide/en/logstash/current/plugins-inputs-redis.html[Redis input plugin] for Logstash. diff --git a/docs/legacy/data-ingestion.asciidoc b/docs/legacy/data-ingestion.asciidoc index f658c41d3b7..01a8d1c894e 100644 --- a/docs/legacy/data-ingestion.asciidoc +++ b/docs/legacy/data-ingestion.asciidoc @@ -1,6 +1,9 @@ [[tune-data-ingestion]] == Tune data ingestion +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + This section explains how to adapt data ingestion according to your needs. * <> @@ -14,6 +17,8 @@ This section explains how to adapt data ingestion according to your needs. APM Server ++++ +IMPORTANT: {deprecation-notice-data} + * <> * <> * <> @@ -88,6 +93,9 @@ Increasing the <> default Elasticsearch ++++ +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + The Elasticsearch reference provides insight on tuning Elasticsearch. {ref}/tune-for-indexing-speed.html[Tune for indexing speed] provides information on: diff --git a/docs/legacy/events-api.asciidoc b/docs/legacy/events-api.asciidoc index 70493849faa..80cf239d443 100644 --- a/docs/legacy/events-api.asciidoc +++ b/docs/legacy/events-api.asciidoc @@ -5,6 +5,9 @@ Events intake ++++ +IMPORTANT: {deprecation-notice-api} +If you've already upgraded, see <>. + NOTE: Most users do not need to interact directly with the events intake API. The events intake API is what we call the internal protocol that APM agents use to talk to the APM Server. diff --git a/docs/legacy/exploring-es-data.asciidoc b/docs/legacy/exploring-es-data.asciidoc index b9d949c8d02..b0044729183 100644 --- a/docs/legacy/exploring-es-data.asciidoc +++ b/docs/legacy/exploring-es-data.asciidoc @@ -1,6 +1,9 @@ [[exploring-es-data]] = Explore data in {es} +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + Elastic APM stores data for each {apm-overview-ref-v}/apm-data-model.html[event type] in separate indices. By default, <> is enabled and event data is stored using the following index naming patterns: diff --git a/docs/legacy/feature-roles.asciidoc b/docs/legacy/feature-roles.asciidoc index 9932a88bf81..9a6f4517a8e 100644 --- a/docs/legacy/feature-roles.asciidoc +++ b/docs/legacy/feature-roles.asciidoc @@ -2,6 +2,8 @@ [[feature-roles]] == Grant users access to secured resources +IMPORTANT: {deprecation-notice-config} + You can use role-based access control to grant users access to secured resources. The roles that you set up depend on your organization's security requirements and the minimum privileges required to use specific features. @@ -39,6 +41,8 @@ In general, there are three types of privileges you'll work with: Create a _setup_ user ++++ +IMPORTANT: {deprecation-notice-config} + IMPORTANT: Setting up {beatname_uc} is an admin-level task that requires extra privileges. As a best practice, grant the setup role to administrators only, and use a more restrictive role for event publishing. @@ -156,6 +160,8 @@ See <> for more information. Create a _writer_ user ++++ +IMPORTANT: {deprecation-notice-config} + IMPORTANT: To minimize the privileges required by the writer role, use the <> to pre-load dependencies. This section assumes that you've done that. @@ -240,6 +246,8 @@ that has the following privileges: Create a _monitoring_ user ++++ +IMPORTANT: {deprecation-notice-config} + {es-security-features} provides built-in users and roles for publishing and viewing monitoring data. The privileges and roles needed to publish monitoring data depend on the method used to collect that data. @@ -381,6 +389,8 @@ need to view monitoring data for {beatname_uc}: Create an _API key_ user ++++ +IMPORTANT: {deprecation-notice-config} + You can configure <> to authorize requests to APM Server. To create an APM Server user with the required privileges for creating and managing API keys: @@ -452,6 +462,8 @@ PUT _security/role/apm_api_key <1> Create a _central config_ user ++++ +IMPORTANT: {deprecation-notice-config} + [[privileges-agent-central-config-server]] ==== APM Server central configuration management @@ -496,6 +508,8 @@ See {kibana-ref}/apm-app-central-config-user.html[APM app central configuration [[more-security-roles]] === Additional APM users and roles +IMPORTANT: {deprecation-notice-config} + In addition to the {beatname_uc} users described in this documentation, you'll likely need to create users for other APM tasks: diff --git a/docs/legacy/getting-started-apm-server.asciidoc b/docs/legacy/getting-started-apm-server.asciidoc index caf15be56c8..38211a06a4f 100644 --- a/docs/legacy/getting-started-apm-server.asciidoc +++ b/docs/legacy/getting-started-apm-server.asciidoc @@ -5,6 +5,8 @@ Get started ++++ +IMPORTANT: {deprecation-notice-installation} + // This section was copied from the APM Overview // Switch to tagged regions when available The easiest way to get started with APM Server is by using our @@ -58,6 +60,8 @@ configure, and start APM Server: [[installing]] === Step 1: Install +IMPORTANT: {deprecation-notice-installation} + NOTE: *Before you begin*: If you haven't installed the {stack}, do that now. See {stack-gs}/get-started-elastic-stack.html[Getting started with the {stack}]. @@ -223,6 +227,8 @@ See <> for deploying Docker containers. [[apm-server-configuration]] === Step 2: Set up and configure +IMPORTANT: {deprecation-notice-installation} + [float] ==== Elastic Cloud @@ -234,21 +240,13 @@ Full details are available in the {cloud}/ec-manage-apm-settings.html[APM user s [float] ==== Self installation -[float] -===== APM integration for Elastic Agent - -If you're running the <>, you can configure settings via {fleet-guide}/agent-policy.html[Elastic Agent policies]. - -[float] -===== Standalone - You can edit the `apm-server.yml` configuration file to customize it to your needs. The location of this file varies by platform, but the <> will help you locate it. All available configuration options are outlined in {apm-server-ref-v}/configuring-howto-apm-server.html[configuring APM Server]. [float] -====== Standalone setup (data streams) +===== Standalone setup (data streams) If you're running APM Server as a standalone process, we recommend that you configure <> to write events to data streams in the same way as the <>. You will need to install the APM @@ -256,9 +254,9 @@ integration package to set up Elasticsearch before APM Server becomes operative. [float] [[index-template-config]] -====== Standalone setup (classic indices) +===== Standalone setup (classic indices) -deprecated::[7.16.0,Users should now use the <> or configure <>.] +deprecated::[7.16.0,Users should now use the <> or configure <>. ] When running APM Server standalone with classic indices, we recommend that you run the `setup` command before starting {beatname_uc}. @@ -302,6 +300,8 @@ All available configuration options are outlined in [[apm-server-starting]] === Step 3: Start +IMPORTANT: {deprecation-notice-installation} + In a production environment, you would put APM Server on its own machines, similar to how you run Elasticsearch. You _can_ run it on the same machines as Elasticsearch, but this is not recommended, @@ -371,6 +371,8 @@ brew services start elastic/tap/apm-server-full [[next-steps]] === Step 4: Next steps +IMPORTANT: {deprecation-notice-installation} + // 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! diff --git a/docs/legacy/guide/apm-data-model.asciidoc b/docs/legacy/guide/apm-data-model.asciidoc index 130cced9f5e..96022cc008e 100644 --- a/docs/legacy/guide/apm-data-model.asciidoc +++ b/docs/legacy/guide/apm-data-model.asciidoc @@ -1,6 +1,9 @@ [[apm-data-model]] == Data Model +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + Elastic APM agents capture different types of information from within their instrumented applications. These are known as events, and can be `spans`, `transactions`, `errors`, or `metrics`. @@ -14,6 +17,9 @@ Events can contain additional <> which further enriches your [[transaction-spans]] === Spans +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + *Spans* contain information about the execution of a specific code path. They measure from the start to the end of an activity, and they can have a parent/child relationship with other spans. @@ -71,6 +77,9 @@ the APM app will calculate the difference and display a message. [[transactions]] === Transactions +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + *Transactions* are a special kind of <> that have additional attributes associated with them. They describe an event captured by an Elastic APM agent instrumenting a service. You can think of transactions as the highest level of work you’re measuring within a service. @@ -121,6 +130,9 @@ Transactions are stored in {apm-server-ref-v}/transaction-indices.html[transacti [[errors]] === Errors +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + An error event contains at least information about the original `exception` that occurred or about a `log` created when the exception occurred. @@ -151,6 +163,9 @@ Errors are stored in {apm-server-ref-v}/error-indices.html[error indices]. [[metrics]] === Metrics +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + APM agents automatically pick up basic host-level metrics, including system and process-level CPU and memory metrics. Agent specific metrics are also available, @@ -179,6 +194,9 @@ For a full list of tracked metrics, see the relevant agent documentation: [[metadata]] === Metadata +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + Metadata can enrich your events and make application performance monitoring even more useful. Let's explore the different types of metadata that Elastic APM offers. diff --git a/docs/legacy/guide/apm-doc-directory.asciidoc b/docs/legacy/guide/apm-doc-directory.asciidoc index b1c0797855f..9d485a9f315 100644 --- a/docs/legacy/guide/apm-doc-directory.asciidoc +++ b/docs/legacy/guide/apm-doc-directory.asciidoc @@ -1,12 +1,15 @@ [[components]] -=== Components and documentation +== Components and documentation + +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. Elastic APM consists of four components: *APM agents*, *APM Server*, *Elasticsearch*, and *Kibana*. image::./../legacy/guide/images/apm-architecture-cloud.png[Architecture of Elastic APM] [float] -==== APM Agents +=== 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. @@ -27,7 +30,7 @@ Each agent has its own documentation: * {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] [float] -==== APM Server +=== APM Server APM Server is a free and open application that receives performance data from your APM agents. It's a {apm-server-ref-v}/overview.html#why-separate-component[separate component by design], @@ -45,14 +48,14 @@ Here you can learn more about {apm-server-ref-v}/getting-started-apm-server.html {apm-server-ref-v}/monitoring.html[monitoring], and more. [float] -==== Elasticsearch +=== Elasticsearch {ref}/index.html[Elasticsearch] 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. Elasticsearch is used to store APM performance metrics and make use of its aggregations. [float] -==== Kibana APM app +=== Kibana APM app {kibana-ref}/index.html[Kibana] is a free and open analytics and visualization platform designed to work with Elasticsearch. You use Kibana to search, view, and interact with data stored in Elasticsearch. diff --git a/docs/legacy/guide/cross-cluster-search.asciidoc b/docs/legacy/guide/cross-cluster-search.asciidoc index a8fa8bde14a..96c8774eccc 100644 --- a/docs/legacy/guide/cross-cluster-search.asciidoc +++ b/docs/legacy/guide/cross-cluster-search.asciidoc @@ -1,6 +1,9 @@ [[apm-cross-cluster-search]] === Cross-cluster search +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + Elastic APM utilizes Elasticsearch's cross-cluster search functionality. Cross-cluster search lets you run a single search request against one or more {ref}/modules-remote-clusters.html[remote clusters] -- diff --git a/docs/legacy/guide/data-security.asciidoc b/docs/legacy/guide/data-security.asciidoc index d9c4dc736eb..2ee54d5c77f 100644 --- a/docs/legacy/guide/data-security.asciidoc +++ b/docs/legacy/guide/data-security.asciidoc @@ -1,6 +1,9 @@ [[data-security]] === Data security +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + When setting up Elastic APM, it's essential to review all captured data carefully to ensure it does not contain sensitive information. When it does, we offer several different ways to filter, manipulate, or obfuscate this data. diff --git a/docs/legacy/guide/distributed-tracing.asciidoc b/docs/legacy/guide/distributed-tracing.asciidoc index ce3e03d6e37..fb1035eac6b 100644 --- a/docs/legacy/guide/distributed-tracing.asciidoc +++ b/docs/legacy/guide/distributed-tracing.asciidoc @@ -1,6 +1,9 @@ [[distributed-tracing]] === Distributed tracing +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + A `trace` is a group of <> and <> with a common root. Each `trace` tracks the entirety of a single request. When a `trace` travels through multiple services, as is common in a microservice architecture, diff --git a/docs/legacy/guide/features.asciidoc b/docs/legacy/guide/features.asciidoc index 2758c432081..8a2dcf39174 100644 --- a/docs/legacy/guide/features.asciidoc +++ b/docs/legacy/guide/features.asciidoc @@ -1,6 +1,9 @@ [[apm-features]] == Elastic APM features +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + ++++ Features ++++ diff --git a/docs/legacy/guide/index.asciidoc b/docs/legacy/guide/index.asciidoc index a604534773b..b65139f9ba6 100644 --- a/docs/legacy/guide/index.asciidoc +++ b/docs/legacy/guide/index.asciidoc @@ -3,11 +3,6 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :apm-ref-all: https://www.elastic.co/guide/en/apm/get-started/ -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/get-started[elastic.co] -endif::[] - ifndef::apm-integration-docs[] [[gettting-started]] = APM Overview @@ -20,12 +15,11 @@ ifdef::apm-integration-docs[] :apm-server-ref-v: {apm-guide-ref} :apm-server-ref: {apm-guide-ref} -// change the name -[[gettting-started]] +[[legacy-apm-overview]] = Legacy APM Overview -endif::[] include::./overview.asciidoc[] +endif::[] include::./apm-doc-directory.asciidoc[] diff --git a/docs/legacy/guide/install-and-run.asciidoc b/docs/legacy/guide/install-and-run.asciidoc index d1965c4a39e..f9334478e64 100644 --- a/docs/legacy/guide/install-and-run.asciidoc +++ b/docs/legacy/guide/install-and-run.asciidoc @@ -1,6 +1,8 @@ [[install-and-run]] == Quick start guide +IMPORTANT: {deprecation-notice-installation} + This guide describes how to get started quickly with Elastic APM. You’ll learn how to: * Spin up {es}, {kib}, and APM Server on {ess} diff --git a/docs/legacy/guide/obs-integrations.asciidoc b/docs/legacy/guide/obs-integrations.asciidoc index cae4cb78204..7576ffbb060 100644 --- a/docs/legacy/guide/obs-integrations.asciidoc +++ b/docs/legacy/guide/obs-integrations.asciidoc @@ -1,6 +1,9 @@ [[observability-integrations]] === Observability integrations +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + Elastic APM supports integrations with other observability solutions. // remove float tag once other integrations are added diff --git a/docs/legacy/guide/opentelemetry-elastic.asciidoc b/docs/legacy/guide/opentelemetry-elastic.asciidoc index 328ffb10bd6..ec99920dc75 100644 --- a/docs/legacy/guide/opentelemetry-elastic.asciidoc +++ b/docs/legacy/guide/opentelemetry-elastic.asciidoc @@ -1,6 +1,9 @@ [[open-telemetry-elastic]] === OpenTelemetry integration +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + :ot-spec: https://github.com/open-telemetry/opentelemetry-specification/blob/master/README.md :ot-contrib: https://github.com/open-telemetry/opentelemetry-collector-contrib :ot-repo: https://github.com/open-telemetry/opentelemetry-collector @@ -20,6 +23,7 @@ Elastic OpenTelemetry integrations allow you to reuse your existing OpenTelemetr instrumentation to quickly analyze distributed traces and metrics to help you monitor business KPIs and technical components with the {stack}. +[float] [[open-telemetry-elastic-protocol]] ==== APM Server native support of OpenTelemetry protocol @@ -75,6 +79,7 @@ Please note the required space between `Bearer` and `an_apm_secret_token`, and ` You are now ready to collect traces and <> before <> and <> in {kib}. +[float] [[open-telemetry-collector]] ===== Connect OpenTelemetry Collector instances @@ -126,6 +131,7 @@ and built-in dashboards. You're now ready to export traces and metrics from your services and applications. +[float] [[open-telemetry-elastic-metrics]] ==== Collect metrics @@ -152,6 +158,7 @@ public void createOrder(HttpServletRequest request) { See the https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md[Open Telemetry Metrics API] for more information. +[float] [[open-telemetry-elastic-verify]] ===== Verify OpenTelemetry metrics data @@ -169,6 +176,7 @@ include::../../shared/open-kibana/open-kibana-widget.asciidoc[] . Narrow your search with a known OpenTelemetry field. For example, if you have an `order_value` field, add `order_value: *` to your search to return only OpenTelemetry metrics documents. +[float] [[open-telemetry-elastic-kibana]] ===== Visualize in {kib} @@ -213,6 +221,7 @@ Both visualizations are now displayed on your custom dashboard. IMPORTANT: By default, Discover shows data for the last 15 minutes. If you have a time-based index and no data displays, you might need to increase the time range. +[float] [[open-telemetry-aws-lambda-elastic]] ==== AWS Lambda Support @@ -220,6 +229,7 @@ AWS Lambda functions can be instrumented with OpenTelemetry and monitored with E To get started, follow the official AWS Distro for OpenTelemetry Lambda https://aws-otel.github.io/docs/getting-started/lambda[getting started documentation] and configure the OpenTelemetry Collector to output traces and metrics to your Elastic cluster. +[float] [[open-telemetry-aws-lambda-elastic-java]] ===== Instrumenting AWS Lambda Java functions @@ -296,6 +306,7 @@ Lambda layer for OpenTelemetry] (e.g. `arn:aws:lambda:eu-west-1:901920570463:lay *** `OTEL_PROPAGATORS="tracecontext, baggage"` to override the default setting that also enables X-Ray headers causing interferences between OpenTelemetry and X-Ray *** `OPENTELEMETRY_COLLECTOR_CONFIG_FILE="/var/task/opentelemetry-collector.yaml"` to specify the path to your OpenTelemetry Collector configuration +[float] [[open-telemetry-aws-lambda-elastic-java-terraform]] ===== Instrumenting AWS Lambda Java functions with Terraform @@ -306,6 +317,7 @@ Here is an example of AWS Lambda Java function managed with Terraform and the ht * Sample Terraform code: https://github.com/cyrille-leclerc/my-serverless-shopping-cart/tree/main/checkout-function/deploy * Note that the Terraform code to manage the HTTP API Gateway (https://github.com/cyrille-leclerc/my-serverless-shopping-cart/tree/main/utils/terraform/api-gateway-proxy[here]) is copied from the official OpenTelemetry Lambda sample https://github.com/open-telemetry/opentelemetry-lambda/tree/e72467a085a2a6e57af133032f85ac5b8bbbb8d1/utils[here] +[float] [[open-telemetry-aws-lambda-elastic-nodejs]] ===== Instrumenting AWS Lambda Node.js functions @@ -360,7 +372,7 @@ Lambda layer for OpenTelemetry]. For example, `arn:aws:lambda:eu-west-1:90192057 ** `OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:55681/v1/traces"` this environment variable is required to be set until https://github.com/open-telemetry/opentelemetry-js/pull/2331[PR #2331] is merged and released. ** `OTEL_TRACES_SAMPLER="AlwaysOn"` define the required sampler strategy if it is not sent from the caller. Note that `Always_on` can potentially create a very large amount of data, so in production set the correct sampling configuration, as per the https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampling[specification]. - +[float] [[open-telemetry-aws-lambda-elastic-nodejs-terraform]] ===== Instrumenting AWS Lambda Node.js functions with Terraform @@ -370,10 +382,11 @@ Here is an example of AWS Lambda Node.js function managed with Terraform and the * https://github.com/michaelhyatt/terraform-aws-nodejs-api-worker-otel/tree/v0.23[Sample Terraform code] +[float] [[elastic-open-telemetry-known-limitations]] ==== Limitations - +[float] [[elastic-open-telemetry-traces-limitations]] ===== OpenTelemetry traces @@ -382,11 +395,13 @@ Here is an example of AWS Lambda Node.js function managed with Terraform and the * Inability in APM views to view the "Time Spent by Span Type" https://github.com/elastic/apm-server/issues/5747[#5747] * Metrics derived from traces (throughput, latency, and errors) are not accurate when traces are sampled before being ingested by Elastic Observability (ie by an OpenTelemetry Collector or OpenTelemetry APM agent or SDK) https://github.com/elastic/apm/issues/472[#472] +[float] [[elastic-open-telemetry-metrics-limitations]] ===== OpenTelemetry metrics * Inability to see host metrics in Elastic Metrics Infrastructure view when using the OpenTelemetry Collector host metrics receiver https://github.com/elastic/apm-server/issues/5310[#5310] +[float] [[elastic-open-telemetry-logs-limitations]] ===== OpenTelemetry logs diff --git a/docs/legacy/guide/opentracing.asciidoc b/docs/legacy/guide/opentracing.asciidoc index 19d71199e64..77c10903663 100644 --- a/docs/legacy/guide/opentracing.asciidoc +++ b/docs/legacy/guide/opentracing.asciidoc @@ -1,6 +1,8 @@ [[opentracing]] === OpenTracing bridge +IMPORTANT: {deprecation-notice-data} + Most Elastic APM agents have https://opentracing.io/[OpenTracing] compatible bridges. The OpenTracing bridge allows you to create Elastic APM <> and <> using the OpenTracing API. diff --git a/docs/legacy/guide/overview.asciidoc b/docs/legacy/guide/overview.asciidoc index b614960d605..44da2ae86aa 100644 --- a/docs/legacy/guide/overview.asciidoc +++ b/docs/legacy/guide/overview.asciidoc @@ -1,16 +1,12 @@ -ifndef::apm-integration-docs[] -[[overview]] -== Free and open application performance monitoring -endif::[] +**** +There are two ways to install, run, and manage Elastic APM: -ifdef::apm-integration-docs[] -[[legacy-apm-overview]] -== Free and open application performance monitoring -endif::[] +* With the Elastic APM integration +* With the standalone (legacy) APM Server binary -++++ -What is APM? -++++ +This documentation focuses on option two: the **standalone (legacy) APM Server binary**. +{deprecation-notice-installation} +**** 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, by @@ -27,9 +23,9 @@ Elastic APM agents automatically pick up basic host-level metrics and agent-spec like JVM metrics in the Java Agent, and Go runtime metrics in the Go Agent. [float] -=== Give Elastic APM a try +== 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. +NOTE: These docs will indiscriminately use the word "service" for both services and applications. \ No newline at end of file diff --git a/docs/legacy/guide/quick-start-overview.asciidoc b/docs/legacy/guide/quick-start-overview.asciidoc index 0d2d31d20d3..44a7ada8fab 100644 --- a/docs/legacy/guide/quick-start-overview.asciidoc +++ b/docs/legacy/guide/quick-start-overview.asciidoc @@ -2,6 +2,8 @@ [[quick-start-overview]] === Quick start development environment +IMPORTANT: {deprecation-notice-installation} + // This tagged region is reused in the Observability docs. // tag::dev-environment[] ifeval::["{release-state}"=="unreleased"] diff --git a/docs/legacy/guide/rum.asciidoc b/docs/legacy/guide/rum.asciidoc index e7e38bcbd3e..962e737b83c 100644 --- a/docs/legacy/guide/rum.asciidoc +++ b/docs/legacy/guide/rum.asciidoc @@ -1,5 +1,9 @@ [[rum]] === Real User Monitoring (RUM) + +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + 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}/configuration-rum.html[enable RUM support] in the APM Server. diff --git a/docs/legacy/guide/trace-sampling.asciidoc b/docs/legacy/guide/trace-sampling.asciidoc index 46afb2d41e8..48c160674ee 100644 --- a/docs/legacy/guide/trace-sampling.asciidoc +++ b/docs/legacy/guide/trace-sampling.asciidoc @@ -1,6 +1,9 @@ [[trace-sampling]] === Transaction sampling +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + Elastic APM supports head-based, probability sampling. _Head-based_ means the sampling decision for each trace is made when that trace is initiated. _Probability sampling_ means that each trace has a defined and equal probability of being sampled. diff --git a/docs/legacy/guide/troubleshooting.asciidoc b/docs/legacy/guide/troubleshooting.asciidoc index 13ea1bfbf07..337f44e59b1 100644 --- a/docs/legacy/guide/troubleshooting.asciidoc +++ b/docs/legacy/guide/troubleshooting.asciidoc @@ -1,6 +1,9 @@ [[troubleshooting-guide]] == Troubleshooting +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, see <>. + If you run into trouble, there are three places you can look for help. [float] diff --git a/docs/legacy/high-availability.asciidoc b/docs/legacy/high-availability.asciidoc index af93e4eb1e8..2bbaf842287 100644 --- a/docs/legacy/high-availability.asciidoc +++ b/docs/legacy/high-availability.asciidoc @@ -1,6 +1,8 @@ [[high-availability]] === High Availability +IMPORTANT: {deprecation-notice-installation} + To achieve high availability you can place multiple instances of APM Server behind a regular HTTP load balancer, for example HAProxy or nginx. diff --git a/docs/legacy/howto.asciidoc b/docs/legacy/howto.asciidoc index 0ae840a61ce..68651422676 100644 --- a/docs/legacy/howto.asciidoc +++ b/docs/legacy/howto.asciidoc @@ -1,6 +1,9 @@ [[howto-guides]] = How-to guides +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + Learn how to perform common {beatname_uc} configuration and management tasks. * <> diff --git a/docs/legacy/ilm-reference.asciidoc b/docs/legacy/ilm-reference.asciidoc index d7dd9c2da0b..5cd005d6447 100644 --- a/docs/legacy/ilm-reference.asciidoc +++ b/docs/legacy/ilm-reference.asciidoc @@ -2,12 +2,12 @@ [role="xpack"] == Configure Index lifecycle management (ILM) -deprecated::[7.16.0,Users should now use the <>. See <>] - ++++ Index lifecycle management ++++ +deprecated::[7.16.0,Users should now use the <>. If you're already using the APM integration, please see <> instead. ] + The {ref}/getting-started-index-lifecycle-management.html[index lifecycle management] (ILM) feature in {es} allows you to automate the lifecycle of your APM Server indices as they grow and age. diff --git a/docs/legacy/ilm.asciidoc b/docs/legacy/ilm.asciidoc index 1a2b2eb7868..94afb0c9f82 100644 --- a/docs/legacy/ilm.asciidoc +++ b/docs/legacy/ilm.asciidoc @@ -2,7 +2,8 @@ [role="xpack"] == Custom index lifecycle management with APM Server -deprecated::[7.16.0,Users should now use the <>. See <>] +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. ++++ Customize index lifecycle management diff --git a/docs/legacy/index.asciidoc b/docs/legacy/index.asciidoc index d0255e3c65f..b0ffdc5cfbf 100644 --- a/docs/legacy/index.asciidoc +++ b/docs/legacy/index.asciidoc @@ -45,11 +45,6 @@ endif::[] :downloads: https://artifacts.elastic.co/downloads/apm-server -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/server[elastic.co] -endif::[] - ifndef::apm-integration-docs[] [[apm-server]] = APM Server Reference @@ -62,20 +57,11 @@ ifdef::apm-integration-docs[] :apm-server-ref-v: {apm-guide-ref} :apm-server-ref: {apm-guide-ref} -//change the name -[[apm-server]] +[[overview]] = Legacy APM Server Reference -// add deprecation notice -deprecated::[7.16.0] - -**** -🚨🚨🚨🚨 -Add some note here about what was deprecated and why. -**** -endif::[] - include::./overview.asciidoc[] +endif::[] include::./getting-started-apm-server.asciidoc[] @@ -101,6 +87,4 @@ include::./troubleshooting.asciidoc[leveloffset=+1] include::./upgrading.asciidoc[leveloffset=+1] -include::{apm-package-dir}/apm-integration.asciidoc[] - include::./redirects.asciidoc[] diff --git a/docs/legacy/intake-api.asciidoc b/docs/legacy/intake-api.asciidoc index 05d09a4d2c3..5df2cf21ba4 100644 --- a/docs/legacy/intake-api.asciidoc +++ b/docs/legacy/intake-api.asciidoc @@ -1,6 +1,9 @@ [[intake-api]] = API +IMPORTANT: {deprecation-notice-api} +If you've already upgraded, see <>. + The APM Server exposes endpoints for: * <> diff --git a/docs/legacy/jaeger-reference.asciidoc b/docs/legacy/jaeger-reference.asciidoc index 464df44afa4..eec427e83a9 100644 --- a/docs/legacy/jaeger-reference.asciidoc +++ b/docs/legacy/jaeger-reference.asciidoc @@ -5,6 +5,9 @@ Jaeger ++++ +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, please see <> instead. + // this content is reused in the how-to guides // tag::jaeger-intro[] Elastic APM integrates with https://www.jaegertracing.io/[Jaeger], an open-source, distributed tracing system. diff --git a/docs/legacy/jaeger-support.asciidoc b/docs/legacy/jaeger-support.asciidoc index f7b89d300e2..1c0614ceda9 100644 --- a/docs/legacy/jaeger-support.asciidoc +++ b/docs/legacy/jaeger-support.asciidoc @@ -5,6 +5,9 @@ Integrate with Jaeger ++++ +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + include::./jaeger-reference.asciidoc[tag=jaeger-intro] [float] diff --git a/docs/legacy/overview.asciidoc b/docs/legacy/overview.asciidoc index 595c7cb8ab9..a6861bef8fb 100644 --- a/docs/legacy/overview.asciidoc +++ b/docs/legacy/overview.asciidoc @@ -1,5 +1,12 @@ -[[overview]] -== Overview +**** +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 two: the **standalone (legacy) APM Server binary**. +{deprecation-notice-installation} +**** The APM Server receives data from APM agents and transforms them into Elasticsearch documents. It does this by exposing an HTTP server endpoint to which agents stream the APM data they collect. diff --git a/docs/legacy/secure-communication-agents.asciidoc b/docs/legacy/secure-communication-agents.asciidoc index ee9f43cce5b..bcc1596e348 100644 --- a/docs/legacy/secure-communication-agents.asciidoc +++ b/docs/legacy/secure-communication-agents.asciidoc @@ -1,6 +1,9 @@ [[secure-communication-agents]] == Secure communication with APM agents +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, see <>. + Communication between APM agents and APM Server can be both encrypted and authenticated. Encryption is achievable through <>. @@ -25,12 +28,18 @@ for the RUM agent (through the browser) and the Jaeger agent. [[ssl-setup]] === SSL/TLS communication +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, see <>. + // Use the shared ssl short description include::./ssl-input.asciidoc[] [[api-key-legacy]] === API keys +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, see <>. + NOTE: API keys are sent as plain-text, so they only provide security when used in combination with <>. They are not applicable for agents running on clients, like the RUM agent, @@ -492,6 +501,9 @@ The old configuration will continue to work until 8.0.0, and the new configurati [[secret-token-legacy]] === Secret token +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, see <>. + You can configure a secret token to authorize requests to the APM Server. This ensures that only your agents are able to send data to your APM servers. Both the agents and the APM servers have to be configured with the same secret token. @@ -581,6 +593,9 @@ This ensures encryption, but does not verify that you are sending data to the co [[secure-communication-unauthenticated]] === Anonymous authentication +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, see <>. + Elastic APM agents can send unauthenticated (anonymous) events to the APM Server. This is useful for agents that run on clients, like the Real User Monitoring (RUM) agent running in a browser, or the iOS/Swift agent running in a user application. diff --git a/docs/legacy/server-info.asciidoc b/docs/legacy/server-info.asciidoc index 9dc403323af..8594aa8096e 100644 --- a/docs/legacy/server-info.asciidoc +++ b/docs/legacy/server-info.asciidoc @@ -5,6 +5,9 @@ Server information ++++ +IMPORTANT: {deprecation-notice-api} +If you've already upgraded, see <>. + The APM Server exposes an API endpoint to query general server information. This lightweight endpoint is useful as a server up/down healthcheck. diff --git a/docs/legacy/setting-up-and-running.asciidoc b/docs/legacy/setting-up-and-running.asciidoc index 042ead0df62..aaedceea193 100644 --- a/docs/legacy/setting-up-and-running.asciidoc +++ b/docs/legacy/setting-up-and-running.asciidoc @@ -6,6 +6,8 @@ Set up ++++ +IMPORTANT: {deprecation-notice-installation} + Before reading this section, see the <> for basic installation and running instructions. diff --git a/docs/legacy/sourcemap-api.asciidoc b/docs/legacy/sourcemap-api.asciidoc index 1708cbed0a2..2315f2af64b 100644 --- a/docs/legacy/sourcemap-api.asciidoc +++ b/docs/legacy/sourcemap-api.asciidoc @@ -5,6 +5,9 @@ Source map upload ++++ +IMPORTANT: {deprecation-notice-api} +If you've already upgraded, see <>. + IMPORTANT: You must <> in the APM Server for this endpoint to work. The APM Server exposes an API endpoint to upload source maps for real user monitoring (RUM). diff --git a/docs/legacy/sourcemaps.asciidoc b/docs/legacy/sourcemaps.asciidoc index c1ec03b7eb9..edf963cf0a9 100644 --- a/docs/legacy/sourcemaps.asciidoc +++ b/docs/legacy/sourcemaps.asciidoc @@ -5,6 +5,9 @@ Create and upload source maps (RUM) ++++ +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + NOTE: This guide is only for standalone APM Server users. Users running the <> need to use the Kibana {kibana-ref}/rum-sourcemap-api.html[source map upload API] instead. diff --git a/docs/legacy/ssl-input-settings.asciidoc b/docs/legacy/ssl-input-settings.asciidoc index bc228935323..97ce13d657e 100644 --- a/docs/legacy/ssl-input-settings.asciidoc +++ b/docs/legacy/ssl-input-settings.asciidoc @@ -1,6 +1,9 @@ [[agent-server-ssl]] === SSL input settings +IMPORTANT: {deprecation-notice-config} +If you've already upgraded, please see <> instead. + You can specify the following options in the `apm-server.ssl` section of the +{beatname_lc}.yml+ config file. They apply to SSL/TLS communication between the APM Server and APM Agents. diff --git a/docs/legacy/storage-management.asciidoc b/docs/legacy/storage-management.asciidoc index d594a607955..c6ed4fe68e0 100644 --- a/docs/legacy/storage-management.asciidoc +++ b/docs/legacy/storage-management.asciidoc @@ -5,6 +5,9 @@ Manage Storage ++++ +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + * <> * <> * <> @@ -14,6 +17,9 @@ [[sizing-guide]] === Storage and sizing guide +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + APM processing and storage costs are largely dominated by transactions, spans, and stack frames. * {apm-overview-ref-v}/transactions.html[*Transactions*] describe an event captured by an Elastic APM agent instrumenting a service. @@ -41,7 +47,7 @@ How little or much you use these APIs will also impact what a typical transactio If your sampling rate is very small, transactions will be the dominate storage cost. -Here's a speculative reference: +Here's a speculative reference: [options="header"] |======================================================================= @@ -70,8 +76,8 @@ These numbers do not account for Elasticsearch compression. APM data compresses quite well, so the storage cost in Elasticsearch will be considerably less: -* Indexing 100 unsampled transactions per second for 1 hour results in 360,000 documents. These documents use around **50 Mb** of disk space. -* Indexing 10 transactions per second for 1 hour, each transaction with 10 spans, each span with 10 stack frames, results in 396,000 documents. These documents use around **200 Mb** of disk space. +* Indexing 100 unsampled transactions per second for 1 hour results in 360,000 documents. These documents use around **50 Mb** of disk space. +* Indexing 10 transactions per second for 1 hour, each transaction with 10 spans, each span with 10 stack frames, results in 396,000 documents. These documents use around **200 Mb** of disk space. * Indexing 25 transactions per second for 1 hour, each transaction with 25 spans, each span with 25 stack frames, results in 2,340,000 documents. These documents use around **1.2 Gb** of disk space. NOTE: These examples were indexing the same data over and over with minimal variation. Because of that, the compression ratios observed of 80-90% are somewhat optimistic. @@ -79,6 +85,9 @@ NOTE: These examples were indexing the same data over and over with minimal vari [[processing-performance]] === Processing and performance +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + APM Server performance depends on a number of factors: memory and CPU available, network latency, transaction sizes, workload patterns, agent and server settings, versions, and protocol. @@ -100,7 +109,7 @@ As a reminder, events are |Transaction/Instance |512Mb Instance |2Gb Instance |8Gb Instance |Small transactions -_5 spans with 5 stack frames each_ |600 events/second |1200 events/second |4800 events/second +_5 spans with 5 stack frames each_ |600 events/second |1200 events/second |4800 events/second |Medium transactions _15 spans with 15 stack frames each_ |300 events/second |600 events/second |2400 events/second @@ -119,11 +128,14 @@ Don't forget that the APM Server is stateless. Several instances running do not need to know about each other. This means that with a properly sized Elasticsearch instance, APM Server scales out linearly. -NOTE: RUM deserves special consideration. The RUM agent runs in browsers, and there can be many thousands reporting to an APM Server with very variable network latency. +NOTE: RUM deserves special consideration. The RUM agent runs in browsers, and there can be many thousands reporting to an APM Server with very variable network latency. [[reduce-storage]] === Reduce storage +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + The amount of storage for APM data depends on several factors: the number of services you are instrumenting, how much traffic the services see, agent and server settings, and the length of time you store your data. @@ -246,6 +258,9 @@ Then click **delete indices**. [[manage-indices-kibana]] === Manage Indices via Kibana +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + The Kibana UI for {kibana-ref}/managing-indices.html[managing indices] allows you to view indices, index settings, mappings, document counts, used storage per index, and much more. You can also perform management operations, like deleting indices directly via the Kibana UI. @@ -254,6 +269,9 @@ Finally, the UI supports applying bulk operations on several indices at once. [[update-existing-data]] === Update existing data +IMPORTANT: {deprecation-notice-data} +If you've already upgraded, please see <> instead. + You might want to update documents that are already indexed. For example, if you your service name was set incorrectly. diff --git a/docs/legacy/transaction-metrics.asciidoc b/docs/legacy/transaction-metrics.asciidoc index 41cb35c99c0..989377a390b 100644 --- a/docs/legacy/transaction-metrics.asciidoc +++ b/docs/legacy/transaction-metrics.asciidoc @@ -6,6 +6,8 @@ Transaction metrics ++++ +IMPORTANT: {deprecation-notice-config} + {beatname_uc} produces transaction histogram metrics that are used to power the APM app. Shifting this responsibility from APM app to APM Server removes the need to store unsampled transactions, reducing storage costs. diff --git a/docs/legacy/troubleshooting.asciidoc b/docs/legacy/troubleshooting.asciidoc index ac3428a078d..3226dd43047 100644 --- a/docs/legacy/troubleshooting.asciidoc +++ b/docs/legacy/troubleshooting.asciidoc @@ -1,6 +1,8 @@ [[troubleshooting]] = Troubleshoot +IMPORTANT: {deprecation-notice-data} + If you have issues installing or running APM Server, read the following tips: diff --git a/docs/notices.asciidoc b/docs/notices.asciidoc new file mode 100644 index 00000000000..2d57ba65b4a --- /dev/null +++ b/docs/notices.asciidoc @@ -0,0 +1,19 @@ +// For installation, get started, and setup docs +:deprecation-notice-installation: This method of installing APM Server will be deprecated and removed in a future release. Please consider getting started with the <> instead. + +// Generic "running" message +// Usually followed by a link to the corresponding APM integration docs +// Link to upgrade docs will be added in #6709 +:deprecation-notice-data: This documentation refers to the standalone (legacy) method of running APM Server. This method of running APM Server will be deprecated and removed in a future release. Please consider upgrading to the Elastic APM integration. + +// For monitoring docs +// Link to upgrade docs will be added in #6709 +:deprecation-notice-monitor: This documentation refers to monitoring the standalone (legacy) APM Server. This method of running APM Server will be deprecated and removed in a future release. Please consider upgrading to {fleet} and the APM integration. + +// For configuration docs +// Link to upgrade docs will be added in #6709 +:deprecation-notice-config: This documentation refers to configuring the standalone (legacy) APM Server. This method of running APM Server will be deprecated and removed in a future release. Please consider upgrading to {fleet} and the APM integration. + +// For API docs +// Link to upgrade docs will be added in #6709 +:deprecation-notice-api: This documentation refers to the API of the standalone (legacy) APM Server. This method of running APM Server will be deprecated and removed in a future release. Please consider upgrading to {fleet} and the APM integration.