diff --git a/docs/en/apm-server/redirects.asciidoc b/docs/en/apm-server/redirects.asciidoc index f733cc02c8..80df5b06e6 100644 --- a/docs/en/apm-server/redirects.asciidoc +++ b/docs/en/apm-server/redirects.asciidoc @@ -35,7 +35,7 @@ The error endpoint has been deprecated. Please see {observability-guide}/apm-api [role="exclude",id="error-schema-definition"] === Error schema definition -The error schema has moved. Please see {observability-guide}/apm-api-error.html[Error Schema]. +The error schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="error-api-examples"] === Error API examples @@ -45,42 +45,42 @@ The error API examples have moved. Please see {observability-guide}/apm-api-even [role="exclude",id="error-payload-schema"] === Error payload schema -The error schema has moved. Please see {observability-guide}/apm-api-error.html[Error Schema]. +The error schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="error-service-schema"] === Error service schema -The error schema has moved. Please see {observability-guide}/apm-api-error.html[Error Schema]. +The error schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="error-system-schema"] === Error system schema -The error schema has moved. Please see {observability-guide}/apm-api-error.html[Error Schema]. +The error schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="error-context-schema"] === Error context schema -The error schema has moved. Please see {observability-guide}/apm-api-error.html[Error Schema]. +The error schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="error-stacktraceframe-schema"] === Error stack trace frame schema -The error schema has moved. Please see {observability-guide}/apm-api-error.html[Error Schema]. +The error schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="payload-with-error"] === Payload with error -This is no longer helpful. Please see {observability-guide}/apm-api-error.html[Error Schema]. +This is no longer helpful. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="payload-with-minimal-exception"] === Payload with minimal exception -This is no longer helpful. Please see {observability-guide}/apm-api-error.html[Error Schema]. +This is no longer helpful. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. [role="exclude",id="payload-with-minimal-log"] === Payload with minimal log -This is no longer helpful. Please see {observability-guide}/apm-api-error.html[Error Schema]. +This is no longer helpful. Please see {observability-guide}/apm-api-events.html#apm-api-error[Error Schema]. // Transaction API @@ -92,7 +92,7 @@ The transaction endpoint has been deprecated. Please see {observability-guide}/a [role="exclude",id="transaction-schema-definition"] === Transaction schema definition -The transaction schema has moved. Please see {observability-guide}/apm-api-transaction.html#apm-api-transaction-schema[Transaction Schema]. +The transaction schema has moved. Please see {observability-guide}/apm-api-events.html#apm-api-transaction-schema[Transaction Schema]. [role="exclude",id="transaction-api-examples"] === Transaction API examples @@ -102,62 +102,62 @@ The transaction API examples have moved. Please see {observability-guide}/apm-ap [role="exclude",id="transaction-span-schema"] === Transaction span schema -This schema has changed. Please see {observability-guide}/apm-api-span.html[Spans]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-span[Spans]. [role="exclude",id="transaction-payload-schema"] === Transaction payload schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="transaction-service-schema"] === Transaction service schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="transaction-system-schema"] === Transaction system schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="transaction-context-schema"] === Transaction context schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="transaction-stacktraceframe-schema"] === Transaction stack trace frame schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="transaction-request-schema"] === Transaction request schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="transaction-user-schema"] === Transaction user schema -This schema has changed. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This schema has changed. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="payload-with-transactions"] === Payload with transactions -This is no longer helpful. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This is no longer helpful. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="payload-with-minimal-transaction"] === Payload with minimal transaction -This is no longer helpful. Please see {observability-guide}/apm-api-transaction.html[Transactions]. +This is no longer helpful. Please see {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="payload-with-minimal-span"] === Payload with minimal span -This is no longer helpful. Please see {observability-guide}/apm-api-span.html[Spans]. +This is no longer helpful. Please see {observability-guide}/apm-api-events.html#apm-api-span[Spans]. [role="exclude",id="example-intakev2-events"] === Example Request Body -Refer to {observability-guide}/apm-api-event-example.html[Example request body]. +Refer to {observability-guide}/apm-api-events.html#apm-api-event-example[Example request body]. // V1 intake API @@ -442,49 +442,49 @@ Refer to {observability-guide}/apm-getting-started-apm-server.html[Self manage A {move-notice} -Refer to {observability-guide}/_apm_server_binary.html[APM Server binary]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html[APM Server binary]. [role="exclude",id="installing"] === Step 1: Install {move-notice} -Refer to {observability-guide}/apm-installing.html[Step 1: Install]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html#apm-installing[Step 1: Install]. [role="exclude",id="apm-server-configuration"] === Step 2: Set up and configure {move-notice} -Refer to {observability-guide}/apm-server-configuration.html[Step 2: Set up and configure]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html#apm-server-configuration[Step 2: Set up and configure]. [role="exclude",id="apm-server-starting"] === Step 3: Start {move-notice} -Refer to {observability-guide}/apm-server-starting.html[Step 3: Start]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html#apm-server-starting[Step 3: Start]. [role="exclude",id="next-steps"] === Step 4: Next steps {move-notice} -Refer to {observability-guide}/apm-next-steps.html[Step 4: Next steps]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html#apm-next-steps[Step 4: Next steps]. [role="exclude",id="setup-repositories"] === Repositories for APT and YUM {move-notice} -Refer to {observability-guide}/apm-setup-repositories.html[Repositories for APT and YUM]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html#apm-setup-repositories[Repositories for APT and YUM]. [role="exclude",id="running-on-docker"] === Run APM Server on Docker {move-notice} -Refer to {observability-guide}/apm-running-on-docker.html[Run APM Server on Docker]. +Refer to {observability-guide}/get-started-with-apm-server-binary.html#apm-running-on-docker[Run APM Server on Docker]. [role="exclude",id="_fleet_managed_apm_server"] === Fleet-managed APM Server @@ -498,28 +498,28 @@ Refer to {observability-guide}/get-started-with-fleet-apm-server.html[Fleet-mana {move-notice} -Refer to {observability-guide}/_step_1_set_up_fleet.html[Step 1: Set up Fleet]. +Refer to {observability-guide}/get-started-with-fleet-apm-server.html#_step_1_set_up_fleet[Step 1: Set up Fleet]. [role="exclude",id="_step_2_add_and_configure_the_apm_integration"] === Step 2: Add and configure the APM integration {move-notice} -Refer to {observability-guide}/add-apm-integration.html[Step 2: Add and configure the APM integration]. +Refer to {observability-guide}/get-started-with-fleet-apm-server.html#add-apm-integration[Step 2: Add and configure the APM integration]. [role="exclude",id="_step_3_install_apm_agents"] === Step 3: Install APM agents {move-notice} -Refer to {observability-guide}/_step_3_install_apm_agents.html[Step 3: Install APM agents]. +Refer to {observability-guide}/get-started-with-fleet-apm-server.html#_step_3_install_apm_agents[Step 3: Install APM agents]. [role="exclude",id="_step_4_view_your_data"] === Step 4: View your data {move-notice} -Refer to {observability-guide}/_step_4_view_your_data.html[Step 4: View your data]. +Refer to {observability-guide}/get-started-with-fleet-apm-server.html#_step_4_view_your_data[Step 4: View your data]. [role="exclude",id="data-model"] === Data Model @@ -621,7 +621,7 @@ Refer to {observability-guide}/apm-data-security-delete.html[Delete sensitive da {move-notice} -Refer to {observability-guide}/apm-distributed-tracing.html[Distributed tracing]. +Refer to {observability-guide}/apm-data-model-traces.html#apm-distributed-tracing[Distributed tracing]. [role="exclude",id="apm-rum"] === Real User Monitoring (RUM) @@ -642,14 +642,14 @@ Refer to {observability-guide}/apm-sampling.html[Transaction sampling]. {move-notice} -Refer to {observability-guide}/apm-configure-head-based-sampling.html[Configure head-based sampling]. +Refer to {observability-guide}/apm-sampling.html#apm-configure-head-based-sampling[Configure head-based sampling]. [role="exclude",id="configure-tail-based-sampling"] === Configure tail-based sampling {move-notice} -Refer to {observability-guide}/apm-configure-tail-based-sampling.html[Configure tail-based sampling]. +Refer to {observability-guide}/apm-sampling.html#apm-configure-tail-based-sampling[Configure tail-based sampling]. [role="exclude",id="log-correlation"] === Logging integration @@ -1191,7 +1191,7 @@ Refer to {observability-guide}/apm-monitoring-local-collection.html[Use local co {move-notice} -Refer to {observability-guide}/apm-select-metrics.html[The select metrics]. +Refer to {observability-guide}/apm-monitoring-local-collection.html#apm-select-metrics[The select metrics]. [role="exclude",id="monitoring-metricbeat-collection"] === Use Metricbeat collection @@ -1226,45 +1226,45 @@ Refer to {observability-guide}/apm-api-events.html[Elastic APM events intake API {move-notice} -Refer to {observability-guide}/apm-api-metadata.html[Metadata]. +Refer to {observability-guide}/apm-api-events.html#apm-api-metadata[Metadata]. [discrete] [[api-metadata-schema]] ==== Metadata scheme -Refer to {observability-guide}/apm-api-metadata.html#apm-api-metadata-schema[Metadata scheme]. +Refer to {observability-guide}/apm-api-events.html#apm-api-metadata-schema[Metadata scheme]. [role="exclude",id="api-transaction"] === Transactions {move-notice} -Refer to {observability-guide}/apm-api-transaction.html[Transactions]. +Refer to {observability-guide}/apm-api-events.html#apm-api-transaction[Transactions]. [role="exclude",id="api-span"] === Spans {move-notice} -Refer to {observability-guide}/apm-api-span.html[Spans]. +Refer to {observability-guide}/apm-api-events.html#apm-api-span[Spans]. [role="exclude",id="api-error"] === Errors {move-notice} -Refer to {observability-guide}/apm-api-error.html[Errors]. +Refer to {observability-guide}/apm-api-events.html#apm-api-error[Errors]. [role="exclude",id="api-metricset"] === Metrics -Refer to {observability-guide}/apm-api-metricset.html[Metrics] +Refer to {observability-guide}/apm-api-events.html#apm-api-metricset[Metrics] [role="exclude",id="api-event-example"] === Example request body {move-notice} -Refer to {observability-guide}/apm-api-event-example.html[Example request body]. +Refer to {observability-guide}/apm-api-events.html#apm-api-event-example[Example request body]. [role="exclude",id="api-config"] === Elastic APM agent configuration API diff --git a/docs/en/observability/apm-ui/apm-alerts.asciidoc b/docs/en/observability/apm-alerts.asciidoc similarity index 95% rename from docs/en/observability/apm-ui/apm-alerts.asciidoc rename to docs/en/observability/apm-alerts.asciidoc index 99a6b6f5ef..063322a2cd 100644 --- a/docs/en/observability/apm-ui/apm-alerts.asciidoc +++ b/docs/en/observability/apm-alerts.asciidoc @@ -1,9 +1,5 @@ [[apm-alerts]] -=== Alerts and rules - -++++ -Create an alert -++++ += APM alerts and rules The APM UI allows you to define **rules** to detect complex conditions within your APM data and trigger built-in **actions** when those conditions are met. @@ -28,7 +24,7 @@ see Kibana's {kibana-ref}/create-and-manage-rules.html[Create and manage rules]. [float] [[apm-create-transaction-alert]] -=== Example: create a latency anomaly rule +== Example: create a latency anomaly rule Latency anomaly rules trigger when the latency of a service is abnormal. Because some parts of an application are more important than others, and have a different @@ -71,7 +67,7 @@ Click **Save**. Your rule has been created and is now active! [float] [[apm-create-error-alert]] -=== Example: create an error count threshold alert +== Example: create an error count threshold alert The error count threshold alert triggers when the number of errors in a service exceeds a defined threshold. Because some errors are more important than others, this guide will focus a specific error group ID. @@ -131,13 +127,13 @@ Click **Save**. The alert has been created and is now active! [float] [[apm-alert-view-active]] -=== View active alerts +== View active alerts Active alerts are displayed and grouped in multiple ways in the APM UI. [float] [[apm-alert-view-group]] -==== View alerts by service group +=== View alerts by service group If you're using the <> feature, you can view alerts by service group. From the service group overview page, click the red alert indicator to open the **Alerts** tab with a predefined filter that matches the filter used when creating the service group. @@ -147,7 +143,7 @@ image::./images/apm-service-group.png[Example view of service group in the APM U [float] [[apm-alert-view-service]] -==== View alerts by service +=== View alerts by service Alerts can be viewed within the context of any service. After selecting a service, go to the **Alerts** tab to view any alerts that are active for the selected service. @@ -157,7 +153,7 @@ image::./images/active-alert-service.png[View active alerts by service] [float] [[apm-alert-manage]] -=== Manage alerts and rules +== Manage alerts and rules From the APM UI, select **Alerts and rules** > **Manage rules** to be taken to the {kib} *{rules-ui}* page. @@ -165,7 +161,7 @@ From this page, you can disable, mute, and delete APM alerts. [float] [[apm-alert-more-info]] -=== More information +== More information See {kibana-ref}/alerting-getting-started.html[Alerting] for more information. diff --git a/docs/en/observability/apm-ui/apm-app-users.asciidoc b/docs/en/observability/apm-ui/apm-app-users.asciidoc deleted file mode 100644 index d54c913fac..0000000000 --- a/docs/en/observability/apm-ui/apm-app-users.asciidoc +++ /dev/null @@ -1,351 +0,0 @@ -[[apm-app-users]] -== APM UI users and privileges - -:beat_default_index_prefix: apm -:annotation_index: observability-annotations - -++++ -Users and privileges -++++ - -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. - -{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a -subset of the privileges needed by APM users. -When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. -If no built-in role is available, you can assign users the privileges needed to accomplish a specific task. -In general, there are three types of privileges you'll work with: - -* **Elasticsearch cluster privileges**: Manage the actions a user can perform against your cluster. -* **Elasticsearch index privileges**: Control access to the data in specific indices your cluster. -* **Kibana feature privileges**: Grant users write or read access to features and apps within Kibana. - -Select your use-case to get started: - -* <> -* <> -* <> -* <> -* <> - -//// -*********************************** *********************************** -//// - -[[apm-app-reader]] -=== APM reader user - -++++ -Create an APM reader user -++++ - -APM reader users typically need to view the APM UI and dashboards and visualizations that use APM data. -These users might also need to create and edit dashboards, visualizations, and machine learning jobs. - -[float] -[[apm-app-reader-full]] -==== APM reader - -To create an APM reader user: - -. Create a new role, named something like `read-apm`, and assign the following privileges: -+ --- -:apm-read-view: -:apm-monitor: -include::./tab-widgets/apm-app-reader/widget.asciidoc[] -:!apm-read-view: -:!apm-monitor: --- - -. Assign the `read-apm` role created in the previous step, and the following built-in roles to -any APM reader users: -+ -[options="header"] -|==== -|Role | Purpose - -|`kibana_admin` -|Grants access to all features in Kibana. - -|`machine_learning_admin` -|Grants the privileges required to create, update, and view machine learning jobs -|==== - -[float] -[[apm-app-reader-partial]] -==== Partial APM reader - -In some instances, you may wish to restrict certain Kibana apps that a user has access to. - -. Create a new role, named something like `read-apm-partial`, and assign the following privileges: -+ --- -include::./tab-widgets/apm-app-reader/widget.asciidoc[] --- - -. Assign feature privileges to any Kibana feature that the user needs access to. -Here are two examples: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -| Kibana -| `Read` or `All` on the APM and User Experience feature -| Allow the use of the the APM and User Experience apps - -| Kibana -| `Read` or `All` on Dashboards and Discover -| Allow the user to view, edit, and create dashboards, as well as browse data. -|==== - -. Finally, assign the following role if a user needs to enable and edit machine learning features: -+ -[options="header"] -|==== -|Role | Purpose - -|`machine_learning_admin` -|Grants the privileges required to create, update, and view machine learning jobs -|==== - -//// -*********************************** *********************************** -//// - -[[apm-app-annotation-user-create]] -=== APM UI annotation user - -++++ -Create an annotation user -++++ - -NOTE: By default, the `viewer` and `editor` built-in roles provide read access to Observability annotations. -You only need to create an annotation user to write to the annotations index -({kibana-ref}/apm-settings-kb.html[`xpack.observability.annotations.index`]). - -[float] -[[apm-app-annotation-user]] -==== Annotation user - -View deployment annotations in the APM UI. - -. Create a new role, named something like `annotation_user`, -and assign the following privileges: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -|Index -|`read` on +\{ANNOTATION_INDEX\}+^1^ -|Read-only access to the observability annotation index - -|Index -|`view_index_metadata` on +\{ANNOTATION_INDEX\}+^1^ -|Read-only access to observability annotation index metadata -|==== -+ -^1^ +\{ANNOTATION_INDEX\}+ should be the index name you've defined in -{kibana-ref}/apm-settings-kb.html[`xpack.observability.annotations.index`]. - -. Assign the `annotation_user` created previously, and the roles and privileges necessary to create -a <> or <> APM reader to any users that need to view annotations in the APM UI - -[float] -[[apm-app-annotation-api]] -==== Annotation API - -See <>. - -//// -*********************************** *********************************** -//// - -[[apm-app-central-config-user]] -=== APM UI central config user - -++++ -Create a central config user -++++ - -[float] -[[apm-app-central-config-manager]] -==== Central configuration manager - -Central configuration users need to be able to view, create, update, and delete APM agent configurations. - -. Create a new role, named something like `central-config-manager`, and assign the following privileges: -+ --- -include::./tab-widgets/central-config-users/widget.asciidoc[] --- -+ -TIP: Using the deprecated APM Server binaries? -Add the privileges under the **Classic APM indices** tab above. - -. Assign the `central-config-manager` role created in the previous step, -and the following Kibana feature privileges to anyone who needs to manage central configurations: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -| Kibana -|`All` on the APM and User Experience feature -|Allow full use of the APM and User Experience apps -|==== - -[float] -[[apm-app-central-config-reader]] -==== Central configuration reader - -In some instances, you may wish to create a user that can only read central configurations, -but not create, update, or delete them. - -. Create a new role, named something like `central-config-reader`, and assign the following privileges: -+ --- -include::./tab-widgets/central-config-users/widget.asciidoc[] --- -+ -TIP: Using the deprecated APM Server binaries? -Add the privileges under the **Classic APM indices** tab above. - -. Assign the `central-config-reader` role created in the previous step, -and the following Kibana feature privileges to anyone who needs to read central configurations: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -| Kibana -|`read` on the APM and User Experience feature -|Allow read access to the APM and User Experience apps -|==== - -[float] -[[apm-app-central-config-api]] -==== Central configuration API - -See <>. - -//// -*********************************** *********************************** -//// - -[[apm-app-storage-explorer-user-create]] -=== APM UI storage explorer user - -++++ -Create a storage explorer user -++++ - -[float] -[[apm-app-storage-explorer-user]] -==== Storage Explorer user - -View the **Storage Explorer** in the APM UI. - -. Create a new role, named something like `storage-explorer_user`, -and assign the following privileges: -+ --- -include::./tab-widgets/storage-explorer-user/widget.asciidoc[] --- - -. Assign the `storage-explorer_user` created previously, and the roles and privileges necessary to create -a <> or <> APM reader to any users that need to view **Storage Explorer** in the APM UI. - -//// -*********************************** *********************************** -//// - -[[apm-app-api-user]] -=== APM UI API user - -++++ -Create an API user -++++ - -[float] -[[apm-app-api-config-manager]] -==== Central configuration API - -Users can list, search, create, update, and delete central configurations via the APM UI API. - -. Assign the following Kibana feature privileges: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -| Kibana -|`all` on the APM and User Experience feature -|Allow all access to the APM and User Experience apps -|==== - -[float] -[[apm-app-api-config-reader]] -==== Central configuration API reader - -Sometimes a user only needs to list and search central configurations via the APM UI API. - -. Assign the following Kibana feature privileges: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -| Kibana -|`read` on the APM and User Experience feature -|Allow read access to the APM and User Experience apps -|==== - -[float] -[[apm-app-api-annotation-manager]] -==== Annotation API - -Users can use the annotation API to create annotations on their APM data. - -. Create a new role, named something like `annotation_role`, -and assign the following privileges: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -|Index -|`manage` on +{annotation_index}+ index -|Check if the +{annotation_index}+ index exists - -|Index -|`read` on +{annotation_index}+ index -|Read the +{annotation_index}+ index - -|Index -|`create_index` on +{annotation_index}+ index -|Create the +{annotation_index}+ index - -|Index -|`create_doc` on +{annotation_index}+ index -|Create new annotations in the +{annotation_index}+ index -|==== - -. Assign the `annotation_role` created previously, -and the following Kibana feature privileges to any annotation API users: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -| Kibana -|`all` on the APM and User Experience feature -|Allow all access to the APM and User Experience apps -|==== - -//LEARN MORE -//Learn more about <>. diff --git a/docs/en/observability/apm-ui/index.asciidoc b/docs/en/observability/apm-ui/index.asciidoc deleted file mode 100644 index 5c3303acd7..0000000000 --- a/docs/en/observability/apm-ui/index.asciidoc +++ /dev/null @@ -1,76 +0,0 @@ -[[apm-ui]] -= Navigate the APM UI - -TIP: For task-oriented guides, see the <>. - -The APM UI in {kib} allows you to monitor your software services and applications in real-time; -visualize detailed performance information on your services, -identify and analyze errors, -and monitor host-level and APM agent-specific metrics like JVM and Go runtime metrics. - -Having access to application-level insights with just a few clicks can drastically decrease the time you spend -debugging errors, slow response times, and crashes. - -For example, you can see information about response times, requests per minute, and status codes per endpoint. -You can even dive into a specific request sample and get a complete waterfall view of what your application is spending its time on. -You might see that your bottlenecks are in database queries, cache calls, or external requests. -For each incoming request and each application error, -you can also see contextual information such as the request header, user information, -system values, or custom data that you manually attached to the request. - -For a quick, high-level overview of the health and performance of your application, -start with: - -* <> -* <> -* <> -* <> - -Notice something awry? Select a service or trace and dive deeper with: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -Configure and troubleshoot the APM UI: - -* <> -* <> -* <> - -include::services.asciidoc[leveloffset=-1] - -include::new-experience-services.asciidoc[leveloffset=+2] - -include::traces.asciidoc[leveloffset=-1] - -include::dependencies.asciidoc[leveloffset=-1] - -include::service-maps.asciidoc[leveloffset=-1] - -include::service-overview.asciidoc[leveloffset=-1] - -include::mobile-service.asciidoc[leveloffset=-1] - -include::transactions.asciidoc[leveloffset=-1] - -include::spans.asciidoc[leveloffset=-1] - -include::errors.asciidoc[leveloffset=-1] - -include::metrics.asciidoc[leveloffset=-1] - -include::infrastructure.asciidoc[leveloffset=-1] - -include::logs.asciidoc[leveloffset=-1] - -include::apm-app-users.asciidoc[] - -include::settings.asciidoc[] - -include::troubleshooting.asciidoc[] diff --git a/docs/en/observability/apm.asciidoc b/docs/en/observability/apm.asciidoc index 4c9e3693c0..ba2f844727 100644 --- a/docs/en/observability/apm.asciidoc +++ b/docs/en/observability/apm.asciidoc @@ -46,36 +46,27 @@ like JVM metrics in the Java Agent, and Go runtime metrics in the Go Agent. Use <> to quickly spin up an APM deployment. Want to host everything yourself instead? See <>. -include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm-server.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/data-model.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/features.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm-ui/index.asciidoc[leveloffset=+1] - -include::{observability-docs-root}/docs/en/observability/apm/how-to.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/open-telemetry.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/manage-storage.asciidoc[] - +//// +Subsections +//// + +// Intro content +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/data-model/index.asciidoc[leveloffset=+1] +// Get data +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/index.asciidoc[leveloffset=+1] +// Do things with that data +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/act-on-data/index.asciidoc[leveloffset=+1] +// Fine-tune your implementation +include::{observability-docs-root}/docs/en/observability/apm/security/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/index.asciidoc[leveloffset=+1] include::{observability-docs-root}/docs/en/observability/apm/configure/index.asciidoc[leveloffset=+1] - -include::{observability-docs-root}/docs/en/observability/apm/setting-up-and-running.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/secure-comms.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/monitor-apm-server.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/api.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm-ui/api.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/troubleshoot-apm.asciidoc[] - +include::{observability-docs-root}/docs/en/observability/apm/monitor-apm-server/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/api/index.asciidoc[leveloffset=+1] +// Fix something +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/index.asciidoc[leveloffset=+1] +// Update an existing implementation include::{observability-docs-root}/docs/en/observability/apm/upgrading.asciidoc[] - include::{observability-docs-root}/docs/en/observability/apm/release-notes.asciidoc[leveloffset=+1] - -include::{observability-docs-root}/docs/en/observability/apm/known-issues.asciidoc[leveloffset=+1] \ No newline at end of file +include::{observability-docs-root}/docs/en/observability/apm/known-issues.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm-ui/custom-links.asciidoc b/docs/en/observability/apm/act-on-data/custom-links.asciidoc similarity index 97% rename from docs/en/observability/apm-ui/custom-links.asciidoc rename to docs/en/observability/apm/act-on-data/custom-links.asciidoc index 0e235c125e..f4bc31408b 100644 --- a/docs/en/observability/apm-ui/custom-links.asciidoc +++ b/docs/en/observability/apm/act-on-data/custom-links.asciidoc @@ -1,5 +1,5 @@ [[apm-custom-links]] -=== Custom links += Custom links in the APM UI ++++ Create custom links @@ -14,7 +14,7 @@ Ready to dive in? Jump straight to the <>. [float] [[custom-links-create]] -=== Create a link +== Create a link Each custom link consists of a label, URL, and optional filter. The easiest way to create a custom link is from within the actions dropdown in the transaction detail page. @@ -26,7 +26,7 @@ and selecting **Create custom link**. [float] [[custom-links-label]] -==== Label +=== Label The name of your custom link. The actions context menu displays this text, so keep it as short as possible. @@ -35,7 +35,7 @@ TIP: Custom links are displayed alphabetically in the actions menu. [float] [[custom-links-url]] -==== URL +=== URL The URL your link points to. URLs support dynamic field name variables, encapsulated in double curly brackets: `{{field.name}}`. @@ -50,7 +50,7 @@ image::./images/example-metadata.png[Example metadata] [float] [[custom-links-filters]] -==== Filters +=== Filters Filter each link to only appear for specific services or transactions. You can filter on the following fields: @@ -64,7 +64,7 @@ Multiple values are allowed when comma-separated. [float] [[custom-links-examples]] -=== Custom link examples +== Custom link examples // Relevant documentation links :jira-query-params: https://confluence.atlassian.com/jirakb/how-to-create-issues-using-direct-html-links-in-jira-server-159474.html @@ -75,7 +75,7 @@ Take a look at the examples below and customize them to your liking! [float] [[custom-links-examples-email]] -==== Email +=== Email Email the owner of a service. @@ -98,7 +98,7 @@ It will only appear on services with the name `python-backend`. [float] [[custom-links-examples-gh]] -==== GitHub issue +=== GitHub issue Open a GitHub issue with pre-populated metadata from the selected trace sample. @@ -127,7 +127,7 @@ See the {github-query-params}[GitHub automation documentation] for a full list o [float] [[custom-links-examples-jira]] -==== Jira task +=== Jira task Create a Jira task with pre-populated metadata from the selected trace sample. @@ -155,7 +155,7 @@ for a full list of supported query parameters. [float] [[custom-links-examples-kib]] -==== Kibana dashboards +=== Kibana dashboards Link to a custom dashboard in Kibana. @@ -176,7 +176,7 @@ There are no filters set. [float] [[custom-links-examples-slack]] -==== Slack channel +=== Slack channel Open a specified slack channel. @@ -199,7 +199,7 @@ It only appears when `transaction.name` is `GET user/login`. [float] [[custom-links-examples-web]] -==== Website +=== Website Open an internal or external website. diff --git a/docs/en/observability/apm/act-on-data/index.asciidoc b/docs/en/observability/apm/act-on-data/index.asciidoc new file mode 100644 index 0000000000..a3036dcf71 --- /dev/null +++ b/docs/en/observability/apm/act-on-data/index.asciidoc @@ -0,0 +1,24 @@ +[[apm-act-on-data]] += Act on application data + +++++ +Act on data +++++ + +In addition to exploring visualizations in the APM UI in {kib}, you can make your application data +more actionable with: + +* *Alerts and rules*: The APM UI allows you to define rules to detect complex + conditions within your APM data and trigger built-in actions when those conditions are met. + Read more about alerts and rules in the <>. +* *Custom links*: Build URLs that contain relevant metadata from a specific trace. + For example, you can create a link that will take you to a page where you can open a new GitHub issue + with context already auto-populated in the issue body. + These links will be shown in the _Actions_ context menu in selected areas of the APM UI (for example, by transaction details). + Read more in <>. + +:leveloffset: +1 + +include::{observability-docs-root}/docs/en/observability/apm/act-on-data/custom-links.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm-ui/api.asciidoc b/docs/en/observability/apm/api/api-ui.asciidoc similarity index 94% rename from docs/en/observability/apm-ui/api.asciidoc rename to docs/en/observability/apm/api/api-ui.asciidoc index 33a64d5d75..8bf85cf5ff 100644 --- a/docs/en/observability/apm-ui/api.asciidoc +++ b/docs/en/observability/apm/api/api-ui.asciidoc @@ -1,5 +1,5 @@ [[apm-app-api]] -== APM UI API += APM UI API Some APM UI features are provided via a REST API: @@ -10,7 +10,7 @@ Some APM UI features are provided via a REST API: [float] [[apm-api-example]] -=== Using the APIs +== Using the APIs // The following content is reused throughout the API docs // tag::using-the-APIs[] @@ -68,7 +68,7 @@ curl -X POST \ [float] [[kibana-api]] -=== Kibana API +== Kibana API In addition to the APM specific API endpoints, Kibana provides its own <> which you can use to automate certain aspects of configuring and deploying Kibana. @@ -79,7 +79,7 @@ which you can use to automate certain aspects of configuring and deploying Kiban //// [[apm-agent-config-api]] -=== Agent Configuration API +== Agent Configuration API The APM agent configuration API allows you to fine-tune your APM agent configuration, without needing to redeploy your application. @@ -93,44 +93,44 @@ The following APM agent configuration APIs are available: [float] [[use-agent-config-api]] -==== How to use APM APIs +=== How to use APM APIs .Expand for required headers, privileges, and usage details [%collapsible%closed] -====== -include::api.asciidoc[tag=using-the-APIs] -====== +===== +include::api-ui.asciidoc[tag=using-the-APIs] +===== //// ******************************************************* //// [[apm-update-config]] -==== Create or update configuration +=== Create or update configuration [float] [[apm-update-config-req]] -===== Request +==== Request `PUT /api/apm/settings/agent-configuration` [float] [role="child_attributes"] [[apm-update-config-req-body]] -===== Request body +==== Request body `service`:: (required, object) Service identifying the configuration to create or update. + .Properties of `service` [%collapsible%open] -====== +===== `name` ::: (required, string) Name of service `environment` ::: (optional, string) Environment of service -====== +===== `settings`:: (required) Key/value object with option name and option value. @@ -141,7 +141,7 @@ include::api.asciidoc[tag=using-the-APIs] [float] [[apm-update-config-example]] -===== Example +==== Example [source,curl] -------------------------------------------------- @@ -166,35 +166,35 @@ PUT /api/apm/settings/agent-configuration [[apm-delete-config]] -==== Delete configuration +=== Delete configuration [float] [[apm-delete-config-req]] -===== Request +==== Request `DELETE /api/apm/settings/agent-configuration` [float] [role="child_attributes"] [[apm-delete-config-req-body]] -===== Request body +==== Request body `service`:: (required, object) Service identifying the configuration to delete + .Properties of `service` [%collapsible%open] -====== +===== `name` ::: (required, string) Name of service `environment` ::: (optional, string) Environment of service -====== +===== [float] [[apm-delete-config-example]] -===== Example +==== Example [source,curl] -------------------------------------------------- @@ -212,17 +212,17 @@ DELETE /api/apm/settings/agent-configuration //// [[apm-list-config]] -==== List configuration +=== List configuration [float] [[apm-list-config-req]] -===== Request +==== Request `GET /api/apm/settings/agent-configuration` [float] [[apm-list-config-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- @@ -273,7 +273,7 @@ DELETE /api/apm/settings/agent-configuration [float] [[apm-list-config-example]] -===== Example +==== Example [source,curl] -------------------------------------------------- @@ -285,38 +285,38 @@ GET /api/apm/settings/agent-configuration //// [[apm-search-config]] -==== Search configuration +=== Search configuration [float] [[apm-search-config-req]] -===== Request +==== Request `POST /api/apm/settings/agent-configuration/search` [float] [role="child_attributes"] [[apm-search-config-req-body]] -===== Request body +==== Request body `service`:: (required, object) Service identifying the configuration. + .Properties of `service` [%collapsible%open] -====== +===== `name` ::: (required, string) Name of service `environment` ::: (optional, string) Environment of service -====== +===== `etag`:: (required) etag is sent by the APM agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its `applied_by_agent` property will be set to `true`. Every time a configuration is edited `applied_by_agent` is reset to `false`. [float] [[apm-search-config-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- @@ -341,7 +341,7 @@ GET /api/apm/settings/agent-configuration [float] [[apm-search-config-example]] -===== Example +==== Example [source,curl] -------------------------------------------------- @@ -361,7 +361,7 @@ POST /api/apm/settings/agent-configuration/search //// [[apm-annotation-api]] -=== Annotation API +== Annotation API The Annotation API allows you to annotate visualizations in the APM UI with significant events, like deployments, allowing you to easily see how these events are impacting the performance of your existing applications. @@ -379,44 +379,44 @@ The following APIs are available: [float] [[use-annotation-api]] -==== How to use APM APIs +=== How to use APM APIs .Expand for required headers, privileges, and usage details [%collapsible%closed] -====== -include::api.asciidoc[tag=using-the-APIs] -====== +===== +include::api-ui.asciidoc[tag=using-the-APIs] +===== //// ******************************************************* //// [[apm-annotation-create]] -==== Create or update annotation +=== Create or update annotation [float] [[apm-annotation-config-req]] -===== Request +==== Request `POST /api/apm/services/:serviceName/annotation` [float] [role="child_attributes"] [[apm-annotation-config-req-body]] -===== Request body +==== Request body `service`:: (required, object) Service identifying the configuration to create or update. + .Properties of `service` [%collapsible%open] -====== +===== `version` ::: (required, string) Version of service. `environment` ::: (optional, string) Environment of service. -====== +===== `@timestamp`:: (required, string) The date and time of the annotation. Must be in https://www.w3.org/TR/NOTE-datetime[ISO 8601] format. @@ -431,7 +431,7 @@ While you can add additional tags, you cannot remove the `apm` tag. [float] [[apm-annotation-config-example]] -===== Example +==== Example The following example creates an annotation for a service named `opbeans-java`. @@ -453,7 +453,7 @@ curl -X POST \ [float] [[apm-annotation-config-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- @@ -492,7 +492,7 @@ curl -X POST \ //// [[apm-rum-sourcemap-api]] -=== RUM source map API +== RUM source map API IMPORTANT: This endpoint is only compatible with the {apm-guide-ref}/index.html[APM integration for Elastic Agent]. @@ -514,7 +514,7 @@ The following APIs are available: [float] [[limit-sourcemap-api]] -==== Max payload size +=== Max payload size {kib}'s maximum payload size is 1mb. If you attempt to upload a source map that exceeds the max payload size, you will get a `413` error. @@ -524,40 +524,40 @@ with the `server.maxPayload` variable. [float] [[use-sourcemap-api]] -==== How to use APM APIs +=== How to use APM APIs .Expand for required headers, privileges, and usage details [%collapsible%closed] -====== -include::api.asciidoc[tag=using-the-APIs] -====== +===== +include::api-ui.asciidoc[tag=using-the-APIs] +===== //// ******************************************************* //// [[rum-sourcemap-post]] -==== Create or update source map +=== Create or update source map Create or update a source map for a specific service and version. [float] [[rum-sourcemap-post-privs]] -===== Privileges +==== Privileges The user accessing this endpoint requires `All` Kibana privileges for the APM and User Experience feature. For more information, see {kibana-ref}/kibana-privileges.html[Kibana privileges]. [float] [[apm-sourcemap-post-req]] -===== Request +==== Request `POST /api/apm/sourcemaps` [float] [role="child_attributes"] [[apm-sourcemap-post-req-body]] -===== Request body +==== Request body `service_name`:: (required, string) The name of the service that the service map should apply to. @@ -574,7 +574,7 @@ https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k[ [float] [[apm-sourcemap-post-example]] -===== Examples +==== Examples The following example uploads a source map for a service named `foo` and a service version of `1.0.0`: @@ -593,7 +593,7 @@ curl -X POST "http://localhost:5601/api/apm/sourcemaps" \ [float] [[apm-sourcemap-post-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- @@ -619,26 +619,26 @@ curl -X POST "http://localhost:5601/api/apm/sourcemaps" \ //// [[rum-sourcemap-get]] -==== Get source maps +=== Get source maps Returns an array of Fleet artifacts, including source map uploads. [float] [[rum-sourcemap-get-privs]] -===== Privileges +==== Privileges The user accessing this endpoint requires `Read` or `All` Kibana privileges for the APM and User Experience feature. For more information, see {kibana-ref}/kibana-privileges.html[Kibana privileges]. [float] [[apm-sourcemap-get-req]] -===== Request +==== Request `GET /api/apm/sourcemaps` [float] [[apm-sourcemap-get-example]] -===== Example +==== Example The following example requests all uploaded source maps: @@ -652,7 +652,7 @@ curl -X GET "http://localhost:5601/api/apm/sourcemaps" \ [float] [[apm-sourcemap-get-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- @@ -702,26 +702,26 @@ curl -X GET "http://localhost:5601/api/apm/sourcemaps" \ //// [[rum-sourcemap-delete]] -==== Delete source map +=== Delete source map Delete a previously uploaded source map. [float] [[rum-sourcemap-delete-privs]] -===== Privileges +==== Privileges The user accessing this endpoint requires `All` Kibana privileges for the APM and User Experience feature. For more information, see {kibana-ref}/kibana-privileges.html[Kibana privileges]. [float] [[apm-sourcemap-delete-req]] -===== Request +==== Request `DELETE /api/apm/sourcemaps/:id` [float] [[apm-sourcemap-delete-example]] -===== Example +==== Example The following example deletes a source map with an id of `apm:foo-1.0.0-644fd5a9`: @@ -735,7 +735,7 @@ curl -X DELETE "http://localhost:5601/api/apm/sourcemaps/apm:foo-1.0.0-644fd5a9" [float] [[apm-sourcemap-delete-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- @@ -748,7 +748,7 @@ curl -X DELETE "http://localhost:5601/api/apm/sourcemaps/apm:foo-1.0.0-644fd5a9" //// [[apm-agent-key-api]] -=== APM agent Key API +== APM agent Key API The APM agent Key API allows you to configure APM agent keys to authorize requests from APM agents to the APM Server. @@ -758,34 +758,34 @@ The following APM agent key APIs are available: [float] [[use-agent-key-api]] -==== How to use APM APIs +=== How to use APM APIs .Expand for required headers, privileges, and usage details [%collapsible%closed] -====== -include::api.asciidoc[tag=using-the-APIs] -====== +===== +include::api-ui.asciidoc[tag=using-the-APIs] +===== //// ******************************************************* //// [[apm-create-agent-key]] -==== Create agent key +=== Create agent key Create an APM agent API key. Specify API key privileges in the request body at creation time. [float] [[apm-create-agent-key-privileges]] -===== Privileges +==== Privileges The user creating an APM agent API key must have at least the `manage_own_api_key` cluster privilege and the APM application-level privileges that it wishes to grant. [float] -====== Example role +===== Example role The example below uses the Kibana {kibana-ref}/role-management-api.html[role management API] to create a role named `apm_agent_key_user`. Create and assign this role to a user that wishes to create APM agent API keys. @@ -813,7 +813,7 @@ POST /_security/role/apm_agent_key_user [float] [[apm-create-agent-key-req]] -===== Request +==== Request `POST /api/apm/agent_keys` @@ -821,7 +821,7 @@ POST /_security/role/apm_agent_key_user [float] [role="child_attributes"] [[apm-create-agent-key-req-body]] -===== Request body +==== Request body `name`:: (required, string) Name of the APM agent key. @@ -835,7 +835,7 @@ POST /_security/role/apm_agent_key_user [float] [[apm-agent-key-create-example]] -===== Example +==== Example [source,curl] -------------------------------------------------- @@ -849,7 +849,7 @@ POST /api/apm/agent_keys [float] [[apm-agent-key-create-body]] -===== Response body +==== Response body [source,js] -------------------------------------------------- diff --git a/docs/en/observability/apm/api-config.asciidoc b/docs/en/observability/apm/api/apm-server/api-config.asciidoc similarity index 94% rename from docs/en/observability/apm/api-config.asciidoc rename to docs/en/observability/apm/api/apm-server/api-config.asciidoc index f98d464432..9077f13c7a 100644 --- a/docs/en/observability/apm/api-config.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-config.asciidoc @@ -1,12 +1,12 @@ [[apm-api-config]] -=== Elastic APM agent configuration API += Elastic APM agent configuration API APM Server exposes API endpoints that allow Elastic APM agents to query the APM Server for configuration changes. More information on this feature is available in <>. [float] [[apm-api-config-endpoint]] -=== Agent configuration endpoints +== Agent configuration endpoints [options="header"] |==== @@ -20,7 +20,7 @@ If an <> or <> is configured, requests to this en [float] [[apm-api-config-api-get]] -==== HTTP GET +=== HTTP GET `service.name` is a required query string parameter. @@ -31,7 +31,7 @@ http(s)://{hostname}:{port}/config/v1/agents?service.name=SERVICE_NAME [float] [[apm-api-config-api-post]] -==== HTTP POST +=== HTTP POST Encode parameters as a JSON object in the body. `service.name` is a required parameter. @@ -50,7 +50,7 @@ http(s)://{hostname}:{port}/config/v1/agents [float] [[apm-api-config-api-response]] -==== Responses +=== Responses * Successful - `200` * APM Server is configured to fetch agent configuration from {es} but the configuration is invalid - `403` @@ -58,7 +58,7 @@ http(s)://{hostname}:{port}/config/v1/agents [float] [[apm-api-config-api-example]] -==== Example request +=== Example request Example Agent configuration `GET` request including the service name "test-service": @@ -79,7 +79,7 @@ curl -X POST http://127.0.0.1:8200/config/v1/agents \ [float] [[apm-api-config-api-ex-response]] -==== Example response +=== Example response ["source","sh",subs="attributes"] --------------------------------------------------------------------------- diff --git a/docs/en/observability/apm/api-error.asciidoc b/docs/en/observability/apm/api/apm-server/api-error.asciidoc similarity index 93% rename from docs/en/observability/apm/api-error.asciidoc rename to docs/en/observability/apm/api/apm-server/api-error.asciidoc index 3e49ac2f2e..3044b6ead4 100644 --- a/docs/en/observability/apm/api-error.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-error.asciidoc @@ -1,11 +1,11 @@ [[apm-api-error]] -==== Errors += Errors An error or a logged error message captured by an agent occurring in a monitored service. [float] [[apm-api-error-schema]] -==== Error Schema +== Error Schema APM Server uses JSON Schema to validate requests. The specification for errors is defined on https://github.com/elastic/apm-server/blob/{minor-version}/docs/spec/v2/error.json[GitHub] and included below: diff --git a/docs/en/observability/apm/api-event-example.asciidoc b/docs/en/observability/apm/api/apm-server/api-event-example.asciidoc similarity index 89% rename from docs/en/observability/apm/api-event-example.asciidoc rename to docs/en/observability/apm/api/apm-server/api-event-example.asciidoc index 7dea62cf5a..43252fa7f9 100644 --- a/docs/en/observability/apm/api-event-example.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-event-example.asciidoc @@ -1,5 +1,5 @@ [[apm-api-event-example]] -==== Example request body += Example request body A request body example containing one event for all currently supported event types. diff --git a/docs/en/observability/apm/api-events.asciidoc b/docs/en/observability/apm/api/apm-server/api-events.asciidoc similarity index 92% rename from docs/en/observability/apm/api-events.asciidoc rename to docs/en/observability/apm/api/apm-server/api-events.asciidoc index da1b2f7f67..dd289b0840 100644 --- a/docs/en/observability/apm/api-events.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-events.asciidoc @@ -1,5 +1,5 @@ [[apm-api-events]] -=== Elastic APM events intake API += Elastic APM events intake API NOTE: Most users do not need to interact directly with the events intake API. @@ -24,7 +24,7 @@ See the <> to learn more about the different type [[apm-api-events-endpoint]] [float] -=== Endpoints +== Endpoints APM Server exposes the following endpoints for Elastic APM agent data intake: @@ -38,7 +38,7 @@ APM Server exposes the following endpoints for Elastic APM agent data intake: [[apm-api-events-example]] [float] -=== Request +== Request Send an `HTTP POST` request to the APM Server `intake/v2/events` endpoint: @@ -72,7 +72,7 @@ http(s)://{hostname}:{port}/intake/v3/rum/events [[apm-api-events-response]] [float] -=== Response +== Response On success, the server will respond with a 202 Accepted status code and no body. @@ -80,7 +80,7 @@ Keep in mind that events can succeed and fail independently of each other. Only [[apm-api-events-errors]] [float] -=== Errors +== Errors There are two types of errors that the APM Server may return to an agent: @@ -134,7 +134,7 @@ If you're developing an agent, these errors can be useful for debugging. [[apm-api-events-schema-definition]] [float] -=== Event API Schemas +== Event API Schemas The APM Server uses a collection of JSON Schemas for validating requests to the intake API: @@ -145,9 +145,9 @@ The APM Server uses a collection of JSON Schemas for validating requests to the * <> * <> -include::./api-metadata.asciidoc[] -include::./api-transaction.asciidoc[] -include::./api-span.asciidoc[] -include::./api-error.asciidoc[] -include::./api-metricset.asciidoc[] -include::./api-event-example.asciidoc[] +include::./api-metadata.asciidoc[leveloffset=+1] +include::./api-transaction.asciidoc[leveloffset=+1] +include::./api-span.asciidoc[leveloffset=+1] +include::./api-error.asciidoc[leveloffset=+1] +include::./api-metricset.asciidoc[leveloffset=+1] +include::./api-event-example.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/api-info.asciidoc b/docs/en/observability/apm/api/apm-server/api-info.asciidoc similarity index 94% rename from docs/en/observability/apm/api-info.asciidoc rename to docs/en/observability/apm/api/apm-server/api-info.asciidoc index b1f315ad92..01e2ef14ef 100644 --- a/docs/en/observability/apm/api-info.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-info.asciidoc @@ -1,12 +1,12 @@ [[apm-api-info]] -=== APM Server information API += APM Server information API The APM Server exposes an API endpoint to query general server information. This lightweight endpoint is useful as a server up/down health check. [float] [[apm-api-info-endpoint]] -=== Server Information endpoint +== Server Information endpoint This is the server information endpoint: @@ -28,7 +28,7 @@ the response payload will include some information about the APM server. [float] [[apm-api-info-example-get-without-credentials]] -==== Example: GET, without credentials +=== Example: GET, without credentials Example APM Server status request with GET, without credentials: @@ -55,7 +55,7 @@ curl --verbose -X GET http://127.0.0.1:8200 [float] [[apm-api-info-example-post-with-secret-token]] -==== Example: POST, with secret token +=== Example: POST, with secret token Example APM Server information request with POST, with a <>: diff --git a/docs/en/observability/apm/api-jaeger.asciidoc b/docs/en/observability/apm/api/apm-server/api-jaeger.asciidoc similarity index 92% rename from docs/en/observability/apm/api-jaeger.asciidoc rename to docs/en/observability/apm/api/apm-server/api-jaeger.asciidoc index 9750316a9b..89f249344c 100644 --- a/docs/en/observability/apm/api-jaeger.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-jaeger.asciidoc @@ -1,5 +1,5 @@ [[apm-api-jaeger]] -=== Jaeger event intake += Jaeger event intake Elastic APM natively supports Jaeger, an open-source, distributed tracing system. <>. @@ -11,4 +11,4 @@ Elastic APM natively supports Jaeger, an open-source, distributed tracing system |Name |Endpoint |Jaeger span intake |`/jaeger.api_v2.CollectorService/PostSpans` |Sampling endpoint |`/jaeger.api_v2.SamplingManager/GetSamplingStrategy` -|==== \ No newline at end of file +|==== diff --git a/docs/en/observability/apm/api-metadata.asciidoc b/docs/en/observability/apm/api/apm-server/api-metadata.asciidoc similarity index 97% rename from docs/en/observability/apm/api-metadata.asciidoc rename to docs/en/observability/apm/api/apm-server/api-metadata.asciidoc index 1d8a29e5c1..db3dad5e3f 100644 --- a/docs/en/observability/apm/api-metadata.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-metadata.asciidoc @@ -1,5 +1,5 @@ [[apm-api-metadata]] -==== Metadata += Metadata Every new connection to the APM Server starts with a `metadata` stanza. This provides general metadata concerning the other objects in the stream. @@ -14,7 +14,7 @@ TIP: Metadata is stored under `context` when viewing documents in {es}. [[apm-api-kubernetes-data]] [float] -==== Kubernetes data +== Kubernetes data APM agents automatically read Kubernetes data and send it to the APM Server. In most instances, agents are able to read this data from inside the container. @@ -55,7 +55,7 @@ The table below maps these environment variables to the APM metadata event field [[apm-api-metadata-schema]] [float] -==== Metadata Schema +== Metadata Schema APM Server uses JSON Schema to validate requests. The specification for metadata is defined on https://github.com/elastic/apm-server/blob/{minor-version}/docs/spec/v2/metadata.json[GitHub] and included below: diff --git a/docs/en/observability/apm/api-metricset.asciidoc b/docs/en/observability/apm/api/apm-server/api-metricset.asciidoc similarity index 92% rename from docs/en/observability/apm/api-metricset.asciidoc rename to docs/en/observability/apm/api/apm-server/api-metricset.asciidoc index 8e9b701f67..42eafa1f3b 100644 --- a/docs/en/observability/apm/api-metricset.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-metricset.asciidoc @@ -1,11 +1,11 @@ [[apm-api-metricset]] -==== Metrics += Metrics Metrics contain application metric data captured by an {apm-agent}. [[apm-api-metricset-schema]] [float] -==== Metric Schema +== Metric Schema APM Server uses JSON Schema to validate requests. The specification for metrics is defined on https://github.com/elastic/apm-server/blob/{minor-version}/docs/spec/v2/metricset.json[GitHub] and included below: diff --git a/docs/en/observability/apm/api-otlp.asciidoc b/docs/en/observability/apm/api/apm-server/api-otlp.asciidoc similarity index 93% rename from docs/en/observability/apm/api-otlp.asciidoc rename to docs/en/observability/apm/api/apm-server/api-otlp.asciidoc index 9e75dc6fc6..4215d9ac59 100644 --- a/docs/en/observability/apm/api-otlp.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-otlp.asciidoc @@ -1,5 +1,5 @@ [[apm-api-otlp]] -=== OpenTelemetry intake API += OpenTelemetry intake API APM Server supports receiving traces, metrics, and logs over the https://opentelemetry.io/docs/specs/otlp/[OpenTelemetry Protocol (OTLP)]. @@ -11,7 +11,7 @@ APM Server supports two OTLP communication protocols on the same port: * OTLP/gRPC [discrete] -=== OTLP/gRPC paths +== OTLP/gRPC paths [options="header"] |==== @@ -22,7 +22,7 @@ APM Server supports two OTLP communication protocols on the same port: |==== [discrete] -==== OTLP/HTTP paths +== OTLP/HTTP paths [options="header"] |==== diff --git a/docs/en/observability/apm/api-span.asciidoc b/docs/en/observability/apm/api/apm-server/api-span.asciidoc similarity index 93% rename from docs/en/observability/apm/api-span.asciidoc rename to docs/en/observability/apm/api/apm-server/api-span.asciidoc index 6805e1fb3d..c47df6814f 100644 --- a/docs/en/observability/apm/api-span.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-span.asciidoc @@ -1,11 +1,11 @@ [[apm-api-span]] -==== Spans += Spans Spans are events captured by an agent occurring in a monitored service. [[apm-api-span-schema]] [float] -==== Span Schema +== Span Schema APM Server uses JSON Schema to validate requests. The specification for spans is defined on https://github.com/elastic/apm-server/blob/{minor-version}/docs/spec/v2/span.json[GitHub] and included below: diff --git a/docs/en/observability/apm/api-transaction.asciidoc b/docs/en/observability/apm/api/apm-server/api-transaction.asciidoc similarity index 91% rename from docs/en/observability/apm/api-transaction.asciidoc rename to docs/en/observability/apm/api/apm-server/api-transaction.asciidoc index ff78ee785f..47ff4a8c16 100644 --- a/docs/en/observability/apm/api-transaction.asciidoc +++ b/docs/en/observability/apm/api/apm-server/api-transaction.asciidoc @@ -1,11 +1,11 @@ [[apm-api-transaction]] -==== Transactions += Transactions Transactions are events corresponding to an incoming request or similar task occurring in a monitored service. [[apm-api-transaction-schema]] [float] -==== Transaction Schema +== Transaction Schema APM Server uses JSON Schema to validate requests. The specification for transactions is defined on https://github.com/elastic/apm-server/blob/{minor-version}/docs/spec/v2/transaction.json[GitHub] and included below: diff --git a/docs/en/observability/apm/api.asciidoc b/docs/en/observability/apm/api/apm-server/index.asciidoc similarity index 86% rename from docs/en/observability/apm/api.asciidoc rename to docs/en/observability/apm/api/apm-server/index.asciidoc index 8d81091ca1..d5a71fce4c 100644 --- a/docs/en/observability/apm/api.asciidoc +++ b/docs/en/observability/apm/api/apm-server/index.asciidoc @@ -1,5 +1,5 @@ [[apm-api]] -== APM Server API += APM Server API The APM Server exposes endpoints for: @@ -9,8 +9,12 @@ The APM Server exposes endpoints for: * <> * <> +:leveloffset: +1 + include::./api-info.asciidoc[] include::./api-events.asciidoc[] include::./api-config.asciidoc[] include::./api-otlp.asciidoc[] include::./api-jaeger.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm/api/index.asciidoc b/docs/en/observability/apm/api/index.asciidoc new file mode 100644 index 0000000000..f12d2ad666 --- /dev/null +++ b/docs/en/observability/apm/api/index.asciidoc @@ -0,0 +1,17 @@ +[[apm-apis]] += APM APIs + +There are two kinds of APIs related to Elastic APM: + +[cols="1,1"] +|=== +| <> +| {kib} APIs specific to working with the APM UI including updating configuration options, + uploading real user monitoring (RUM) source maps, adding annotations, and more. +| <> +| APIs for working with APM Server. + These are mainly intake APIs that accept data from APM agents and are used primarily by APM agent developers. +|=== + +include::{observability-docs-root}/docs/en/observability/apm/api/api-ui.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/api/apm-server/index.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/apm-data-security.asciidoc b/docs/en/observability/apm/apm-data-security.asciidoc deleted file mode 100644 index 4ff5d4facc..0000000000 --- a/docs/en/observability/apm/apm-data-security.asciidoc +++ /dev/null @@ -1,596 +0,0 @@ -[[apm-data-security]] -=== Data security - -When setting up Elastic APM, it's essential to review all captured data carefully to ensure -it doesn't contain sensitive information like passwords, credit card numbers, or health data. -In addition, you may wish to filter out other identifiable information, like IP addresses, user agent information, -or form field data. - -Depending on the type of data, we offer several different ways to filter, manipulate, -or obfuscate sensitive information during or before ingestion: - -* <> -* <> - -In addition to utilizing filters, you should regularly review the <> table to ensure -sensitive data is not being ingested. If it is, it's possible to remove or redact it. -See <> for more information. - -[float] -[[apm-built-in-data-filters]] -==== Built-in data filters - -// tag::data-filters[] -Built-in data filters allow you to filter or turn off ingestion of the following types of data: - -[options="header"] -|==== -|Data type |Common sensitive data -|<> |Passwords, credit card numbers, authorization, etc. -|<> |Passwords, credit card numbers, etc. -|<> |Client IP address and user agent. -|<> |URLs visited, click events, user browser errors, resources used, etc. -|<> |Sensitive user or business information -|==== -// end::data-filters[] - -[float] -[[apm-custom-data-filters]] -==== Custom filters - -// tag::custom-filters[] -Custom filters allow you to filter or redact other types of APM data on ingestion: - -|==== -|<> | Applied at ingestion time. -All agents and fields are supported. Data leaves the instrumented service. -There are no performance overhead implications on the instrumented service. - -|<> | Not supported by all agents. -Data is sanitized before leaving the instrumented service. -Potential overhead implications on the instrumented service -|==== -// end::custom-filters[] - -[float] -[[apm-sensitive-fields]] -==== Sensitive fields - -You should review the following fields regularly to ensure sensitive data is not being captured: - -[options="header"] -|==== -| Field | Description | Remedy -| `client.ip` | The client IP address, as forwarded by proxy. | <> -| `http.request.body.original` | The body of the monitored HTTP request. | <> -| `http.request.headers` | The canonical headers of the monitored HTTP request. | <> -| `http.request.socket.remote_address` | The address of the last proxy or end-user (if no proxy). | <> -| `http.response.headers` | The canonical headers of the monitored HTTP response. | <> -| `process.args` | Process arguments. | <> -| `span.db.statement` | Database statement. | <> -| `stacktrace.vars` | A flat mapping of local variables captured in the stack frame | <> -| `url.query` | The query string of the request, e.g. `?pass=hunter2`. | <> -| `user.*` | Logged-in user information. | <> -| `user_agent.*` | Device and version making the network request. | <> -|==== - -// **************************************************************** - -[[apm-filtering]] -==== Built-in data filters - -include::./apm-data-security.asciidoc[tag=data-filters] - -[discrete] -[[apm-filters-http-header]] -==== HTTP headers - -By default, APM agents capture HTTP request and response headers (including cookies). -Most Elastic APM agents provide the ability to sanitize HTTP header fields, -including cookies and `application/x-www-form-urlencoded` data (POST form fields). -Query string and captured request bodies, like `application/json` data, are not sanitized. - -The default list of sanitized fields attempts to target common field names for data relating to -passwords, credit card numbers, authorization, etc., but can be customized to fit your data. -This sensitive data never leaves the instrumented service. - -This setting supports <>, -which means the list of sanitized fields can be updated without needing to redeploy your services: - -* Go: {apm-go-ref-v}/configuration.html#config-sanitize-field-names[`ELASTIC_APM_SANITIZE_FIELD_NAMES`] -* Java: {apm-java-ref-v}/config-core.html#config-sanitize-field-names[`sanitize_field_names`] -* .NET: {apm-dotnet-ref-v}/config-core.html#config-sanitize-field-names[`sanitizeFieldNames`] -* Node.js: {apm-node-ref-v}/configuration.html#sanitize-field-names[`sanitizeFieldNames`] -// * PHP: {apm-php-ref-v}[``] -* Python: {apm-py-ref-v}/configuration.html#config-sanitize-field-names[`sanitize_field_names`] -* Ruby: {apm-ruby-ref-v}/configuration.html#config-sanitize-field-names[`sanitize_field_names`] - -Alternatively, you can completely disable the capturing of HTTP headers. -This setting also supports <>: - -* Go: {apm-go-ref-v}/configuration.html#config-capture-headers[`ELASTIC_APM_CAPTURE_HEADERS`] -* Java: {apm-java-ref-v}/config-core.html#config-capture-headers[`capture_headers`] -* .NET: {apm-dotnet-ref-v}/config-http.html#config-capture-headers[`CaptureHeaders`] -* Node.js: {apm-node-ref-v}/configuration.html#capture-headers[`captureHeaders`] -// * PHP: {apm-php-ref-v}[``] -* Python: {apm-py-ref-v}/configuration.html#config-capture-headers[`capture_headers`] -* Ruby: {apm-ruby-ref-v}/configuration.html#config-capture-headers[`capture_headers`] - -[discrete] -[[apm-filters-http-body]] -==== HTTP bodies - -By default, the body of HTTP requests is not recorded. -Request bodies often contain sensitive data like passwords or credit card numbers, -so use care when enabling this feature. - -This setting supports <>, -which means the list of sanitized fields can be updated without needing to redeploy your services: - -* Go: {apm-go-ref-v}/configuration.html#config-capture-body[`ELASTIC_APM_CAPTURE_BODY`] -* Java: {apm-java-ref-v}/config-core.html#config-capture-body[`capture_body`] -* .NET: {apm-dotnet-ref-v}/config-http.html#config-capture-body[`CaptureBody`] -* Node.js: {apm-node-ref-v}/configuration.html#capture-body[`captureBody`] -// * PHP: {apm-php-ref-v}[``] -* Python: {apm-py-ref-v}/configuration.html#config-capture-body[`capture_body`] -* Ruby: {apm-ruby-ref-v}/configuration.html#config-capture-body[`capture_body`] - -[discrete] -[[apm-filters-personal-data]] -==== Personal data - -By default, the APM Server captures some personal data associated with trace events: - -* `client.ip`: The client's IP address. Typically derived from the HTTP headers of incoming requests. -`client.ip` is also used in conjunction with the {ref}/geoip-processor.html[`geoip` processor] to assign -geographical information to trace events. To learn more about how `client.ip` is derived, -see <>. -* `user_agent`: User agent data, including the client operating system, device name, vendor, and version. - -The capturing of this data can be turned off by setting -**Capture personal data** to `false`. - -[discrete] -[[apm-filters-real-user-data]] -==== Real user monitoring data - -Protecting user data is important. -For that reason, individual RUM instrumentations can be disabled in the RUM agent with the -{apm-rum-ref-v}/configuration.html#disable-instrumentations[`disableInstrumentations`] configuration variable. -Disabled instrumentations produce no spans or transactions. - -[options="header"] -|==== -|Disable |Configuration value -|HTTP requests |`fetch` and `xmlhttprequest` -|Page load metrics including static resources |`page-load` -|JavaScript errors on the browser |`error` -|User click events including URLs visited, mouse clicks, and navigation events |`eventtarget` -|Single page application route changes |`history` -|==== - -[discrete] -[[apm-filters-database-statements]] -==== Database statements - -For SQL databases, APM agents do not capture the parameters of prepared statements. -Note that Elastic APM currently does not make an effort to strip parameters of regular statements. -Not using prepared statements makes your code vulnerable to SQL injection attacks, -so be sure to use prepared statements. - -For non-SQL data stores, such as {es} or MongoDB, -Elastic APM captures the full statement for queries. -For inserts or updates, the full document is not stored. -To filter or obfuscate data in non-SQL database statements, -or to remove the statement entirely, -you can set up an ingest node pipeline. - -[discrete] -[[apm-filters-agent-specific]] -==== Agent-specific options - -Certain agents offer additional filtering and obfuscating options: - -**Agent configuration options** - -* (Node.js) Remove errors raised by the server-side process: -disable with {apm-node-ref-v}/configuration.html#capture-exceptions[captureExceptions]. - -* (Java) Remove process arguments from transactions: -disabled by default with {apm-java-ref-v}/config-reporter.html#config-include-process-args[`include_process_args`]. - -// **************************************************************** - -[[apm-custom-filter]] -==== Custom filters - -include::./apm-data-security.asciidoc[tag=custom-filters] - -[discrete] -[[apm-filters-ingest-pipeline]] -==== Create an ingest pipeline filter - -Ingest node pipelines specify a series of processors that transform data in a specific way. -Transformation happens prior to indexing--inflicting no performance overhead on the monitored application. -Pipelines are a flexible and easy way to filter or obfuscate Elastic APM data. - -[discrete] -[[apm-filters-ingest-pipeline-tutorial]] -===== Tutorial: redact sensitive information - -Say you decide to <> -but quickly notice that sensitive information is being collected in the -`http.request.body.original` field: - -[source,json] ----- -{ - "email": "test@abc.com", - "password": "hunter2" -} ----- - -**Create a pipeline** - -To obfuscate the passwords stored in the request body, -you can use a series of {ref}/processors.html[ingest processors]. -To start, create a pipeline with a simple description and an empty array of processors: - -[source,json] ----- -{ - "pipeline": { - "description": "redact http.request.body.original.password", - "processors": [] <1> - } -} ----- -<1> The processors defined below will go in this array - -**Add a JSON processor** - -Add your first processor to the processors array. -Because the agent captures the request body as a string, use the -{ref}/json-processor.html[JSON processor] to convert the original field value into a structured JSON object. -Save this JSON object in a new field: - -[source,json] ----- -{ - "json": { - "field": "http.request.body.original", - "target_field": "http.request.body.original_json", - "ignore_failure": true - } -} ----- - -**Add a set processor** - -If `body.original_json` is not `null`, i.e., it exists, we'll redact the `password` with the {ref}/set-processor.html[set processor], -by setting the value of `body.original_json.password` to `"redacted"`: - -[source,json] ----- -{ - "set": { - "field": "http.request.body.original_json.password", - "value": "redacted", - "if": "ctx?.http?.request?.body?.original_json != null" - } -} ----- - -**Add a convert processor** - -Use the {ref}/convert-processor.html[convert processor] to convert the JSON value of `body.original_json` to a string and set it as the `body.original` value: - -[source,json] ----- -{ - "convert": { - "field": "http.request.body.original_json", - "target_field": "http.request.body.original", - "type": "string", - "if": "ctx?.http?.request?.body?.original_json != null", - "ignore_failure": true - } -} ----- - -**Add a remove processor** - -Finally, use the {ref}/remove-processor.html[remove processor] to remove the `body.original_json` field: - -[source,json] ----- -{ - "remove": { - "field": "http.request.body.original", - "if": "ctx?.http?.request?.body?.original_json != null", - "ignore_failure": true - } -} ----- - -**Register the pipeline** - -Now we'll put it all together. -Use the {ref}/put-pipeline-api.html[create or update pipeline API] to register the new pipeline in {es}. -Name the pipeline `apm_redacted_body_password`: - -[source,console] ----- -PUT _ingest/pipeline/apm_redacted_body_password -{ - "description": "redact http.request.body.original.password", - "processors": [ - { - "json": { - "field": "http.request.body.original", - "target_field": "http.request.body.original_json", - "ignore_failure": true - } - }, - { - "set": { - "field": "http.request.body.original_json.password", - "value": "redacted", - "if": "ctx?.http?.request?.body?.original_json != null" - } - }, - { - "convert": { - "field": "http.request.body.original_json", - "target_field": "http.request.body.original", - "type": "string", - "if": "ctx?.http?.request?.body?.original_json != null", - "ignore_failure": true - } - }, - { - "remove": { - "field": "http.request.body.original_json", - "if": "ctx?.http?.request?.body?.original_json != null", - "ignore_failure": true - } - } - ] -} ----- - -**Test the pipeline** - -Prior to enabling this new pipeline, you can test it with the {ref}/simulate-pipeline-api.html[simulate pipeline API]. -This API allows you to run multiple documents through a pipeline to ensure it is working correctly. - -The request below simulates running three different documents through the pipeline: - -[source,console] ----- -POST _ingest/pipeline/apm_redacted_body_password/_simulate -{ - "docs": [ - { - "_source": { <1> - "http": { - "request": { - "body": { - "original": """{"email": "test@abc.com", "password": "hunter2"}""" - } - } - } - } - }, - { - "_source": { <2> - "some-other-field": true - } - }, - { - "_source": { <3> - "http": { - "request": { - "body": { - "original": """["invalid json" """ - } - } - } - } - } - ] -} ----- -<1> This document features the same sensitive data from the original example above -<2> This document only contains an unrelated field -<3> This document contains invalid JSON - -The API response should be similar to this: - -[source,json] ----- -{ - "docs" : [ - { - "doc" : { - "_source" : { - "http" : { - "request" : { - "body" : { - "original" : { - "password" : "redacted", - "email" : "test@abc.com" - } - } - } - } - } - } - }, - { - "doc" : { - "_source" : { - "nobody" : true - } - } - }, - { - "doc" : { - "_source" : { - "http" : { - "request" : { - "body" : { - "original" : """["invalid json" """ - } - } - } - } - } - } - ] -} ----- - -As expected, only the first simulated document has a redacted password field. -All other documents are unaffected. - -**Create an `@custom` pipeline** - -The final step in this process is to call the newly created `apm_redacted_body_password` pipeline -from the `@custom` pipeline of the data stream you wish to edit. - -include::./ingest-pipelines.asciidoc[tag=ingest-pipeline-naming] - -Use the {ref}/put-pipeline-api.html[create or update pipeline API] to register the new pipeline in {es}. -Name the pipeline `traces-apm@custom`: - -[source,console] ----- -PUT _ingest/pipeline/traces-apm@custom -{ - "processors": [ - { - "pipeline": { - "name": "apm_redacted_body_password" <1> - } - } - ] -} ----- -<1> The name of the pipeline we previously created - -TIP: If you prefer using a GUI, you can instead open {kib} and navigate to -**Stack Management** -> **Ingest Pipelines** -> **Create pipeline**. -Use the same naming convention explained previously to ensure your new pipeline matches the correct APM data stream. - -That's it! Passwords will now be redacted from your APM HTTP body data. - -To learn more about ingest pipelines, see <>. - -[discrete] -[[apm-filters-in-agent]] -==== APM agent filters - -Some APM agents offer a way to manipulate or drop APM events _before_ they are sent to the APM Server. -Please see the relevant agent's documentation for more information and examples: - -// * Go: {apm-go-ref-v}/[] -// * Java: {apm-java-ref-v}/[] -* .NET: {apm-dotnet-ref-v}/public-api.html#filter-api[Filter API]. -* Node.js: {apm-node-ref-v}/agent-api.html#apm-add-filter[`addFilter()`]. -// * PHP: {apm-php-ref-v}[] -* Python: {apm-py-ref-v}/sanitizing-data.html[custom processors]. -* Ruby: {apm-ruby-ref-v}/api.html#api-agent-add-filter[`add_filter()`]. - -// **************************************************************** - -[[apm-data-security-delete]] -==== Delete sensitive data - -If you accidentally ingest sensitive data, follow these steps to remove or redact the offending data: - -. Stop collecting the sensitive data. -Use the *remedy* column of the <> table to determine how to stop collecting -the offending data. - -. Delete or redact the ingested data. With data collection fixed, you can now delete or redact the offending data: -+ -* <> -* <> - -[float] -[[apm-redact-field-data]] -===== Redact specific fields - -To redact sensitive data in a specific field, use the {ref}/docs-update-by-query.html[update by query API]. - -For example, the following query removes the `client.ip` address -from APM documents in the `logs-apm.error-default` data stream: - -[source, console] ----- -POST /logs-apm.error-default/_update_by_query -{ - "query": { - "exists": { - "field": "client.ip" - } - } - "script": { - "source": "ctx._source.client.ip = params.redacted", - "params": { - "redacted": "[redacted]" - } - } -} ----- - -Or, perhaps you only want to redact IP addresses from European users: - -[source, console] ----- -POST /logs-apm.error-default/_update_by_query -{ - "query": { - "term": { - "client.geo.continent_name": { - "value": "Europe" - } - } - }, - "script": { - "source": "ctx._source.client.ip = params.redacted", - "params": { - "redacted": "[redacted]" - } - } -} ----- - -See {ref}/docs-update-by-query.html[update by query API] for more information and examples. - -[float] -[[apm-delete-doc-data]] -===== Delete {es} documents - -WARNING: This will permanently delete your data. -You should test your queries with the {ref}/search-search.html[search API] prior to deleting data. - -To delete an {es} document, -you can use the {ref}/docs-delete-by-query.html[delete by query API]. - -For example, to delete all documents in the `apm-traces-*` data stream with a `user.email` value, run the following query: - -[source, console] ----- -POST /apm-traces-*/_delete_by_query -{ - "query": { - "exists": { - "field": "user.email" - } - } -} ----- - -See {ref}/docs-delete-by-query.html[delete by query API] for more information and examples. diff --git a/docs/en/observability/apm-ui/agent-configuration.asciidoc b/docs/en/observability/apm/collect-application-data/agents/agent-configuration.asciidoc similarity index 93% rename from docs/en/observability/apm-ui/agent-configuration.asciidoc rename to docs/en/observability/apm/collect-application-data/agents/agent-configuration.asciidoc index 13d929dd53..7441b33b76 100644 --- a/docs/en/observability/apm-ui/agent-configuration.asciidoc +++ b/docs/en/observability/apm/collect-application-data/agents/agent-configuration.asciidoc @@ -1,8 +1,8 @@ [[apm-agent-configuration]] -=== APM Agent central configuration += APM agent central configuration ++++ -Configure APM agents with central config +Centrally configure APM agents in Kibana ++++ APM Agent configuration allows you to fine-tune your APM agent configuration from within the APM UI. @@ -15,7 +15,7 @@ The APM UI will let you know when your APM agents have applied your configuratio image::./images/apm-agent-configuration.png[APM Agent configuration in Kibana] [float] -==== Precedence +== Precedence Configurations set from the APM UI take precedence over configurations set locally in each APM agent. However, if APM Server is slow to respond, is offline, reports an error, etc., @@ -23,7 +23,7 @@ APM agents will use local defaults until they're able to update the configuratio For this reason, it is still essential to set custom default configurations locally in each of your APM agents. [float] -==== Supported configurations +== Supported configurations Each APM agent has a list of supported configurations. After selecting a Service name and environment in the APM UI, @@ -45,7 +45,7 @@ Ruby agent:: {apm-ruby-ref}/configuration.html[Configuration reference] Real User Monitoring (RUM) agent:: {apm-rum-ref}/configuration.html[Configuration reference] [float] -==== APM Server configuration +== APM Server configuration For most users, APM agent configuration should work out-of-the-box. If you run into trouble, it may be because you're not using the {es} output, diff --git a/docs/en/observability/apm/collect-application-data/agents/index.asciidoc b/docs/en/observability/apm/collect-application-data/agents/index.asciidoc new file mode 100644 index 0000000000..d52dab9eee --- /dev/null +++ b/docs/en/observability/apm/collect-application-data/agents/index.asciidoc @@ -0,0 +1,41 @@ +[[apm-agents]] += APM agents + +Elastic APM agents automatically measure application performance and track errors. +They offer built-in support for popular frameworks and technologies, and provide easy-to-use +APIs that allow you to instrument any application. + +[discrete] +== Available APM agents + +Elastic APM agents are built and maintained by Elastic. While they are similar, different +programming languages have different nuances and requirements. Refer to each APM agent's +documentation to learn how to install the agent, configure it, and more: + +* {apm-android-ref}/intro.html[APM Android agent] +* {apm-go-ref}/introduction.html[APM Go agent] +* {apm-ios-ref}/intro.html[APM iOS agent] +* {apm-java-ref}/intro.html[APM Java agent] +* {apm-dotnet-ref}/intro.html[APM .NET agent] +* {apm-node-ref}/intro.html[APM Node.js agent] +* {apm-php-ref}/intro.html[APM PHP agent] +* {apm-py-ref}/getting-started.html[APM Python agent] +* {apm-ruby-ref}/introduction.html[APM Ruby agent] +* {apm-rum-ref}/intro.html[APM Real User Monitoring JavaScript agent] + +[discrete] +== More APM agent resources + +Though you should refer to each APM agent's documentation for information on using the agent, +there are some tasks you can complete in the APM UI: + +* <> +* <> + +//// +Subsections +//// + +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/agents/agent-configuration.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/agents/rum.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/agents/source-map-how-to.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/apm-rum.asciidoc b/docs/en/observability/apm/collect-application-data/agents/rum.asciidoc similarity index 96% rename from docs/en/observability/apm/apm-rum.asciidoc rename to docs/en/observability/apm/collect-application-data/agents/rum.asciidoc index 7ca2368f49..b4750cb14d 100644 --- a/docs/en/observability/apm/apm-rum.asciidoc +++ b/docs/en/observability/apm/collect-application-data/agents/rum.asciidoc @@ -1,5 +1,5 @@ [[apm-rum]] -=== Real User Monitoring (RUM) += Real User Monitoring (RUM) Real User Monitoring captures user interaction with clients such as web browsers. The {apm-rum-ref-v}[JavaScript Agent] is Elastic’s RUM Agent. // To use it you need to {apm-server-ref-v}/configuration-rum.html[enable RUM support] in the APM Server. diff --git a/docs/en/observability/apm/source-map-how-to.asciidoc b/docs/en/observability/apm/collect-application-data/agents/source-map-how-to.asciidoc similarity index 96% rename from docs/en/observability/apm/source-map-how-to.asciidoc rename to docs/en/observability/apm/collect-application-data/agents/source-map-how-to.asciidoc index 12acf196f9..8c76192810 100644 --- a/docs/en/observability/apm/source-map-how-to.asciidoc +++ b/docs/en/observability/apm/collect-application-data/agents/source-map-how-to.asciidoc @@ -1,5 +1,5 @@ [[apm-source-map-how-to]] -=== Create and upload source maps (RUM) += Create and upload source maps (RUM) Minifying JavaScript bundles in production is a common practice; it can greatly improve the load time and network latency of your applications. @@ -32,7 +32,7 @@ Follow the steps below to enable source mapping your error stack traces in the A [float] [[apm-source-map-rum-initialize]] -=== Initialize the RUM Agent +== Initialize the RUM Agent Set the service name and version of your application when initializing the RUM Agent. To make uploading subsequent source maps easier, the `serviceVersion` you choose might be the @@ -62,7 +62,7 @@ The APM integration uses the service name and version to match the correct sourc [float] [[apm-source-map-rum-generate]] -=== Generate a source map +== Generate a source map To be compatible with Elastic APM, source maps must follow the https://sourcemaps.info/spec.html[source map revision 3 proposal spec]. @@ -95,7 +95,7 @@ module.exports = { [float] [[apm-source-map-rum-upload]] -=== Upload the source map +== Upload the source map TIP: When uploading a source map, ensure that RUM support is enabled in the APM integration. @@ -114,7 +114,7 @@ If you have multiple source maps, you'll need to upload each individually. [float] [[apm-source-map-curl]] -==== Upload via curl +=== Upload via curl Here’s an example curl request that uploads the source map file created in the previous step. This request uses an API key for authentication. @@ -136,7 +136,7 @@ curl -X POST "http://localhost:5601/api/apm/sourcemaps" \ [float] [[apm-source-map-custom-app]] -==== Upload via a custom app +=== Upload via a custom app To ensure uploading source maps become a part of your deployment process, consider automating the process with a custom application. @@ -169,7 +169,7 @@ request.post({url: 'http://localhost:5601/api/apm/sourcemaps',formData: formData [float] [[apm-source-map-next]] -=== What happens next +== What happens next Source maps are stored in {es}. When you upload a source map, a new {es} document is created containing the contents of the source map. diff --git a/docs/en/observability/apm/aws-lambda-extension.asciidoc b/docs/en/observability/apm/collect-application-data/aws-lambda-extension.asciidoc similarity index 93% rename from docs/en/observability/apm/aws-lambda-extension.asciidoc rename to docs/en/observability/apm/collect-application-data/aws-lambda-extension.asciidoc index b2efe4673c..f4280f8000 100644 --- a/docs/en/observability/apm/aws-lambda-extension.asciidoc +++ b/docs/en/observability/apm/collect-application-data/aws-lambda-extension.asciidoc @@ -1,6 +1,10 @@ [[apm-monitoring-aws-lambda]] = Monitoring AWS Lambda Functions +++++ +AWS Lambda Functions +++++ + Elastic APM lets you monitor your AWS Lambda functions. The natural integration of <> into your AWS Lambda functions provides insights into the function's execution and runtime behavior as well as its relationships and dependencies to other services. diff --git a/docs/en/observability/apm/collect-application-data/index.asciidoc b/docs/en/observability/apm/collect-application-data/index.asciidoc new file mode 100644 index 0000000000..1d8f3b19d1 --- /dev/null +++ b/docs/en/observability/apm/collect-application-data/index.asciidoc @@ -0,0 +1,86 @@ +[[apm-collect-application-data]] += Collect application data + +[discrete] +== Language-specific options + +Use Elastic APM agents or an OpenTelemetry language SDK to instrument a service in the language its written in: + +* <>: Elastic APM agents are instrumentation libraries written in the same language as your service. +* <>: OpenTelemetry is an open source set of APIs, SDKs, tooling, and integrations that enable the capture and management of telemetry data from your services and applications. +** This option includes Elastic Distributions of OpenTelemetry, which are customized versions of https://opentelemetry.io/docs/languages/[OpenTelemetry language SDKs] that are optimized to work with an Elastic backend. + +*Not sure which method is right for you?* Compare the available options below. + +[discrete] +=== Capabilities + +//// +TO DO: +Is this table even helpful? +Is it missing anything that would make it more helpful? +//// +|=== +| | Elastic APM agent | Elastic Distribution of OpenTelemetry + +| *Support level* +| Fully supported +| Mixed support + +_Refer to the_ <> + +| *Data protocol* +| Elastic protocol +| https://opentelemetry.io/docs/specs/otel/protocol/[OpenTelemetry protocol (OTLP)] + +| *Central configuration* +| Supported + +_Refer to_ <> +| Not supported +|=== + +[discrete] +[[apm-collect-data-availability]] +=== Availability + +:not-available: image:images/icons/cross.svg[Not available] + +//// +TO DO: +Are we ok with maintaining this table? +Are we ok with the gaps it exposes? +//// +[cols="<,^,^"] +|=== +| *Language* | *Elastic APM agent* | *Elastic Distributions of OpenTelemetry (EDOT)* +| *Android* | Android agent | {not-available} +| *Go* | Go agent | {not-available} +| *iOS* | iOS agent | {not-available} +| *Java* | Java agent | EDOT Java +| *.NET* | .NET agent | preview:[] EDOT .NET +| *Node.js* | Node.js agent | preview:[] EDOT Node.js +| *PHP* | PHP agent | preview:[] EDOT PHP +| *Python* | Python agent | preview:[] EDOT Python +| *Ruby* | Ruby agent | {not-available} +|=== + +[discrete] +== Service-specific options + +Elastic also offers several tools to help you collect data from specific services: + +* *Kubernetes*: The Elastic APM attacher for Kubernetes simplifies the instrumentation and configuration of your application pods. + Read more in the {apm-attacher-ref}/apm-attacher.html[APM attacher for Kubernetes docs]. +* *AWS Lambda Functions*: Helps you monitor your AWS Lambda functions. + Read more in the {apm-lambda-ref}/aws-lambda-arch.html[APM Architecture for AWS Lambda docs]. +* deprecated:[8.15.0] *Jaeger*: Helps you to switch an existing Jaeger setup from the default + Jaeger backend to the {stack}. Read more in <>. + +//// +Subsections +//// + +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/agents/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/open-telemetry/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/k8s-attacher.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/aws-lambda-extension.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/collect-application-data/jaeger-integration.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/jaeger-integration.asciidoc b/docs/en/observability/apm/collect-application-data/jaeger-integration.asciidoc similarity index 94% rename from docs/en/observability/apm/jaeger-integration.asciidoc rename to docs/en/observability/apm/collect-application-data/jaeger-integration.asciidoc index d703756c69..47c1cb42d6 100644 --- a/docs/en/observability/apm/jaeger-integration.asciidoc +++ b/docs/en/observability/apm/collect-application-data/jaeger-integration.asciidoc @@ -1,8 +1,8 @@ [[apm-jaeger-integration]] -=== Jaeger integration += Integrate with Jaeger ++++ -Integrate with Jaeger +Jaeger (deprecated) ++++ WARNING: Support for Jaeger is deprecated and will be removed in a future version of Elastic APM. https://www.jaegertracing.io/docs/1.35/client-libraries/[Jaeger clients are deprecated] in favor of OpenTelemetry SDKs, and OpenTelemetry has removed all Jaeger exporters from their https://github.com/open-telemetry/opentelemetry-specification/pull/2858[specification]. @@ -14,7 +14,7 @@ Best of all, no instrumentation changes are needed in your application code. [float] [[apm-jaeger-architecture]] -=== Supported architecture +== Supported architecture Jaeger architecture supports different data formats and transport protocols that define how data can be sent to a collector. Elastic APM, as a Jaeger collector, @@ -33,7 +33,7 @@ for more information on Jaeger architecture. [float] [[apm-get-started-jaeger]] -=== Get started +== Get started Connect your preexisting Jaeger setup to Elastic APM in three steps: @@ -45,7 +45,7 @@ IMPORTANT: There are <> to this integration. [float] [[apm-configure-agent-client-jaeger]] -==== Configure Jaeger agents +=== Configure Jaeger agents The APM integration serves Jaeger gRPC over the same host and port as the Elastic {apm-agent} protocol. @@ -53,7 +53,7 @@ include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/jaeger- [float] [[apm-configure-sampling-jaeger]] -==== Configure Sampling +=== Configure Sampling The APM integration supports probabilistic sampling, which can be used to reduce the amount of data that your agents collect and send. Probabilistic sampling makes a random sampling decision based on the configured sampling value. @@ -66,7 +66,7 @@ There are two different ways to configure the sampling rate of your Jaeger agent [float] [[apm-configure-sampling-central-jaeger]] -===== {apm-agent} central configuration (default) +==== {apm-agent} central configuration (default) Central sampling, with {apm-agent} central configuration, allows Jaeger clients to poll APM Server for the sampling rate. @@ -75,7 +75,7 @@ See <> to learn more. [float] [[apm-configure-sampling-local-jaeger]] -===== Local sampling in each Jaeger client +==== Local sampling in each Jaeger client If you don't have access to the APM UI, you'll need to change the Jaeger client's `sampler.type` and `sampler.param`. @@ -85,13 +85,13 @@ for more information. [float] [[apm-configure-start-jaeger]] -==== Start sending data +=== Start sending data That's it! Data sent from Jaeger clients to the APM Server can now be viewed in the APM UI. [float] [[apm-caveats-jaeger]] -=== Caveats +== Caveats There are some limitations and differences between Elastic APM and Jaeger that you should be aware of. diff --git a/docs/en/observability/apm/apm-k8s-attacher.asciidoc b/docs/en/observability/apm/collect-application-data/k8s-attacher.asciidoc similarity index 63% rename from docs/en/observability/apm/apm-k8s-attacher.asciidoc rename to docs/en/observability/apm/collect-application-data/k8s-attacher.asciidoc index 9267d54132..1e1b070a4d 100644 --- a/docs/en/observability/apm/apm-k8s-attacher.asciidoc +++ b/docs/en/observability/apm/collect-application-data/k8s-attacher.asciidoc @@ -1,7 +1,11 @@ [[apm-k8s-attacher]] = APM K8S Attacher -The {apm-attacher-ref}/apm-attacher.html[APM attacher] for Kubernetes simplifies the instrumentation and configuration of your application pods. +++++ +Kubernetes +++++ + +The {apm-attacher-ref}/apm-attacher.html[APM attacher for Kubernetes] simplifies the instrumentation and configuration of your application pods. The attacher includes a webhook receiver that modifies pods so they are automatically instrumented by an Elastic APM agent. Ready to get started? See {apm-attacher-ref}/apm-get-started-webhook.html[Instrument and configure pods] to get started. diff --git a/docs/en/observability/apm/open-telemetry.asciidoc b/docs/en/observability/apm/collect-application-data/open-telemetry/index.asciidoc similarity index 96% rename from docs/en/observability/apm/open-telemetry.asciidoc rename to docs/en/observability/apm/collect-application-data/open-telemetry/index.asciidoc index 0e387498c3..f1cb772a06 100644 --- a/docs/en/observability/apm/open-telemetry.asciidoc +++ b/docs/en/observability/apm/collect-application-data/open-telemetry/index.asciidoc @@ -1,8 +1,8 @@ [[apm-open-telemetry]] -== Use OpenTelemetry with APM += Use OpenTelemetry with APM ++++ -Use OpenTelemetry +OpenTelemetry ++++ [NOTE] @@ -139,16 +139,14 @@ To get started, follow the official AWS Distro for OpenTelemetry Lambda document https://aws-otel.github.io/docs/getting-started/lambda[*Get started with the AWS Distro for OpenTelemetry Lambda*^] image:images/icons/popout.svg[] -// TODO: I'm not sure what this diagram should look like... -// image::images/apm-otel-lambda.png[] +//// +Subsections +//// -include::./otel-direct.asciidoc[] - -include::./otel-metrics.asciidoc[] - -include::./otel-limitations.asciidoc[] - -include::./otel-attrs.asciidoc[] +include::./otel-direct.asciidoc[leveloffset=+1] +include::./otel-metrics.asciidoc[leveloffset=+1] +include::./otel-limitations.asciidoc[leveloffset=+1] +include::./otel-attrs.asciidoc[leveloffset=+1] // **** // The text below is used in the Quick start guide diff --git a/docs/en/observability/apm/otel-attrs.asciidoc b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-attrs.asciidoc similarity index 98% rename from docs/en/observability/apm/otel-attrs.asciidoc rename to docs/en/observability/apm/collect-application-data/open-telemetry/otel-attrs.asciidoc index 7a4bac9654..a54ebb0a3e 100644 --- a/docs/en/observability/apm/otel-attrs.asciidoc +++ b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-attrs.asciidoc @@ -1,5 +1,5 @@ [[apm-open-telemetry-resource-attributes]] -=== Resource attributes += Resource attributes A resource attribute is a key/value pair containing information about the entity producing telemetry. Resource attributes are mapped to Elastic Common Schema (ECS) fields like `service.*`, `cloud.*`, `process.*`, etc. diff --git a/docs/en/observability/apm/otel-direct.asciidoc b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-direct.asciidoc similarity index 97% rename from docs/en/observability/apm/otel-direct.asciidoc rename to docs/en/observability/apm/collect-application-data/open-telemetry/otel-direct.asciidoc index df1a47d6f2..9761a73dbf 100644 --- a/docs/en/observability/apm/otel-direct.asciidoc +++ b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-direct.asciidoc @@ -1,5 +1,5 @@ [[apm-open-telemetry-direct]] -=== Upstream OpenTelemetry Collectors and language SDKs += Upstream OpenTelemetry Collectors and language SDKs [NOTE] ==== @@ -17,7 +17,7 @@ be sent directly to the {stack}. [discrete] [[apm-connect-open-telemetry-collector]] -==== Send data from an upstream OpenTelemetry Collector +== Send data from an upstream OpenTelemetry Collector Connect your OpenTelemetry Collector instances to Elastic {observability} using the OTLP exporter: @@ -83,7 +83,7 @@ In addition, your data will not be viewable in the {kib} {observability} apps if [discrete] [[apm-instrument-apps-otel]] -==== Send data from an upstream OpenTelemetry SDK +== Send data from an upstream OpenTelemetry SDK [NOTE] ==== @@ -139,7 +139,7 @@ and <> in {kib}. [discrete] [[apm-open-telemetry-proxy-apm]] -==== Proxy requests to APM Server +== Proxy requests to APM Server APM Server supports both the https://opentelemetry.io/docs/specs/otlp/#otlpgrpc[OTLP/gRPC] and https://opentelemetry.io/docs/specs/otlp/#otlphttp[OTLP/HTTP] protocol on the same port as Elastic APM agent requests. For ease of setup, we recommend using OTLP/HTTP when proxying or load balancing requests to the APM Server. @@ -155,7 +155,7 @@ https://github.com/elastic/apm-server/blob/main/dev_docs/otel.md#muxing-grpc-and [discrete] [[apm-open-telemetry-direct-next]] -==== Next steps +== Next steps * <> * Learn about the <> diff --git a/docs/en/observability/apm/otel-limitations.asciidoc b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-limitations.asciidoc similarity index 95% rename from docs/en/observability/apm/otel-limitations.asciidoc rename to docs/en/observability/apm/collect-application-data/open-telemetry/otel-limitations.asciidoc index a438c4f72c..1817d62dff 100644 --- a/docs/en/observability/apm/otel-limitations.asciidoc +++ b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-limitations.asciidoc @@ -1,9 +1,9 @@ [[apm-open-telemetry-known-limitations]] -=== Limitations += Limitations [float] [[apm-open-telemetry-traces-limitations]] -==== OpenTelemetry traces +== OpenTelemetry traces * Traces of applications using `messaging` semantics might be wrongly displayed as `transactions` in the APM UI, while they should be considered `spans` (see issue https://github.com/elastic/apm-server/issues/7001[#7001]). * Inability to see Stack traces in spans. @@ -11,21 +11,21 @@ [float] [[apm-open-telemetry-logs-intake]] -==== OpenTelemetry logs +== OpenTelemetry logs * preview:[] The OpenTelemetry logs intake via APM Server is in technical preview. * The application logs data stream (`app_logs`) has dynamic mapping disabled. This means the automatic detection and mapping of new fields is disabled (see issue https://github.com/elastic/apm-server/issues/9093[#9093]). [float] [[apm-open-telemetry-otlp-limitations]] -==== OpenTelemetry Line Protocol (OTLP) +== OpenTelemetry Line Protocol (OTLP) APM Server supports both the https://opentelemetry.io/docs/specs/otlp/#otlpgrpc[OTLP/gRPC] and https://opentelemetry.io/docs/specs/otlp/#otlphttp[OTLP/HTTP] protocol with ProtoBuf payload. APM Server does not yet support JSON Encoding for OTLP/HTTP. [float] [[apm-open-telemetry-collector-exporter]] -==== OpenTelemetry Collector exporter for Elastic +== OpenTelemetry Collector exporter for Elastic The https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.57.2/exporter/elasticexporter[OpenTelemetry Collector exporter for Elastic] has been deprecated and replaced by the native support of the OpenTelemetry Line Protocol in Elastic Observability (OTLP). @@ -36,7 +36,7 @@ The https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/ [float] [[apm-open-telemetry-tbs]] -==== OpenTelemetry's tail-based sampling +== OpenTelemetry's tail-based sampling Tail-based sampling allows to make sampling decisions after all spans of a trace have been completed. This allows for more powerful and informed sampling rules. diff --git a/docs/en/observability/apm/otel-metrics.asciidoc b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-metrics.asciidoc similarity index 96% rename from docs/en/observability/apm/otel-metrics.asciidoc rename to docs/en/observability/apm/collect-application-data/open-telemetry/otel-metrics.asciidoc index 4ffcf30256..bff834fd90 100644 --- a/docs/en/observability/apm/otel-metrics.asciidoc +++ b/docs/en/observability/apm/collect-application-data/open-telemetry/otel-metrics.asciidoc @@ -1,5 +1,5 @@ [[apm-open-telemetry-collect-metrics]] -=== Collect metrics += Collect metrics IMPORTANT: When collecting metrics, please note that the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/metrics/DoubleValueRecorder.html[`DoubleValueRecorder`] and https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/metrics/LongValueObserver.html[`LongValueRecorder`] metrics are not yet supported. @@ -26,7 +26,7 @@ for more information. [float] [[apm-open-telemetry-verify-metrics]] -==== Verify OpenTelemetry metrics data +== Verify OpenTelemetry metrics data Use *Discover* to validate that metrics are successfully reported to {kib}. @@ -44,7 +44,7 @@ only OpenTelemetry metrics documents. [float] [[apm-open-telemetry-visualize]] -==== Visualize in {kib} +== Visualize in {kib} Use *Lens* to create visualizations for OpenTelemetry metrics. Lens enables you to build visualizations by dragging and dropping data fields. It makes smart visualization suggestions for your data, allowing you to switch between visualization types. diff --git a/docs/en/observability/apm/common-problems.asciidoc b/docs/en/observability/apm/common-problems.asciidoc deleted file mode 100644 index 3df7179c2b..0000000000 --- a/docs/en/observability/apm/common-problems.asciidoc +++ /dev/null @@ -1,200 +0,0 @@ -[[apm-common-problems]] -=== Common problems - -This section describes common problems you might encounter when using a Fleet-managed APM Server. - -* <> -* <> -* <> -* <> -* <> -* <> - -[float] -[[apm-no-data-indexed]] -=== No data is indexed - -If no data shows up in {es}, first make sure that your APM components are properly connected. - -include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/no-data-indexed-widget.asciidoc[] - -[[apm-data-indexed-no-apm]] -[float] -=== Data is indexed but doesn't appear in the APM UI - -The APM UI relies on index mappings to query and display data. -If your APM data isn't showing up in the APM UI, but is elsewhere in {kib}, like the Discover app, -you may have a missing index mapping. - -You can determine if a field was mapped correctly with the `_mapping` API. -For example, run the following command in the {kib} {kibana-ref}/console-kibana.html[console]. -This will display the field data type of the `service.name` field. - -[source,curl] ----- -GET *apm*/_mapping/field/service.name ----- - -If the `mapping.name.type` is `"text"`, your APM indices were not set up correctly. - -[source,yml] ----- -".ds-metrics-apm.transaction.1m-default-2023.04.12-000038": { - "mappings": { - "service.name": { - "full_name": "service.name", - "mapping": { - "name": { - "type": "text" <1> - } - } - } - } -} ----- -<1> The `service.name` `mapping.name.type` would be `"keyword"` if this field had been set up correctly. - -To fix this problem, install the APM integration by following these steps: - --- -include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm-server.asciidoc[tag=install-apm-integration] --- - -This will reinstall the APM index templates and trigger a data stream index rollover. - -You can verify the correct index templates were installed by running the following command in the {kib} console: - -[source,curl] ----- -GET /_index_template/traces-apm ----- - -[float] -[[apm-common-ssl-problems]] -=== Common SSL-related problems - -* <> -* <> -* <> -* <> -* <> - - -[float] -[[apm-ssl-client-fails]] -==== SSL client fails to connect - -The target host might be unreachable or the certificate may not be valid. -To fix this problem: - -. Make sure that the APM Server process on the target host is running and you can connect to it. -Try to ping the target host to verify that you can reach it from the host running APM Server. -Then use either `nc` or `telnet` to make sure that the port is available. For example: -+ -[source,shell] ----- -ping -telnet 5044 ----- - -. Verify that the certificate is valid and that the hostname and IP match. -. Use OpenSSL to test connectivity to the target server and diagnose problems. -See the https://www.openssl.org/docs/manmaster/man1/openssl-s_client.html[OpenSSL documentation] for more info. - -[float] -[[apm-cannot-validate-certificate]] -==== x509: cannot validate certificate for because it doesn't contain any IP SANs - -This happens because your certificate is only valid for the hostname present in the Subject field. -To resolve this problem, try one of these solutions: - -* Create a DNS entry for the hostname, mapping it to the server's IP. -* Create an entry in `/etc/hosts` for the hostname. Or, on Windows, add an entry to -`C:\Windows\System32\drivers\etc\hosts`. -* Re-create the server certificate and add a Subject Alternative Name (SAN) for the IP address of the server. This makes the -server's certificate valid for both the hostname and the IP address. - -[float] -[[apm-getsockopt-no-route-to-host]] -==== getsockopt: no route to host - -This is not an SSL problem. It's a networking problem. Make sure the two hosts can communicate. - -[float] -[[apm-getsockopt-connection-refused]] -==== getsockopt: connection refused - -This is not an SSL problem. Make sure that {ls} is running and that there is no firewall blocking the traffic. - -[float] -[[apm-target-machine-refused-connection]] -==== No connection could be made because the target machine actively refused it - -A firewall is refusing the connection. Check if a firewall is blocking the traffic on the client, the network, or the -destination host. - -[[apm-io-timeout]] -[float] -=== I/O Timeout - -I/O Timeouts can occur when your timeout settings across the stack are not configured correctly, -especially when using a load balancer. - -You may see an error like the one below in the {apm-agent} logs, and/or a similar error on the APM Server side: - -[source,logs] ----- -[ElasticAPM] APM Server responded with an error: -"read tcp 123.34.22.313:8200->123.34.22.40:41602: i/o timeout" ----- - -To fix this, ensure timeouts are incrementing from the {apm-agent}, -through your load balancer, to the APM Server. - -By default, the agent timeouts are set at 10 seconds, and the server timeout is set at 3600 seconds. -Your load balancer should be set somewhere between these numbers. - -For example: - -[source,txt] ----- -APM agent --> Load Balancer --> APM Server - 10s 15s 3600s ----- - -The APM Server timeout can be configured by updating the -<>. - -[[apm-field-limit-exceeded]] -[float] -=== Field limit exceeded - -When adding too many distinct tag keys on a transaction or span, -you risk creating a link:{ref}/mapping.html#mapping-limit-settings[mapping explosion]. - -For example, you should avoid that user-specified data, -like URL parameters, is used as a tag key. -Likewise, using the current timestamp or a user ID as a tag key is not a good idea. -However, tag *values* with a high cardinality are not a problem. -Just try to keep the number of distinct tag keys at a minimum. - -The symptom of a mapping explosion is that transactions and spans are not indexed anymore after a certain time. Usually, on the next day, -the spans and transactions will be indexed again because a new index is created each day. -But as soon as the field limit is reached, indexing stops again. - -In the agent logs, you won't see a sign of failures as the APM server asynchronously sends the data it received from the agents to {es}. However, the APM server and {es} log a warning like this: - -[source,logs] ----- -{\"type\":\"illegal_argument_exception\",\"reason\":\"Limit of total fields [1000] in [INDEX_NAME] has been exceeded\"} ----- - -[[apm-tail-based-sampling-memory-disk-io]] -[float] -=== Tail-based sampling causing high system memory usage and high disk IO - -Tail-based sampling requires minimal memory to run, and there should not be a noticeable increase in RSS memory usage. -However, since tail-based sampling writes data to disk, -it is possible to see a significant increase in OS page cache memory usage due to disk IO. -If you see a drop in throughput and excessive disk activity after enabling tail-based sampling, -please ensure that there is enough memory headroom in the system for OS page cache to perform disk IO efficiently. diff --git a/docs/en/observability/apm/command-reference.asciidoc b/docs/en/observability/apm/configure/advanced-setup/command-reference.asciidoc similarity index 98% rename from docs/en/observability/apm/command-reference.asciidoc rename to docs/en/observability/apm/configure/advanced-setup/command-reference.asciidoc index 45e65e570d..d95b0c0f6a 100644 --- a/docs/en/observability/apm/command-reference.asciidoc +++ b/docs/en/observability/apm/configure/advanced-setup/command-reference.asciidoc @@ -26,7 +26,7 @@ endif::serverless[] // end::attributes[] [[apm-command-line-options]] -=== APM Server command reference += APM Server command reference ++++ Command reference @@ -74,7 +74,7 @@ Also see <>. [float] [[apm-apikey-command]] -==== `apikey` command +== `apikey` command experimental::[] @@ -172,7 +172,7 @@ For more information, see <>. [float] [[apm-export-command]] -==== `export` command +== `export` command ifndef::serverless[] {export-command-short-desc}. You can use this @@ -258,7 +258,7 @@ endif::serverless[] [float] [[apm-help-command]] -==== `help` command +== `help` command {help-command-short-desc}. ifndef::serverless[] @@ -291,7 +291,7 @@ apm-server help export ifndef::serverless[] [float] [[apm-keystore-command]] -==== `keystore` command +== `keystore` command {keystore-command-short-desc}. @@ -350,7 +350,7 @@ endif::[] ifndef::serverless[] [float] [[apm-run-command]] -==== `run` command +== `run` command {run-command-short-desc}. @@ -409,7 +409,7 @@ endif::[] [float] [[apm-test-command]] -==== `test` command +== `test` command {test-command-short-desc}. @@ -444,7 +444,7 @@ apm-server test config [float] [[apm-version-command]] -==== `version` command +== `version` command {version-command-short-desc}. @@ -472,7 +472,7 @@ apm-server version [float] [[apm-global-flags]] -=== Global flags +== Global flags These global flags are available whenever you run APM Server. diff --git a/docs/en/observability/apm/data-ingestion.asciidoc b/docs/en/observability/apm/configure/advanced-setup/data-ingestion.asciidoc similarity index 93% rename from docs/en/observability/apm/data-ingestion.asciidoc rename to docs/en/observability/apm/configure/advanced-setup/data-ingestion.asciidoc index 13c825a97d..d4e6373cc0 100644 --- a/docs/en/observability/apm/data-ingestion.asciidoc +++ b/docs/en/observability/apm/configure/advanced-setup/data-ingestion.asciidoc @@ -1,11 +1,11 @@ [[apm-tune-data-ingestion]] -=== Tune data ingestion += Tune data ingestion This section explains how to adapt data ingestion according to your needs. [float] [[apm-tune-apm-server]] -=== Tune APM Server +== Tune APM Server * <> * <> @@ -13,7 +13,7 @@ This section explains how to adapt data ingestion according to your needs. [[apm-add-apm-server-instances]] [float] -==== Add APM Server or {agent} instances +=== Add APM Server or {agent} instances If the APM Server cannot process data quickly enough, you will see request timeouts. @@ -25,7 +25,7 @@ Having several instances will also increase <Advanced setup +++++ + +Before reading this section, see the <> +for basic installation and running instructions. + +This section includes additional information on how to set up and run APM Server, including: + +* <> +* <> +* <> +* <> +* <> +* <> + +:leveloffset: +1 + +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/shared-directory-layout.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/keystore.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/command-reference.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/data-ingestion.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/high-availability.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/shared-systemd.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm/keystore.asciidoc b/docs/en/observability/apm/configure/advanced-setup/keystore.asciidoc similarity index 96% rename from docs/en/observability/apm/keystore.asciidoc rename to docs/en/observability/apm/configure/advanced-setup/keystore.asciidoc index 39183ab3a3..3e330f8e16 100644 --- a/docs/en/observability/apm/keystore.asciidoc +++ b/docs/en/observability/apm/configure/advanced-setup/keystore.asciidoc @@ -1,5 +1,5 @@ [[apm-keystore]] -=== Secrets keystore for secure settings += Secrets keystore for secure settings ++++ Secrets keystore @@ -45,7 +45,7 @@ APM Server. [discrete] [[apm-creating-keystore]] -=== Create a keystore +== Create a keystore To create a secrets keystore, use: @@ -59,7 +59,7 @@ configuration setting. [discrete] [[apm-add-keys-to-keystore]] -=== Add keys +== Add keys To store sensitive values, such as authentication credentials for {es}, use the `keystore add` command: @@ -88,7 +88,7 @@ cat /file/containing/setting/value | apm-server keystore add ES_PWD --stdin --fo [discrete] [[apm-list-settings]] -=== List keys +== List keys To list the keys defined in the keystore, use: @@ -99,7 +99,7 @@ apm-server keystore list [discrete] [[apm-remove-settings]] -=== Remove keys +== Remove keys To remove a key from the keystore, use: diff --git a/docs/en/observability/apm/shared-directory-layout.asciidoc b/docs/en/observability/apm/configure/advanced-setup/shared-directory-layout.asciidoc similarity index 95% rename from docs/en/observability/apm/shared-directory-layout.asciidoc rename to docs/en/observability/apm/configure/advanced-setup/shared-directory-layout.asciidoc index f9837466cc..49f1f765fd 100644 --- a/docs/en/observability/apm/shared-directory-layout.asciidoc +++ b/docs/en/observability/apm/configure/advanced-setup/shared-directory-layout.asciidoc @@ -10,12 +10,12 @@ ////////////////////////////////////////////////////////////////////////// [[apm-directory-layout]] -=== Installation layout += Installation layout View the installation layout and default paths for both Fleet-managed APM Server and the APM Server binary. [float] -=== Fleet-managed +== Fleet-managed {agent} files are installed in the following locations. You cannot override these installation paths because they are required for upgrades. @@ -25,7 +25,7 @@ include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/install-layout -- [float] -=== APM Server binary +== APM Server binary APM Server uses the following default paths unless you explicitly change them. diff --git a/docs/en/observability/apm/shared-systemd.asciidoc b/docs/en/observability/apm/configure/advanced-setup/shared-systemd.asciidoc similarity index 96% rename from docs/en/observability/apm/shared-systemd.asciidoc rename to docs/en/observability/apm/configure/advanced-setup/shared-systemd.asciidoc index 6db6d33565..dcad0c74c6 100644 --- a/docs/en/observability/apm/shared-systemd.asciidoc +++ b/docs/en/observability/apm/configure/advanced-setup/shared-systemd.asciidoc @@ -1,5 +1,5 @@ [[apm-running-with-systemd]] -=== APM Server and systemd += APM Server and systemd IMPORTANT: These commands only apply to the APM Server binary installation method. Fleet-managed users should see {fleet-guide}/start-stop-elastic-agent.html[Start and stop {agent}s on edge hosts]. @@ -12,7 +12,7 @@ We recommend that the apm-server process is run as a non-root user. Therefore, that is the default setup for APM Server's DEB package and RPM installation. [float] -==== Start and stop APM Server +== Start and stop APM Server Use `systemctl` to start or stop APM Server: @@ -40,7 +40,7 @@ sudo systemctl disable apm-server ------------------------------------------------ [float] -==== APM Server status and logs +== APM Server status and logs To get the service status, use `systemctl`: @@ -57,7 +57,7 @@ journalctl -u apm-server.service ------------------------------------------------ [float] -=== Customize systemd unit for APM Server +== Customize systemd unit for APM Server The systemd service unit file includes environment variables that you can override to change the default options. diff --git a/docs/en/observability/apm/configure/agent-config.asciidoc b/docs/en/observability/apm/configure/agent-config.asciidoc index 50b6c7eb6e..40abb459f2 100644 --- a/docs/en/observability/apm/configure/agent-config.asciidoc +++ b/docs/en/observability/apm/configure/agent-config.asciidoc @@ -25,7 +25,7 @@ apm-server.agent.config.elasticsearch.api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSo ---- [float] -= APM agent configuration options +== APM agent configuration options The following options are only supported for APM Server binary users. You can specify these options in the `apm-server.agent.config` section of the @@ -33,14 +33,14 @@ You can specify these options in the `apm-server.agent.config` section of the [float] [[apm-agent-config-cache]] -== `apm-server.agent.config.cache.expiration` +=== `apm-server.agent.config.cache.expiration` When using APM agent configuration, information fetched from {es} will be cached in memory for some time. Specify the cache expiration time via this setting. Defaults to `30s` (30 seconds). [float] [[apm-agent-config-elasticsearch]] -== `apm-server.agent.config.elasticsearch` +=== `apm-server.agent.config.elasticsearch` Takes the same options as <>. @@ -50,7 +50,7 @@ configuration. If `output.elasticsearch` isn't set or doesn't have sufficient pr use these {es} options to provide {es} access. [float] -== Common problems +=== Common problems You may see either of the following HTTP 403 errors from APM Server when it attempts to fetch APM agent configuration: diff --git a/docs/en/observability/apm/configure/anonymous-auth.asciidoc b/docs/en/observability/apm/configure/anonymous-auth.asciidoc index 16695d34b3..3068eb5a8a 100644 --- a/docs/en/observability/apm/configure/anonymous-auth.asciidoc +++ b/docs/en/observability/apm/configure/anonymous-auth.asciidoc @@ -28,7 +28,7 @@ IMPORTANT: All anonymous access configuration is ignored if [float] [[apm-config-auth-anon-rum]] -= Real User Monitoring (RUM) +== Real User Monitoring (RUM) If an <> or <> is configured, then anonymous authentication must be enabled to collect RUM data. @@ -39,7 +39,7 @@ See <> for additional RUM configuration options. [float] [[apm-config-auth-anon-mitigating]] -== Mitigating malicious requests +=== Mitigating malicious requests There are a few configuration variables that can mitigate the impact of malicious requests to an unauthenticated APM Server endpoint. @@ -53,7 +53,7 @@ This allows you to specify the maximum number of requests allowed per unique IP [float] [[apm-config-auth-anon-client-ip]] -== Deriving an incoming request's `client.ip` address +=== Deriving an incoming request's `client.ip` address The remote IP address of an incoming request might be different from the end-user's actual IP address, for example, because of a proxy. For this reason, @@ -68,7 +68,7 @@ If none of these headers are present, the remote address for the incoming reques [float] [[apm-config-auth-anon-client-ip-concerns]] -== Using a reverse proxy or load balancer +=== Using a reverse proxy or load balancer HTTP headers are easily modified; it's possible for anyone to spoof the derived `client.ip` value by changing or setting, @@ -83,11 +83,11 @@ APM Server's rate limiting feature. [float] [[apm-config-auth-anon]] -= Configuration reference +== Configuration reference [float] [[apm-config-auth-anon-enabled]] -== Anonymous Agent access +=== Anonymous Agent access Enable or disable anonymous authentication. Default: `false` (disabled). (bool) @@ -99,7 +99,7 @@ Default: `false` (disabled). (bool) [float] [[apm-config-auth-anon-allow-agent]] -== Allowed anonymous agents +=== Allowed anonymous agents A list of permitted {apm-agent} names for anonymous authentication. Names in this list must match the agent's `agent.name`. Default: `[rum-js, js-base]` (only RUM agent events are accepted). (array) @@ -124,7 +124,7 @@ Default: Not set (any service name is accepted). (array) [float] [[apm-config-auth-anon-ip-limit]] -== IP limit +=== IP limit The number of unique IP addresses to track in an LRU cache. IP addresses in the cache will be rate limited according to the <> setting. Consider increasing this default if your application has many concurrent clients. @@ -137,7 +137,7 @@ Default: `1000`. (int) [float] [[apm-config-auth-anon-event-limit]] -== Event limit +=== Event limit The maximum number of events allowed per second, per agent IP address. Default: `300`. (int) diff --git a/docs/en/observability/apm/configure/auth.asciidoc b/docs/en/observability/apm/configure/auth.asciidoc index f04958beee..d8c02bd988 100644 --- a/docs/en/observability/apm/configure/auth.asciidoc +++ b/docs/en/observability/apm/configure/auth.asciidoc @@ -13,14 +13,14 @@ include::./tab-widgets/auth-config-widget.asciidoc[] [float] [[apm-api-key-auth-settings]] -= API key authentication options +== API key authentication options These settings apply to API key communication between the APM Server and APM Agents. NOTE: These settings are different from the API key settings used for {es} output and monitoring. [float] -== API key for agent authentication +=== API key for agent authentication Enable API key authorization by setting `enabled` to `true`. By default, `enabled` is set to `false`, and API key support is disabled. (bool) @@ -35,7 +35,7 @@ When enabled, third-party APM agents must include a valid API key in the followi `Authorization: ApiKey `. The key must be the base64 encoded representation of the API key's `id:name`. [float] -== API key limit +=== API key limit Each unique API key triggers one request to {es}. This setting restricts the number of unique API keys are allowed per minute. @@ -48,7 +48,7 @@ The default `limit` is `100`. (int) |==== [float] -== Secret token +=== Secret token Authorization token for sending APM data. The same token must also be set in each {apm-agent}. @@ -60,7 +60,7 @@ This token is not used for RUM endpoints. (text) |==== [float] -= `auth.api_key.elasticsearch.*` configuration options +== `auth.api_key.elasticsearch.*` configuration options **** image:./binary-yes-fm-no.svg[supported deployment methods] @@ -72,51 +72,51 @@ If none are set, configuration settings from the `apm-server.output` section wil **** [float] -== `elasticsearch.hosts` +=== `elasticsearch.hosts` API keys are fetched from {es}. This configuration needs to point to a secured {es} cluster that is able to serve API key requests. [float] -== `elasticsearch.protocol` +=== `elasticsearch.protocol` The name of the protocol {es} is reachable on. The options are: `http` or `https`. The default is `http`. If nothing is configured, configuration settings from the `output` section will be reused. [float] -== `elasticsearch.path` +=== `elasticsearch.path` An optional HTTP path prefix that is prepended to the HTTP API calls. If nothing is configured, configuration settings from the `output` section will be reused. [float] -== `elasticsearch.proxy_url` +=== `elasticsearch.proxy_url` The URL of the proxy to use when connecting to the {es} servers. The value may be either a complete URL or a "host[:port]", in which case the "http"scheme is assumed. If nothing is configured, configuration settings from the `output` section will be reused. [float] -== `elasticsearch.timeout` +=== `elasticsearch.timeout` The HTTP request timeout in seconds for the {es} request. If nothing is configured, configuration settings from the `output` section will be reused. [float] -= `auth.api_key.elasticsearch.ssl.*` configuration options +== `auth.api_key.elasticsearch.ssl.*` configuration options SSL is off by default. Set `elasticsearch.protocol` to `https` if you want to enable `https`. [float] -== `elasticsearch.ssl.enabled` +=== `elasticsearch.ssl.enabled` Enable custom SSL settings. Set to false to ignore custom SSL settings for secure communication. [float] -== `elasticsearch.ssl.verification_mode` +=== `elasticsearch.ssl.verification_mode` Configure SSL verification mode. If `none` is configured, all server hosts and certificates will be accepted. @@ -124,45 +124,45 @@ In this mode, SSL based connections are susceptible to man-in-the-middle attacks **Use only for testing**. Default is `full`. [float] -== `elasticsearch.ssl.supported_protocols` +=== `elasticsearch.ssl.supported_protocols` List of supported/valid TLS versions. By default, all TLS versions from 1.0 to 1.2 are enabled. [float] -== `elasticsearch.ssl.certificate_authorities` +=== `elasticsearch.ssl.certificate_authorities` List of root certificates for HTTPS server verifications. [float] -== `elasticsearch.ssl.certificate` +=== `elasticsearch.ssl.certificate` The path to the certificate for SSL client authentication. [float] -== `elasticsearch.ssl.key` +=== `elasticsearch.ssl.key` The client certificate key used for client authentication. This option is required if certificate is specified. [float] -== `elasticsearch.ssl.key_passphrase` +=== `elasticsearch.ssl.key_passphrase` An optional passphrase used to decrypt an encrypted key stored in the configured key file. [float] -== `elasticsearch.ssl.cipher_suites` +=== `elasticsearch.ssl.cipher_suites` The list of cipher suites to use. The first entry has the highest priority. If this option is omitted, the Go crypto library’s default suites are used (recommended). [float] -== `elasticsearch.ssl.curve_types` +=== `elasticsearch.ssl.curve_types` The list of curve types for ECDHE (Elliptic Curve Diffie-Hellman ephemeral key exchange). [float] -== `elasticsearch.ssl.renegotiation` +=== `elasticsearch.ssl.renegotiation` Configure what types of renegotiation are supported. Valid options are `never`, `once`, and `freely`. Default is `never`. diff --git a/docs/en/observability/apm/configure/general.asciidoc b/docs/en/observability/apm/configure/general.asciidoc index decdc577e8..16d889230a 100644 --- a/docs/en/observability/apm/configure/general.asciidoc +++ b/docs/en/observability/apm/configure/general.asciidoc @@ -13,11 +13,11 @@ include::./tab-widgets/general-config-widget.asciidoc[] [float] [[apm-configuration-apm-server]] -= Configuration options +== Configuration options [[apm-host]] [float] -== Host +=== Host Defines the host and port the server is listening on. Use `"unix:/path/to.sock"` to listen on a Unix domain socket. Defaults to 'localhost:8200'. (text) @@ -28,7 +28,7 @@ Defaults to 'localhost:8200'. (text) |==== [float] -== URL +=== URL The publicly reachable server URL. For deployments on Elastic Cloud or ECK, the default is unchangeable. |==== @@ -38,7 +38,7 @@ The publicly reachable server URL. For deployments on Elastic Cloud or ECK, the [[apm-max_header_size]] [float] -== Max header size +=== Max header size Maximum permitted size of a request's header accepted by the server to be processed (in Bytes). Defaults to 1048576 Bytes (1 MB). (int) @@ -49,7 +49,7 @@ Defaults to 1048576 Bytes (1 MB). (int) [[apm-idle_timeout]] [float] -== Idle timeout +=== Idle timeout Maximum amount of time to wait for the next incoming request before underlying connection is closed. Defaults to `45s` (45 seconds). (text) @@ -60,7 +60,7 @@ Defaults to `45s` (45 seconds). (text) [[apm-read_timeout]] [float] -== Read timeout +=== Read timeout Maximum permitted duration for reading an entire request. Defaults to `3600s` (3600 seconds). (text) @@ -71,7 +71,7 @@ Defaults to `3600s` (3600 seconds). (text) [[apm-write_timeout]] [float] -== Write timeout +=== Write timeout Maximum permitted duration for writing a response. Defaults to `30s` (30 seconds). (text) @@ -82,7 +82,7 @@ Defaults to `30s` (30 seconds). (text) [[apm-shutdown_timeout]] [float] -=== Shutdown timeout +==== Shutdown timeout Maximum duration in seconds before releasing resources when shutting down the server. Defaults to `30s` (30 seconds). (text) @@ -93,7 +93,7 @@ Defaults to `30s` (30 seconds). (text) [[apm-max_event_size]] [float] -== Max event size +=== Max event size Maximum permitted size of an event accepted by the server to be processed (in Bytes). Defaults to `307200` Bytes. (int) @@ -104,7 +104,7 @@ Defaults to `307200` Bytes. (int) [[apm-max_connections]] [float] -== Max connections +=== Max connections Maximum number of TCP connections to accept simultaneously. Default value is 0, which means _unlimited_. (int) @@ -115,7 +115,7 @@ Default value is 0, which means _unlimited_. (int) [[apm-custom_http_headers]] [float] -== Custom HTTP response headers +=== Custom HTTP response headers Custom HTTP headers to add to HTTP responses. Useful for security policy compliance. (text) |==== @@ -125,7 +125,7 @@ Custom HTTP headers to add to HTTP responses. Useful for security policy complia [[apm-capture_personal_data]] [float] -== Capture personal data +=== Capture personal data If true, APM Server captures the IP of the instrumented service and its User Agent if any. Enabled by default. (bool) @@ -138,7 +138,7 @@ Enabled by default. (bool) [[apm-default_service_environment]] [float] -== Default service environment +=== Default service environment Sets the default service environment to associate with data and requests received from agents which have no service environment defined. Default: none. (text) |==== @@ -148,7 +148,7 @@ Sets the default service environment to associate with data and requests receive [[apm-expvar.enabled]] [float] -== expvar support +=== expvar support When set to true APM Server exposes https://golang.org/pkg/expvar/[golang expvar] under `/debug/vars`. Disabled by default. @@ -159,7 +159,7 @@ Disabled by default. [[apm-expvar.url]] [float] -== expvar URL +=== expvar URL Configure the URL to expose expvar. Defaults to `debug/vars`. @@ -170,7 +170,7 @@ Defaults to `debug/vars`. [[apm-data_streams.namespace]] [float] -== Data stream namespace +=== Data stream namespace Change the default namespace. This setting changes the name of the integration's data stream. diff --git a/docs/en/observability/apm/configure/index.asciidoc b/docs/en/observability/apm/configure/index.asciidoc index c4d2722f8e..df3fe704a5 100644 --- a/docs/en/observability/apm/configure/index.asciidoc +++ b/docs/en/observability/apm/configure/index.asciidoc @@ -1,5 +1,5 @@ [[apm-configuring-howto-apm-server]] -= Configure += Configure APM Server How you configure the APM Server depends on your deployment method. @@ -49,4 +49,6 @@ include::tls.asciidoc[leveloffset=+1] include::sampling.asciidoc[leveloffset=+1] -include::env.asciidoc[leveloffset=+1] \ No newline at end of file +include::env.asciidoc[leveloffset=+1] + +include::advanced-setup/index.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/configure/rum.asciidoc b/docs/en/observability/apm/configure/rum.asciidoc index 0156fb0c4b..5dbab0cb8e 100644 --- a/docs/en/observability/apm/configure/rum.asciidoc +++ b/docs/en/observability/apm/configure/rum.asciidoc @@ -23,11 +23,11 @@ you will need to configure {apm-rum-ref-v}/configuring-cors.html[Cross-Origin Re [float] [[apm-enable-rum-support]] -= Configuration reference +== Configuration reference [[apm-rum-enable]] [float] -== Enable RUM +=== Enable RUM To enable RUM support, set to `true`. By default this is disabled. (bool) @@ -45,7 +45,7 @@ Anonymous authentication is required as the RUM agent runs in the browser. [float] [[apm-rum-allow-origins]] -== Allowed Origins +=== Allowed Origins A list of permitted origins for RUM support. User-agents send an Origin header that will be validated against this list. This is done automatically by modern browsers as part of the https://www.w3.org/TR/cors/[CORS specification]. @@ -60,7 +60,7 @@ Default: `['*']` (allows everything). (text) [float] [[apm-rum-allow-headers]] -== Access-Control-Allow-Headers +=== Access-Control-Allow-Headers HTTP requests made from the RUM agent to the APM Server are limited in the HTTP headers they are allowed to have. If any other headers are added, the request will be rejected by the browser due to Cross-Origin Resource Sharing (CORS) restrictions. Use this setting to allow additional headers. @@ -76,7 +76,7 @@ Default: `[]`. (text) [float] [[apm-rum-response-headers]] -== Custom HTTP response headers +=== Custom HTTP response headers Custom HTTP headers to add to RUM responses. This can be useful for security policy compliance. @@ -91,7 +91,7 @@ Default: none. (text) [float] [[apm-rum-library-pattern]] -== Library Frame Pattern +=== Library Frame Pattern RegExp to be matched against a stack trace frame's `file_name` and `abs_path` attributes. If the RegExp matches, the stack trace frame is considered to be a library frame. When source mapping is applied, the `error.culprit` is set to reflect the _function_ and the _filename_ @@ -106,7 +106,7 @@ Default: `"node_modules|bower_components|~"`. (text) |==== [float] -== Exclude from grouping +=== Exclude from grouping RegExp to be matched against a stack trace frame's `file_name`. If the RegExp matches, the stack trace frame is excluded from being used for calculating error groups. @@ -120,7 +120,7 @@ Default: `"^/webpack"` (excludes stack trace frames that have a filename startin [float] [[apm-rum-source-map]] -= Source map configuration options +== Source map configuration options **** image:./binary-yes-fm-no.svg[supported deployment methods] @@ -131,7 +131,7 @@ the options in this section are only supported by the APM Server binary. [[apm-config-sourcemapping-enabled]] [float] -== `source_mapping.enabled` +=== `source_mapping.enabled` Used to enable/disable <> for RUM events. When enabled, the APM Server needs additional privileges to read source maps. See <> for more details. @@ -140,14 +140,14 @@ Default: `true` [[apm-config-sourcemapping-elasticsearch]] [float] -== `source_mapping.elasticsearch` +=== `source_mapping.elasticsearch` Configure the {es} source map retrieval location, taking the same options as <>. This must be set when using an output other than {es}, and that output is writing to {es}. Otherwise leave this section empty. [[apm-rum-sourcemap-cache]] [float] -== `source_mapping.cache.expiration` +=== `source_mapping.cache.expiration` If a source map has been uploaded to the APM Server, <> is automatically applied to documents sent to the RUM endpoint. Source maps are fetched from {es} and then kept in an in-memory cache for the configured time. @@ -156,7 +156,7 @@ Values configured without a time unit are treated as seconds. Default: `5m` (5 minutes) [float] -== `source_mapping.index_pattern` +=== `source_mapping.index_pattern` Previous versions of APM Server stored source maps in `apm-%{[observer.version]}-sourcemap` indices. Search source maps stored in an older version with this setting. @@ -164,11 +164,11 @@ Default: `"apm-*-sourcemap*"` [float] [[apm-rum-deprecated]] -= Deprecated configuration options +== Deprecated configuration options [float] [[apm-event_rate.limit]] -== `event_rate.limit` +=== `event_rate.limit` deprecated::[7.15.0, Replaced by <>.] @@ -177,7 +177,7 @@ The maximum number of events allowed per second, per agent IP address. Default: `300` [float] -== `event_rate.lru_size` +=== `event_rate.lru_size` deprecated::[7.15.0, Replaced by <>.] @@ -189,7 +189,7 @@ Default: `1000` [float] [[apm-rum-allow-service-names]] -== `allow_service_names` +=== `allow_service_names` deprecated::[7.15.0, Replaced by <>.] A list of permitted service names for RUM support. @@ -200,7 +200,7 @@ in order to limit the number of service-specific indices or data streams created Default: Not set (any service name is accepted) [float] -= Ingest pipelines +== Ingest pipelines The default APM Server pipeline includes processors that enrich RUM data prior to indexing in {es}. See <> for details on how to locate, edit, or disable this preprocessing. \ No newline at end of file diff --git a/docs/en/observability/apm/configure/sampling.asciidoc b/docs/en/observability/apm/configure/sampling.asciidoc index 7932ee17d0..cd31a3e079 100644 --- a/docs/en/observability/apm/configure/sampling.asciidoc +++ b/docs/en/observability/apm/configure/sampling.asciidoc @@ -13,7 +13,7 @@ include::./tab-widgets/sampling-config-widget.asciidoc[] [float] [[apm-configuration-tbs]] -= Top-level tail-based sampling settings +== Top-level tail-based sampling settings See <> to learn more. @@ -22,7 +22,7 @@ See <> to learn more. [float] [id="sampling-tail-enabled-{input-type}"] -== Enable tail-based sampling +=== Enable tail-based sampling Set to `true` to enable tail based sampling. Disabled by default. (bool) @@ -33,7 +33,7 @@ Disabled by default. (bool) [float] [id="sampling-tail-interval-{input-type}"] -== Interval +=== Interval Synchronization interval for multiple APM Servers. Should be in the order of tens of seconds or low minutes. Default: `1m` (1 minute). (duration) @@ -45,7 +45,7 @@ Default: `1m` (1 minute). (duration) [float] [id="sampling-tail-policies-{input-type}"] -== Policies +=== Policies Criteria used to match a root transaction to a sample rate. Policies map trace events to a sample rate. @@ -63,7 +63,7 @@ This final policy is used to catch remaining trace events that don't match a str [float] [id="sampling-tail-storage_limit-{input-type}"] -== Storage limit +=== Storage limit The amount of storage space allocated for trace events matching tail sampling policies. Caution: Setting this limit higher than the allowed space may cause APM Server to become unhealthy. If the configured storage limit is insufficient, it logs "configured storage limit reached". The event will bypass sampling and will always be indexed when storage limit is reached. @@ -79,7 +79,7 @@ Default: `3GB`. (text) [float] [[apm-configuration-tbs-policy]] -= Policy-level tail-based sampling settings +== Policy-level tail-based sampling settings See <> to learn more. @@ -87,9 +87,7 @@ See <> to learn more. [float] [id="sampling-tail-sample-rate-{input-type}"] -== Sample rate - -**`sample_rate`** +=== **`sample_rate`** The sample rate to apply to trace events matching this policy. Required in each policy. @@ -100,9 +98,7 @@ A `sample_rate` of `1` means that 100% of trace events matching the policy will [float] [id="sampling-tail-trace-name-{input-type}"] -== Trace name - -**`trace.name`** +=== **`trace.name`** The trace name for events to match a policy. A match occurs when the configured `trace.name` matches the `transaction.name` of the root transaction of a trace. @@ -110,9 +106,7 @@ A root transaction is any transaction without a `parent.id`. (string) [float] [id="sampling-tail-trace-outcome-{input-type}"] -== Trace outcome - -**`trace.outcome`** +=== **`trace.outcome`** The trace outcome for events to match a policy. A match occurs when the configured `trace.outcome` matches a trace's `event.outcome` field. @@ -120,17 +114,13 @@ Trace outcome can be `success`, `failure`, or `unknown`. (string) [float] [id="sampling-tail-service-name-{input-type}"] -== Service name - -**`service.name`** +=== **`service.name`** The service name for events to match a policy. (string) [float] [id="sampling-tail-service-environment-{input-type}"] -== Service Environment - -**`service.environment`** +=== **`service.environment`** The service environment for events to match a policy. (string) diff --git a/docs/en/observability/apm/data-model/data-model-errors.asciidoc b/docs/en/observability/apm/data-model/data-model-errors.asciidoc new file mode 100644 index 0000000000..2f2c749918 --- /dev/null +++ b/docs/en/observability/apm/data-model/data-model-errors.asciidoc @@ -0,0 +1,52 @@ +[[apm-data-model-errors]] += Errors + +An error event contains at least +information about the original `exception` that occurred +or about a `log` created when the exception occurred. +For simplicity, errors are represented by a unique ID. + +An Error contains: + +* Both the captured `exception` and the captured `log` of an error can contain a `stack trace`, +which is helpful for debugging. +* The `culprit` of an error indicates where it originated. +* An error might relate to the <> during which it happened, +via the `transaction.id`. +* Data about the environment in which the event is recorded: +** Service - environment, framework, language, etc. +** Host - architecture, hostname, IP, etc. +** Process - args, PID, PPID, etc. +** URL - full, domain, port, query, etc. +** <> - (if supplied) email, ID, username, etc. + +In addition, agents provide options for users to capture custom <>. +Metadata can be indexed - <>, or not-indexed - <>. + +TIP: Most agents limit keyword fields (e.g. `error.id`) to 1024 characters, +non-keyword fields (e.g. `error.exception.message`) to 10,000 characters. + +Errors are stored in error indices. + +[float] +== Data streams + +Errors are stored in the following data streams: + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=logs-data-streams] + +See <> to learn more. + +[float] +== Example error document + +This example shows what error documents can look like when indexed in {es}. + +[%collapsible] +.Expand {es} document +==== +[source,json] +---- +include::{apm-server-root}/docs/data/elasticsearch/generated/errors.json[] +---- +==== diff --git a/docs/en/observability/apm/data-model/data-model-metadata.asciidoc b/docs/en/observability/apm/data-model/data-model-metadata.asciidoc new file mode 100644 index 0000000000..fa6be2fc94 --- /dev/null +++ b/docs/en/observability/apm/data-model/data-model-metadata.asciidoc @@ -0,0 +1,99 @@ +[[apm-data-model-metadata]] += Metadata + +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. + +[float] +[[apm-data-model-labels]] +== Labels + +Labels add *indexed* information to transactions, spans, and errors. +Indexed means the data is searchable and aggregatable in {es}. +Add additional key-value pairs to define multiple labels. + +* Indexed: Yes +* {es} type: {ref}/object.html[object] +* {es} field: `labels` +* Applies to: <> | <> | <> + +Label values can be a string, boolean, or number, although some agents only support string values at this time. +Because labels for a given key, regardless of agent used, are stored in the same place in {es}, +all label values of a given key must have the same data type. +Multiple data types per key will throw an exception, for example: `{foo: bar}` and `{foo: 42}` is not allowed. + +IMPORTANT: Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +{ref}/mapping.html#mapping-limit-settings[mapping explosion]. + +[float] +=== Agent API reference + +* Go: {apm-go-ref-v}/api.html#context-set-label[`SetLabel`] +* Java: {apm-java-ref-v}/public-api.html#api-transaction-add-tag[`setLabel`] +* .NET: {apm-dotnet-ref-v}/public-api.html#api-transaction-set-label[`SetLabel`] +* Node.js: {apm-node-ref-v}/agent-api.html#apm-set-label[`setLabel`] | {apm-node-ref-v}/agent-api.html#apm-add-labels[`addLabels`] +* PHP: {apm-php-ref}/public-api.html#api-transaction-interface-set-label[`Transaction` `setLabel`] | {apm-php-ref}/public-api.html#api-span-interface-set-label[`Span` `setLabel`] +* Python: {apm-py-ref-v}/api.html#api-label[`elasticapm.label()`] +* Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-label[`set_label`] +* Rum: {apm-rum-ref-v}/agent-api.html#apm-add-labels[`addLabels`] + +[float] +[[apm-data-model-custom]] +== Custom context + +Custom context adds *non-indexed*, +custom contextual information to transactions and errors. +Non-indexed means the data is not searchable or aggregatable in {es}, +and you cannot build dashboards on top of the data. +This also means you don't have to worry about {ref}/mapping.html#mapping-limit-settings[mapping explosions], +as these fields are not added to the mapping. + +Non-indexed information is useful for providing contextual information to help you +quickly debug performance issues or errors. + +* Indexed: No +* {es} type: {ref}/object.html[object] +* {es} fields: `transaction.custom` | `error.custom` +* Applies to: <> | <> + +IMPORTANT: Setting a circular object, a large object, or a non JSON serializable object can lead to errors. + +[float] +=== Agent API reference + +* Go: {apm-go-ref-v}/api.html#context-set-custom[`SetCustom`] +* iOS: _coming soon_ +* Java: {apm-java-ref-v}/public-api.html#api-transaction-add-custom-context[`addCustomContext`] +* .NET: _coming soon_ +* Node.js: {apm-node-ref-v}/agent-api.html#apm-set-custom-context[`setCustomContext`] +* PHP: _coming soon_ +* Python: {apm-py-ref-v}/api.html#api-set-custom-context[`set_custom_context`] +* Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-custom-context[`set_custom_context`] +* Rum: {apm-rum-ref-v}/agent-api.html#apm-set-custom-context[`setCustomContext`] + +[float] +[[apm-data-model-user]] +== User context + +User context adds *indexed* user information to transactions and errors. +Indexed means the data is searchable and aggregatable in {es}. + +* Indexed: Yes +* {es} type: {ref}/keyword.html[keyword] +* {es} fields: `user.email` | `user.name` | `user.id` +* Applies to: <> | <> + +[float] +=== Agent API reference + +* Go: {apm-go-ref-v}/api.html#context-set-username[`SetUsername`] | {apm-go-ref-v}/api.html#context-set-user-id[`SetUserID`] | +{apm-go-ref-v}/api.html#context-set-user-email[`SetUserEmail`] +* iOS: _coming soon_ +* Java: {apm-java-ref-v}/public-api.html#api-transaction-set-user[`setUser`] +* .NET _coming soon_ +* Node.js: {apm-node-ref-v}/agent-api.html#apm-set-user-context[`setUserContext`] +* PHP: _coming soon_ +* Python: {apm-py-ref-v}/api.html#api-set-user-context[`set_user_context`] +* Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-user[`set_user`] +* Rum: {apm-rum-ref-v}/agent-api.html#apm-set-user-context[`setUserContext`] diff --git a/docs/en/observability/apm/data-model.asciidoc b/docs/en/observability/apm/data-model/data-model-metrics.asciidoc similarity index 54% rename from docs/en/observability/apm/data-model.asciidoc rename to docs/en/observability/apm/data-model/data-model-metrics.asciidoc index 60c0a69c07..9f2161c2e1 100644 --- a/docs/en/observability/apm/data-model.asciidoc +++ b/docs/en/observability/apm/data-model/data-model-metrics.asciidoc @@ -1,224 +1,5 @@ -:span-name-type-sheet: https://docs.google.com/spreadsheets/d/1SmWeX5AeqUcayrArUauS_CxGgsjwRgMYH4ZY8yQsMhQ/edit#gid=644582948 -:span-spec: https://github.com/elastic/apm/blob/main/tests/agents/json-specs/span_types.json - -[[apm-data-model]] -== Data Model - -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`. - -* <> -* <> -* <> -* <> - -Events can contain additional <> which further enriches your data. - -[[apm-data-model-spans]] -=== Spans - -*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. - -Agents automatically instrument a variety of libraries to capture these spans from within your application, -but you can also use the Agent API for custom instrumentation of specific code paths. - -Among other things, spans can contain: - -* A `transaction.id` attribute that refers to its parent <>. -* A `parent.id` attribute that refers to its parent span or transaction. -* Its start time and duration. -* A `name`, `type`, `subtype`, and `action`—see the {span-name-type-sheet}[span name/type alignment] -sheet for span name patterns and examples by {apm-agent}. -In addition, some APM agents test against a public {span-spec}[span type/subtype spec]. -* An optional `stack trace`. Stack traces consist of stack frames, -which represent a function call on the call stack. -They include attributes like function name, file name and path, line number, etc. - -TIP: Most agents limit keyword fields, like `span.id`, to 1024 characters, -and non-keyword fields, like `span.start.us`, to 10,000 characters. - -[float] -[[apm-data-model-dropped-spans]] -==== Dropped spans - -For performance reasons, APM agents can choose to sample or omit spans purposefully. -This can be useful in preventing edge cases, like long-running transactions with over 100 spans, -that would otherwise overload both the Agent and the APM Server. -When this occurs, the APM UI will display the number of spans dropped. - -To configure the number of spans recorded per transaction, see the relevant Agent documentation: - -* Android: _Not yet supported_ -* Go: {apm-go-ref-v}/configuration.html#config-transaction-max-spans[`ELASTIC_APM_TRANSACTION_MAX_SPANS`] -* iOS: _Not yet supported_ -* Java: {apm-java-ref-v}/config-core.html#config-transaction-max-spans[`transaction_max_spans`] -* .NET: {apm-dotnet-ref-v}/config-core.html#config-transaction-max-spans[`TransactionMaxSpans`] -* Node.js: {apm-node-ref-v}/configuration.html#transaction-max-spans[`transactionMaxSpans`] -* PHP: {apm-php-ref-v}/configuration-reference.html#config-transaction-max-spans[`transaction_max_spans`] -* Python: {apm-py-ref-v}/configuration.html#config-transaction-max-spans[`transaction_max_spans`] -* Ruby: {apm-ruby-ref-v}/configuration.html#config-transaction-max-spans[`transaction_max_spans`] - -[float] -[[apm-data-model-missing-spans]] -==== Missing spans - -Agents stream spans to the APM Server separately from their transactions. -Because of this, unforeseen errors may cause spans to go missing. -Agents know how many spans a transaction should have; -if the number of expected spans does not equal the number of spans received by the APM Server, -the APM UI will calculate the difference and display a message. - -[float] -==== Data streams - -Spans are stored with transactions in the following data streams: - -include::./data-streams.asciidoc[tag=traces-data-streams] - -See <> to learn more. - -[float] -==== Example span document - -This example shows what span documents can look like when indexed in {es}. - -[%collapsible] -.Expand {es} document -==== -[source,json] ----- -include::{apm-server-root}/docs/data/elasticsearch/generated/spans.json[] ----- -==== - -[[apm-data-model-transactions]] -=== Transactions - -*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. -As an example, a transaction might be a: - -* Request to your server -* Batch job -* Background job -* Custom transaction type - -Agents decide whether to sample transactions or not, -and provide settings to control sampling behavior. -If sampled, the <> of a transaction are sent and stored as separate documents. -Within one transaction there can be 0, 1, or many spans captured. - -A transaction contains: - -* The timestamp of the event -* A unique id, type, and name -* Data about the environment in which the event is recorded: -** Service - environment, framework, language, etc. -** Host - architecture, hostname, IP, etc. -** Process - args, PID, PPID, etc. -** URL - full, domain, port, query, etc. -** <> - (if supplied) email, ID, username, etc. -* Other relevant information depending on the agent. Example: The JavaScript RUM agent captures transaction marks, -which are points in time relative to the start of the transaction with some label. - -In addition, agents provide options for users to capture custom <>. -Metadata can be indexed - <>, or not-indexed - <>. - -Transactions are grouped by their `type` and `name` in the APM UI's -<>. -If you're using a supported framework, APM agents will automatically handle the naming for you. -If you're not, or if you wish to override the default, -all agents have API methods to manually set the `type` and `name`. - -* `type` should be a keyword of specific relevance in the service's domain, -e.g. `request`, `backgroundjob`, etc. -* `name` should be a generic designation of a transaction in the scope of a single service, -e.g. `GET /users/:id`, `UsersController#show`, etc. - -TIP: Most agents limit keyword fields (e.g. `labels`) to 1024 characters, -non-keyword fields (e.g. `span.db.statement`) to 10,000 characters. - -[float] -==== Data streams - -Transactions are stored with spans in the following data streams: - -include::./data-streams.asciidoc[tag=traces-data-streams] - -See <> to learn more. - -[float] -==== Example transaction document - -This example shows what transaction documents can look like when indexed in {es}. - -[%collapsible] -.Expand {es} document -==== -[source,json] ----- -include::{apm-server-root}/docs/data/elasticsearch/generated/transactions.json[] ----- -==== - -[[apm-data-model-errors]] -=== Errors - -An error event contains at least -information about the original `exception` that occurred -or about a `log` created when the exception occurred. -For simplicity, errors are represented by a unique ID. - -An Error contains: - -* Both the captured `exception` and the captured `log` of an error can contain a `stack trace`, -which is helpful for debugging. -* The `culprit` of an error indicates where it originated. -* An error might relate to the <> during which it happened, -via the `transaction.id`. -* Data about the environment in which the event is recorded: -** Service - environment, framework, language, etc. -** Host - architecture, hostname, IP, etc. -** Process - args, PID, PPID, etc. -** URL - full, domain, port, query, etc. -** <> - (if supplied) email, ID, username, etc. - -In addition, agents provide options for users to capture custom <>. -Metadata can be indexed - <>, or not-indexed - <>. - -TIP: Most agents limit keyword fields (e.g. `error.id`) to 1024 characters, -non-keyword fields (e.g. `error.exception.message`) to 10,000 characters. - -Errors are stored in error indices. - -[float] -==== Data streams - -Errors are stored in the following data streams: - -include::./data-streams.asciidoc[tag=logs-data-streams] - -See <> to learn more. - -[float] -==== Example error document - -This example shows what error documents can look like when indexed in {es}. - -[%collapsible] -.Expand {es} document -==== -[source,json] ----- -include::{apm-server-root}/docs/data/elasticsearch/generated/errors.json[] ----- -==== - [[apm-data-model-metrics]] -=== Metrics += Metrics **Metrics** measure the state of a system by gathering information on a regular interval. There are two types of APM metrics: @@ -226,7 +7,7 @@ include::{apm-server-root}/docs/data/elasticsearch/generated/errors.json[] * **Calculated metrics**: Aggregated trace event metrics used to power visualizations in the APM UI. [float] -==== System metrics +== System metrics APM agents automatically pick up basic host-level metrics, including system and process-level CPU and memory metrics. @@ -251,7 +32,7 @@ For a full list of tracked metrics, see the relevant agent documentation: * {apm-ruby-ref-v}/metrics.html[Ruby] [float] -===== Example system metric document +=== Example system metric document This example shows what system metric documents can look like when indexed in {es}. @@ -271,7 +52,7 @@ include::{apm-server-root}/docs/data/elasticsearch/metricset.json[] ==== [float] -==== Calculated metrics +== Calculated metrics APM agents and APM Server calculate metrics from trace events to power visualizations in the APM UI. @@ -281,7 +62,7 @@ the dimensions and concrete limits for aggregations are subject to change within These metrics are described below. [float] -===== Breakdown metrics +=== Breakdown metrics To power the <> graph, agents collect summarized metrics about the timings of spans and transactions, @@ -306,7 +87,7 @@ You can filter and group by these dimensions: -- [float] -===== Example breakdown metric document +=== Example breakdown metric document This example shows what breakdown metric documents can look like when indexed in {es}. @@ -321,7 +102,7 @@ include::{apm-server-root}/docs/data/elasticsearch/span_breakdown.json[] ==== [float] -===== Transaction metrics +=== Transaction metrics To power <> visualizations, APM Server aggregates transaction events into latency distribution metrics. @@ -377,7 +158,7 @@ You can filter and group by these dimensions (some of which are optional, for ex The `@timestamp` field of these documents holds the start of the aggregation interval. [float] -===== Example transaction document +=== Example transaction document This example shows what transaction documents can look like when indexed in {es}. @@ -392,7 +173,7 @@ include::{apm-server-root}/docs/data/elasticsearch/transaction_metric.json[] ==== [float] -===== Service-transaction metrics +=== Service-transaction metrics To power <> visualizations, APM Server aggregates transaction events into service-transaction metrics. @@ -423,7 +204,7 @@ You can filter and group by these dimensions: The `@timestamp` field of these documents holds the start of the aggregation interval. [float] -===== Example service-transaction document +=== Example service-transaction document This example shows what service-transaction documents can look like when indexed in {es}. @@ -438,7 +219,7 @@ include::{apm-server-root}/docs/data/elasticsearch/service_transaction_metric.js ==== [float] -===== Service-destination metrics +=== Service-destination metrics To power <> visualizations, APM Server aggregates span events into service-destination metrics. @@ -471,7 +252,7 @@ You can filter and group by these dimensions: The `@timestamp` field of these documents holds the start of the aggregation interval. [float] -===== Example service-destination document +=== Example service-destination document This example shows what service-destination documents can look like when indexed in {es}. @@ -486,7 +267,7 @@ include::{apm-server-root}/docs/data/elasticsearch/service_destination_metric.js ==== [float] -===== Service-summary metrics +=== Service-summary metrics To power <> visualizations, APM Server aggregates transaction, error, log, and metric events into service-summary metrics. @@ -506,7 +287,7 @@ You can filter and group by these dimensions: The `@timestamp` field of these documents holds the start of the aggregation interval. [float] -===== Example service-summary document +=== Example service-summary document This example shows what service-summary documents can look like when indexed in {es}. @@ -521,22 +302,22 @@ include::{apm-server-root}/docs/data/elasticsearch/service_summary_metric.json[] ==== [float] -==== Data streams +== Data streams Metrics are stored in the following data streams: -include::./data-streams.asciidoc[tag=metrics-data-streams] +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=metrics-data-streams] See <> to learn more. [float] -==== Aggregated metrics: limits and overflows +== Aggregated metrics: limits and overflows For all aggregated metrics, namely transaction, service-transaction, service-destination, and service-summary metrics, there are limits on the number of unique groups tracked at any given time. [float] -===== Limits +=== Limits Note that all the below limits may change in the future with further improvements. @@ -556,7 +337,7 @@ which is 1000 service destination groups for 1GB APM Server with 500 increment p In the above, a service is defined as a combination of `service.name`, `service.environment`, `service.language.name` and `agent.name`. [float] -===== Overflows +=== Overflows When a dimension has a high cardinality and exceeds the limit, the metrics will be aggregated under a dedicated overflow bucket. @@ -577,104 +358,3 @@ that are based on parameters that can change. For example, user ids, product ids should be stripped away from the dimensions. For the same reason, avoid high cardinality global labels (`labels.\*` and `numeric_labels.*`). Aggregated metrics do not consider global labels from RUM agents in order to protect APM server from using too much memory. - -// This heading is linked to from the APM UI section in Kibana -[[apm-data-model-metadata]] -=== Metadata - -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. - -[float] -[[apm-data-model-labels]] -==== Labels - -Labels add *indexed* information to transactions, spans, and errors. -Indexed means the data is searchable and aggregatable in {es}. -Add additional key-value pairs to define multiple labels. - -* Indexed: Yes -* {es} type: {ref}/object.html[object] -* {es} field: `labels` -* Applies to: <> | <> | <> - -Label values can be a string, boolean, or number, although some agents only support string values at this time. -Because labels for a given key, regardless of agent used, are stored in the same place in {es}, -all label values of a given key must have the same data type. -Multiple data types per key will throw an exception, for example: `{foo: bar}` and `{foo: 42}` is not allowed. - -IMPORTANT: Avoid defining too many user-specified labels. -Defining too many unique fields in an index is a condition that can lead to a -{ref}/mapping.html#mapping-limit-settings[mapping explosion]. - -[float] -===== Agent API reference - -* Go: {apm-go-ref-v}/api.html#context-set-label[`SetLabel`] -* Java: {apm-java-ref-v}/public-api.html#api-transaction-add-tag[`setLabel`] -* .NET: {apm-dotnet-ref-v}/public-api.html#api-transaction-set-label[`SetLabel`] -* Node.js: {apm-node-ref-v}/agent-api.html#apm-set-label[`setLabel`] | {apm-node-ref-v}/agent-api.html#apm-add-labels[`addLabels`] -* PHP: {apm-php-ref}/public-api.html#api-transaction-interface-set-label[`Transaction` `setLabel`] | {apm-php-ref}/public-api.html#api-span-interface-set-label[`Span` `setLabel`] -* Python: {apm-py-ref-v}/api.html#api-label[`elasticapm.label()`] -* Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-label[`set_label`] -* Rum: {apm-rum-ref-v}/agent-api.html#apm-add-labels[`addLabels`] - -[float] -[[apm-data-model-custom]] -==== Custom context - -Custom context adds *non-indexed*, -custom contextual information to transactions and errors. -Non-indexed means the data is not searchable or aggregatable in {es}, -and you cannot build dashboards on top of the data. -This also means you don't have to worry about {ref}/mapping.html#mapping-limit-settings[mapping explosions], -as these fields are not added to the mapping. - -Non-indexed information is useful for providing contextual information to help you -quickly debug performance issues or errors. - -* Indexed: No -* {es} type: {ref}/object.html[object] -* {es} fields: `transaction.custom` | `error.custom` -* Applies to: <> | <> - -IMPORTANT: Setting a circular object, a large object, or a non JSON serializable object can lead to errors. - -[float] -===== Agent API reference - -* Go: {apm-go-ref-v}/api.html#context-set-custom[`SetCustom`] -* iOS: _coming soon_ -* Java: {apm-java-ref-v}/public-api.html#api-transaction-add-custom-context[`addCustomContext`] -* .NET: _coming soon_ -* Node.js: {apm-node-ref-v}/agent-api.html#apm-set-custom-context[`setCustomContext`] -* PHP: _coming soon_ -* Python: {apm-py-ref-v}/api.html#api-set-custom-context[`set_custom_context`] -* Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-custom-context[`set_custom_context`] -* Rum: {apm-rum-ref-v}/agent-api.html#apm-set-custom-context[`setCustomContext`] - -[float] -[[apm-data-model-user]] -==== User context - -User context adds *indexed* user information to transactions and errors. -Indexed means the data is searchable and aggregatable in {es}. - -* Indexed: Yes -* {es} type: {ref}/keyword.html[keyword] -* {es} fields: `user.email` | `user.name` | `user.id` -* Applies to: <> | <> - -[float] -===== Agent API reference - -* Go: {apm-go-ref-v}/api.html#context-set-username[`SetUsername`] | {apm-go-ref-v}/api.html#context-set-user-id[`SetUserID`] | -{apm-go-ref-v}/api.html#context-set-user-email[`SetUserEmail`] -* iOS: _coming soon_ -* Java: {apm-java-ref-v}/public-api.html#api-transaction-set-user[`setUser`] -* .NET _coming soon_ -* Node.js: {apm-node-ref-v}/agent-api.html#apm-set-user-context[`setUserContext`] -* PHP: _coming soon_ -* Python: {apm-py-ref-v}/api.html#api-set-user-context[`set_user_context`] -* Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-user[`set_user`] -* Rum: {apm-rum-ref-v}/agent-api.html#apm-set-user-context[`setUserContext`] diff --git a/docs/en/observability/apm/span-compression.asciidoc b/docs/en/observability/apm/data-model/data-model-spans.asciidoc similarity index 54% rename from docs/en/observability/apm/span-compression.asciidoc rename to docs/en/observability/apm/data-model/data-model-spans.asciidoc index 8156639bd3..a0e395b2fb 100644 --- a/docs/en/observability/apm/span-compression.asciidoc +++ b/docs/en/observability/apm/data-model/data-model-spans.asciidoc @@ -1,5 +1,85 @@ -[[apm-span-compression]] -=== Span compression +[[apm-data-model-spans]] += Spans + +*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. + +Agents automatically instrument a variety of libraries to capture these spans from within your application, +but you can also use the Agent API for custom instrumentation of specific code paths. + +Among other things, spans can contain: + +* A `transaction.id` attribute that refers to its parent <>. +* A `parent.id` attribute that refers to its parent span or transaction. +* Its start time and duration. +* A `name`, `type`, `subtype`, and `action`—see the {span-name-type-sheet}[span name/type alignment] +sheet for span name patterns and examples by {apm-agent}. +In addition, some APM agents test against a public {span-spec}[span type/subtype spec]. +* An optional `stack trace`. Stack traces consist of stack frames, +which represent a function call on the call stack. +They include attributes like function name, file name and path, line number, etc. + +TIP: Most agents limit keyword fields, like `span.id`, to 1024 characters, +and non-keyword fields, like `span.start.us`, to 10,000 characters. + +[float] +[[apm-data-model-dropped-spans]] +== Dropped spans + +For performance reasons, APM agents can choose to sample or omit spans purposefully. +This can be useful in preventing edge cases, like long-running transactions with over 100 spans, +that would otherwise overload both the Agent and the APM Server. +When this occurs, the APM UI will display the number of spans dropped. + +To configure the number of spans recorded per transaction, see the relevant Agent documentation: + +* Android: _Not yet supported_ +* Go: {apm-go-ref-v}/configuration.html#config-transaction-max-spans[`ELASTIC_APM_TRANSACTION_MAX_SPANS`] +* iOS: _Not yet supported_ +* Java: {apm-java-ref-v}/config-core.html#config-transaction-max-spans[`transaction_max_spans`] +* .NET: {apm-dotnet-ref-v}/config-core.html#config-transaction-max-spans[`TransactionMaxSpans`] +* Node.js: {apm-node-ref-v}/configuration.html#transaction-max-spans[`transactionMaxSpans`] +* PHP: {apm-php-ref-v}/configuration-reference.html#config-transaction-max-spans[`transaction_max_spans`] +* Python: {apm-py-ref-v}/configuration.html#config-transaction-max-spans[`transaction_max_spans`] +* Ruby: {apm-ruby-ref-v}/configuration.html#config-transaction-max-spans[`transaction_max_spans`] + +[float] +[[apm-data-model-missing-spans]] +== Missing spans + +Agents stream spans to the APM Server separately from their transactions. +Because of this, unforeseen errors may cause spans to go missing. +Agents know how many spans a transaction should have; +if the number of expected spans does not equal the number of spans received by the APM Server, +the APM UI will calculate the difference and display a message. + +[float] +== Data streams + +Spans are stored with transactions in the following data streams: + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=traces-data-streams] + +See <> to learn more. + +[float] +== Example span document + +This example shows what span documents can look like when indexed in {es}. + +[%collapsible] +.Expand {es} document +==== +[source,json] +---- +include::{apm-server-root}/docs/data/elasticsearch/generated/spans.json[] +---- +==== + +[float] +[[apm-spans-span-compression]] +== Span compression In some cases, APM agents may collect large amounts of very similar or identical spans in a transaction. For example, this can happen if spans are captured inside of a loop, or in unoptimized SQL queries that use multiple queries instead of joins to fetch related data. diff --git a/docs/en/observability/apm/apm-distributed-tracing.asciidoc b/docs/en/observability/apm/data-model/distributed-tracing.asciidoc similarity index 84% rename from docs/en/observability/apm/apm-distributed-tracing.asciidoc rename to docs/en/observability/apm/data-model/distributed-tracing.asciidoc index 42c04a4e79..dbb1e6df76 100644 --- a/docs/en/observability/apm/apm-distributed-tracing.asciidoc +++ b/docs/en/observability/apm/data-model/distributed-tracing.asciidoc @@ -1,10 +1,19 @@ +[[apm-data-model-traces]] += Traces + +A trace is a group of <> and <> with a common root. +Each trace tracks the entirety of a single request. It describes the individual operations and their causality that +ensue from a single logical operation. + +[float] [[apm-distributed-tracing]] -=== Distributed tracing +== Distributed tracing + +When a trace travels through multiple services, as is common in a microservice architecture, +it is known as a *distributed trace*. A distributed trace comprises operations across multiple +distributed components, crossing process, network, and security boundaries. -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, -it is known as a distributed trace. +image::images/distributed-traces.png[Diagram illustrating the relationship between spans, transactions, and distributed traces as described in the text on this page] [float] [[apm-why-distributed-tracing]] @@ -37,7 +46,7 @@ and continues to propagate the trace. [float] [[apm-trace-propagation]] -==== Trace propagation examples +=== Trace propagation examples In this example, Elastic's Ruby agent communicates with Elastic's Java agent. Both support the `traceparent` header, and trace data is successfully propagated. @@ -60,7 +69,7 @@ image::./images/dt-trace-ex3.png[How traceparent propagation works] [float] [[apm-w3c-tracecontext-spec]] -==== W3C Trace Context specification +=== W3C Trace Context specification All Elastic agents now support the official W3C Trace Context specification and `traceparent` header. See the table below for the minimum required agent version: diff --git a/docs/en/observability/apm/data-model/index.asciidoc b/docs/en/observability/apm/data-model/index.asciidoc new file mode 100644 index 0000000000..b3d0771787 --- /dev/null +++ b/docs/en/observability/apm/data-model/index.asciidoc @@ -0,0 +1,52 @@ +:span-name-type-sheet: https://docs.google.com/spreadsheets/d/1SmWeX5AeqUcayrArUauS_CxGgsjwRgMYH4ZY8yQsMhQ/edit#gid=644582948 +:span-spec: https://github.com/elastic/apm/blob/main/tests/agents/json-specs/span_types.json + +[[apm-data-model]] += Application data types + +++++ +Learn about data types +++++ + +Elastic APM agents capture different types of information from within their instrumented applications. +These are known as events, and can be spans, transactions, traces, errors, or metrics. + +//// +Explain how the different data types relate to each other at a high level +//// + +Elastic APM helps you see what happens from start to finish when a request is made to an application: + +* <>: A span contain information about the execution of a specific code path. + They are the building blocks of _transactions_ and _traces_. +* <>: A transaction describes an event captured by an Elastic + APM agent instrumenting a service. A transaction is technically a type of span that has additional + attributes associated with it and often contains multiple child _spans_. You can think of transactions + as the highest level of work you’re measuring within a service. +* <>: A trace is a group of _transactions_ and _spans_ with a common root. + Each trace tracks the entirety of a single request. When a trace travels through multiple services, + it is known as a _distributed trace_. + +image::images/spans-transactions-and-traces.png[Diagram illustrating the relationship between spans, transactions, and traces as described in the text on this page] + +In addition to the building blocks of traces, Elastic APM agents also capture: + +* <>: An error is created when something goes wrong with a request to an application. + This event contains information to help you determine where and why an error occurred, often including in which + _transaction_ the error occurred. +* <>: Metrics measure the state of a system by gathering information on a regular interval. + +Events can contain additional <> which further enriches your data. + +//// +Subsections +//// + +:leveloffset: +1 +include::{observability-docs-root}/docs/en/observability/apm/data-model/data-model-spans.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/data-model/transactions/index.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/data-model/distributed-tracing.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/data-model/data-model-errors.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/data-model/data-model-metrics.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/data-model/data-model-metadata.asciidoc[] +:!leveloffset: diff --git a/docs/en/observability/apm/data-model/transactions/index.asciidoc b/docs/en/observability/apm/data-model/transactions/index.asciidoc new file mode 100644 index 0000000000..3b4ade2936 --- /dev/null +++ b/docs/en/observability/apm/data-model/transactions/index.asciidoc @@ -0,0 +1,76 @@ +[[apm-data-model-transactions]] += Transactions + +*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. +As an example, a transaction might be a: + +* Request to your server +* Batch job +* Background job +* Custom transaction type + +Agents decide whether to sample transactions or not, +and provide settings to control sampling behavior. +If sampled, the <> of a transaction are sent and stored as separate documents. +Within one transaction there can be 0, 1, or many spans captured. + +A transaction contains: + +* The timestamp of the event +* A unique id, type, and name +* Data about the environment in which the event is recorded: +** Service - environment, framework, language, etc. +** Host - architecture, hostname, IP, etc. +** Process - args, PID, PPID, etc. +** URL - full, domain, port, query, etc. +** <> - (if supplied) email, ID, username, etc. +* Other relevant information depending on the agent. Example: The JavaScript RUM agent captures transaction marks, +which are points in time relative to the start of the transaction with some label. + +In addition, agents provide options for users to capture custom <>. +Metadata can be indexed - <>, or not-indexed - <>. + +Transactions are grouped by their `type` and `name` in the APM UI's +<>. +If you're using a supported framework, APM agents will automatically handle the naming for you. +If you're not, or if you wish to override the default, +all agents have API methods to manually set the `type` and `name`. + +* `type` should be a keyword of specific relevance in the service's domain, +e.g. `request`, `backgroundjob`, etc. +* `name` should be a generic designation of a transaction in the scope of a single service, +e.g. `GET /users/:id`, `UsersController#show`, etc. + +TIP: Most agents limit keyword fields (e.g. `labels`) to 1024 characters, +non-keyword fields (e.g. `span.db.statement`) to 10,000 characters. + +[float] +== Data streams + +Transactions are stored with spans in the following data streams: + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=traces-data-streams] + +See <> to learn more. + +[float] +== Example transaction document + +This example shows what transaction documents can look like when indexed in {es}. + +[%collapsible] +.Expand {es} document +==== +[source,json] +---- +include::{apm-server-root}/docs/data/elasticsearch/generated/transactions.json[] +---- +==== + +//// +Subsections +//// + +include::{observability-docs-root}/docs/en/observability/apm/data-model/transactions/sampling.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/sampling.asciidoc b/docs/en/observability/apm/data-model/transactions/sampling.asciidoc similarity index 93% rename from docs/en/observability/apm/sampling.asciidoc rename to docs/en/observability/apm/data-model/transactions/sampling.asciidoc index 33172f4dc9..af055d6093 100644 --- a/docs/en/observability/apm/sampling.asciidoc +++ b/docs/en/observability/apm/data-model/transactions/sampling.asciidoc @@ -1,5 +1,5 @@ [[apm-sampling]] -=== Transaction sampling += Transaction sampling Distributed tracing can generate a substantial amount of data. More data can mean higher costs and more noise. @@ -14,7 +14,7 @@ Elastic APM supports two types of sampling: [float] [[apm-head-based-sampling]] -==== Head-based sampling +== Head-based sampling In head-based sampling, the sampling decision for each trace is made when the trace is initiated. Each trace has a defined and equal probability of being sampled. @@ -31,7 +31,7 @@ See <> to get started. [float] [[distributed-tracing-examples]] -===== Distributed tracing +=== Distributed tracing In a distributed trace, the sampling decision is still made when the trace is initiated. Each subsequent service respects the initial service's sampling decision, regardless of its configured sample rate; @@ -52,7 +52,7 @@ be `1` (`100%`). image::./images/dt-sampling-example-2.png[Distributed tracing and head based sampling example two] [float] -===== Trace continuation strategies with distributed tracing +==== Trace continuation strategies with distributed tracing In addition to setting the sample rate, you can also specify which _trace continuation strategy_ to use. There are three trace continuation strategies: `continue`, `restart`, and `restart_external`. @@ -91,7 +91,7 @@ traces will be sampled as new traces in `Service C`. The end result will be five image::./images/dt-sampling-continuation-strategy-restart.png[Distributed tracing and head based sampling with restart continuation strategy] [float] -===== OpenTelemetry +=== OpenTelemetry Head-based sampling is implemented directly in the APM agents and SDKs. The sample rate must be propagated between services and the managed intake service in order to produce accurate metrics. @@ -113,7 +113,7 @@ Refer to the documentation of your favorite OpenTelemetry agent or SDK for more [float] [[apm-tail-based-sampling]] -==== Tail-based sampling +== Tail-based sampling In tail-based sampling, the sampling decision for each trace is made after the trace has completed. This means all traces will be analyzed against a set of rules, or policies, which will determine the rate at which they are sampled. @@ -129,7 +129,8 @@ So running APM Server close to your instrumented services can reduce any increas See <> to get started. -**Distributed tracing with tail-based sampling** +[float] +=== Distributed tracing with tail-based sampling With tail-based sampling, all traces are observed and a sampling decision is only made once a trace completes. @@ -140,7 +141,8 @@ the sampled traces would look something like this: image::./images/dt-sampling-example-3.png[Distributed tracing and tail based sampling example one] -**OpenTelemetry with tail-based sampling** +[float] +=== OpenTelemetry with tail-based sampling Tail-based sampling is implemented entirely in APM Server, and will work with traces sent by either Elastic APM agents or OpenTelemetry SDKs. @@ -148,7 +150,7 @@ and will work with traces sent by either Elastic APM agents or OpenTelemetry SDK Due to <> when using https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor[tailsamplingprocessor], we recommend using APM Server tail-based sampling instead. [float] -==== Sampled data and visualizations +== Sampled data and visualizations A sampled trace retains all data associated with it. A non-sampled trace drops all <> and <> data^1^. @@ -174,7 +176,7 @@ The {kib} apps that utilize RUM data depend on transaction events, so non-sampled RUM traces retain transaction data -- only span data is dropped. [float] -==== Sample rates +== Sample rates What's the best sampling rate? Unfortunately, there isn't one. Sampling is dependent on your data, the throughput of your application, data retention policies, and other factors. @@ -189,26 +191,27 @@ Here are some examples: Regardless of the above, cost conscious customers are likely to be fine with a lower sample rate. +[float] [[apm-configure-head-based-sampling]] -==== Configure head-based sampling +== Configure head-based sampling There are three ways to adjust the head-based sampling rate of your APM agents: [float] -===== Dynamic configuration +=== Dynamic configuration The transaction sample rate can be changed dynamically (no redeployment necessary) on a per-service and per-environment basis with <> in {kib}. [float] -===== {kib} API configuration +=== {kib} API configuration {apm-agent} configuration exposes an API that can be used to programmatically change your agents' sampling rate. An example is provided in the <>. [float] -===== {apm-agent} configuration +=== {apm-agent} configuration Each agent provides a configuration value used to set the transaction sample rate. See the relevant agent's documentation for more details: @@ -221,8 +224,9 @@ See the relevant agent's documentation for more details: * Python: {apm-py-ref-v}/configuration.html#config-transaction-sample-rate[`transaction_sample_rate`] * Ruby: {apm-ruby-ref-v}/configuration.html#config-transaction-sample-rate[`transaction_sample_rate`] +[float] [[apm-configure-tail-based-sampling]] -==== Configure tail-based sampling +== Configure tail-based sampling Enable tail-based sampling with <>. When enabled, trace events are mapped to sampling policies. @@ -241,7 +245,7 @@ but, due to how the limit is calculated and enforced the actual disk space may s over the limit. [float] -===== Example configuration +=== Example configuration This example defines three tail-based sampling polices: @@ -261,14 +265,14 @@ This example defines three tail-based sampling polices: or traces with any other name [float] -===== Configuration reference +=== Configuration reference -**Top-level tail-based sampling settings:** +[float] +==== Top-level tail-based sampling settings -:leveloffset: +4 -include::./configure/sampling.asciidoc[tag=tbs-top] +include::{observability-docs-root}/docs/en/observability/apm/configure/sampling.asciidoc[tag=tbs-top,leveloffset=+2] -**Policy settings:** +[float] +==== Policy settings -include::./configure/sampling.asciidoc[tag=tbs-policy] -:leveloffset: -4 +include::{observability-docs-root}/docs/en/observability/apm/configure/sampling.asciidoc[tag=tbs-policy,leveloffset=+2] diff --git a/docs/en/observability/apm/features.asciidoc b/docs/en/observability/apm/features.asciidoc deleted file mode 100644 index 6800ce61b6..0000000000 --- a/docs/en/observability/apm/features.asciidoc +++ /dev/null @@ -1,37 +0,0 @@ -[[apm-features]] -== Elastic APM features - -++++ -Features -++++ - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -include::./apm-k8s-attacher.asciidoc[leveloffset=+2] - -include::./cross-cluster-search.asciidoc[] - -include::./apm-data-security.asciidoc[] - -include::./apm-distributed-tracing.asciidoc[] - -include::./jaeger-integration.asciidoc[] - -include::./log-correlation.asciidoc[] - -include::./aws-lambda-extension.asciidoc[leveloffset=+2] - -include::./apm-rum.asciidoc[] - -include::./span-compression.asciidoc[] - -include::./sampling.asciidoc[] diff --git a/docs/en/observability/apm/getting-started-apm-server.asciidoc b/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc similarity index 55% rename from docs/en/observability/apm/getting-started-apm-server.asciidoc rename to docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc index 9ccde19dbd..4087a8cc64 100644 --- a/docs/en/observability/apm/getting-started-apm-server.asciidoc +++ b/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc @@ -1,153 +1,10 @@ -[[apm-getting-started-apm-server]] -== Self manage APM Server - -++++ -Self manage APM Server -++++ - -TIP: The easiest way to get started with Elastic APM is by using our -{ess-product}[hosted {es} Service] on {ecloud}. -The {es} Service is available on AWS, GCP, and Azure. -See <> to get started in minutes. - - -// TODO: MOVE THIS -IMPORTANT: Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage APM index templates, -{ilm-init} policies, and ingest pipelines. APM Server will only send data to {es} _after_ the APM integration has been installed. - -The APM Server receives performance data from your APM agents, -validates and processes it, and then transforms the data into {es} documents. -If you're on this page, then you've chosen to self-manage the Elastic Stack, -and you now must decide how to run and configure the APM Server. -There are two options, and the components required are different for each: - -* **<>** -* **<>** -// * **<>** - -[float] -[[apm-setup-apm-server-binary]] -=== APM Server binary - -Install, configure, and run the APM Server binary wherever you need it. - -image::./images/bin-ov.png[APM Server binary overview] - -**Pros**: - -- Simplest self-managed option -- No addition component knowledge required -- YAML configuration simplifies automation - -**Supported outputs**: - -- {es} -- {ess} -- {ls} -- Kafka -- Redis -- File -- Console - -**Required components**: - -- APM agents -- APM Server -- {stack} - -**Configuration method**: YAML - -[float] -[[apm-setup-fleet-managed-apm]] -=== Fleet-managed APM Server - -Fleet is a web-based UI in {kib} that is used to centrally manage {agent}s. -In this deployment model, use {agent} to spin up APM Server instances that can be centrally-managed in a custom-curated user interface. - -NOTE: Fleet-managed APM Server does not have full feature parity with the APM Server binary method of running Elastic APM. - -image::./images/fm-ov.png[APM Server fleet overview] - -// (outputs, stable APIs) -// not the best option for a simple test setup or if only interested in centrally running APM Server - -**Pros**: - -- Conveniently manage one, some, or many different integrations from one central {fleet} UI. - -**Supported outputs**: - -- {es} -- {ess} - -**Required components**: - -- APM agents -- APM Server -- {agent} -- Fleet Server -- {stack} - -**Configuration method**: {kib} UI - -// [float] -// [[apm-setup-apm-server-ea]] -// === Standalone Elastic Agent-managed APM Server -// // I really don't know how to sell this option -// Instead of installing and configuring the APM Server binary, let {agent} orchestrate it for you. -// Install {agent} and manually configure the agent locally on the system where it's installed. -// You are responsible for managing and upgrading {agent}. This approach is recommended for advanced users only. - -// **Pros**: - -// - Easily add integrations for other data sources -// useful if EA already in place for other integrations, and customers want to customize setup rather than using Fleet for configuration -// // TODO: -// // maybe get some more hints on this one from the EA team to align with highlighting the same pros & cons. - -// **Available on Elastic Cloud**: ❌ - -// This supports all of the same outputs as binary -// see https://github.com/elastic/apm-server/issues/10467 -// **Supported outputs**: - -// **Configuration method**: YAML - -// image::./images/ea-ov.png[APM Server ea overview] - -// @simitt's notes for how to include EA-managed in the decision tree: -// **** -// If we generally describe Standalone Elastic Agent managed APM Server then we should also add it to this diagram: -// Do you want to use other integrations? -// -> yes: Would you like to use the comfort of Fleet UI based management? -> yes: Fleet managed APM Server; -> no: Standalone Elastic Agent managed APM Server -// -> no: What is your prefered way of configuration? -> yaml: APM Server binary; -> Kibana UI: Fleet managed APM Server -// **** - -// Components required: - -// [options="header"] -// |==== -// | Installation method | APM Server | Elastic Agent | Fleet Server -// | APM Server binary | ✔️ | | -// // | Standalone Elastic Agent-managed APM Server | ✔️ | ✔️ | -// | Fleet-managed APM Server | ✔️ | ✔️ | ✔️ -// |==== - -[float] -=== Help me decide - -Use the decision tree below to help determine which method of configuring and running the APM Server is best for your use case. - -[subs=attributes+] -include::{observability-docs-root}/docs/en/observability/apm/diagrams/apm-decision-tree.asciidoc[APM Server decision tree] - - -=== APM Server binary +[[get-started-with-apm-server-binary]] += APM Server binary This guide will explain how to set up and configure the APM Server binary. [float] -==== Prerequisites +== Prerequisites // tag::prereq[] First, see the https://www.elastic.co/support/matrix[Elastic Support Matrix] for information about supported operating systems and product compatibility. @@ -168,8 +25,9 @@ image::images/apm-architecture-diy.png[Install Elastic APM yourself] // STEP 1 // ******************************************************* +[float] [[apm-installing]] -==== Step 1: Install +== Step 1: Install NOTE: *Before you begin*: If you haven't installed the {stack}, do that now. See {stack-ref}/installing-elastic-stack.html[Learn how to install the @@ -303,8 +161,9 @@ See <> for deploying Docker containers // STEP 2 // ******************************************************* +[float] [[apm-server-configuration]] -==== Step 2: Set up and configure +== Step 2: Set up and configure // This content is reused in the upgrading guide // tag::why-apm-integration[] @@ -313,7 +172,7 @@ Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage // end::why-apm-integration[] [float] -===== Install the APM integration +=== Install the APM integration // This content is reused in the upgrading guide // tag::install-apm-integration[] @@ -367,7 +226,7 @@ See {kibana-ref}/api.html[Kibana API] to learn more about how to use the Kibana // end::install-apm-integration[] [float] -===== Configure APM +=== Configure APM Configure APM by editing the `apm-server.yml` configuration file. The location of this file varies by platform--see the <> for help locating it. @@ -396,8 +255,9 @@ All available configuration options are outlined in // STEP 3 // ******************************************************* +[float] [[apm-server-starting]] -==== Step 3: Start +== Step 3: Start In a production environment, you would put APM Server on its own machines, similar to how you run {es}. @@ -426,7 +286,7 @@ You can change the defaults in `apm-server.yml` or by supplying a different addr [float] [[apm-running-deb-rpm]] -===== Debian Package / RPM +=== Debian Package / RPM For Debian package and RPM installations, we recommend the `apm-server` process runs as a non-root user. Therefore, these installation methods create an `apm-server` user which you can use to start the process. @@ -447,97 +307,32 @@ See the <> for a full directory la // STEP 4 // ******************************************************* +[float] [[apm-next-steps]] -==== Step 4: Next steps - -// Use a tagged region to pull APM Agent information from the APM Overview -If you haven't already, you can now install APM Agents in your services! - -* {apm-android-ref}/intro.html[Android agent] -* {apm-go-ref-v}/introduction.html[Go agent] -* {apm-ios-ref-v}/intro.html[iOS agent] -* {apm-java-ref-v}/intro.html[Java agent] -* {apm-dotnet-ref-v}/intro.html[.NET agent] -* {apm-node-ref-v}/intro.html[Node.js agent] -* {apm-php-ref-v}/intro.html[PHP agent] -* {apm-py-ref-v}/getting-started.html[Python agent] -* {apm-ruby-ref-v}/introduction.html[Ruby agent] -* {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] - -Once you have at least one {apm-agent} sending data to APM Server, -you can start visualizing your data in the <>. +== Step 4: Install APM agents -If you're migrating from Jaeger, see <>. - -// Shared APM & YUM -include::{observability-docs-root}/docs/en/observability/apm/repositories.asciidoc[] - -// Shared docker -include::{observability-docs-root}/docs/en/observability/apm/shared-docker.asciidoc[] - -[[get-started-with-fleet-apm-server]] -=== Fleet-managed APM Server +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc[] -This guide will explain how to set up and configure a Fleet-managed APM Server. +// ******************************************************* +// STEP 5 +// ******************************************************* [float] -==== Prerequisites - -You need {es} for storing and searching your data, and {kib} for visualizing and managing it. -When setting these components up, you need: - -include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/prereq.asciidoc[tag=self-managed] - -==== Step 1: Set up Fleet +== Step 5: View your data -Use {fleet} in {kib} to get APM data into the {stack}. -The first time you use {fleet}, you'll need to set it up and add a -{fleet-server}: - -include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc[tag=self-managed] - -For more information, refer to {fleet-guide}/fleet-server.html[{fleet-server}]. - -[[add-apm-integration]] -==== Step 2: Add and configure the APM integration - -include::{observability-docs-root}/docs/en/observability/tab-widgets/add-apm-integration/content.asciidoc[tag=self-managed] - -**** -An internet connection is required to install the APM integration via the Fleet UI in Kibana. - --- -include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm-server.asciidoc[tag=install-apm-integration-no-internet] --- -**** - -==== Step 3: Install APM agents - -APM agents are written in the same language as your service. -To monitor a new service, you must install the agent and configure it with a service name, -APM Server host, and Secret token. - -* **Service name**: The APM integration maps an instrumented service's name–defined in each {apm-agent}'s configuration– -to the index that its data is stored in {es}. -Service names are case-insensitive and must be unique. -For example, you cannot have a service named `Foo` and another named `foo`. -Special characters will be removed from service names and replaced with underscores (`_`). - -* **APM Server URL**: The host and port that APM Server listens for events on. -This should match the host and port defined when setting up the APM integration. - -* **Secret token**: Authentication method for {apm-agent} and APM Server communication. -This should match the secret token defined when setting up the APM integration. - -TIP: You can edit your APM integration settings if you need to change the APM Server URL -or secret token to match your APM agents. +Once you have at least one {apm-agent} sending data to APM Server, +you can start visualizing your data in the <>. -include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc[] +[role="screenshot"] +image::./images/kibana-apm-sample-data.png[APM UI with data] -==== Step 4: View your data +// If you're migrating from Jaeger, see <>. -Back in {kib}, under {observability}, select APM. -You should see application performance monitoring data flowing into the {stack}! +//// +Subsections +//// -[role="screenshot"] -image::./images/kibana-apm-sample-data.png[APM UI with data] +// Shared APM & YUM +include::{observability-docs-root}/docs/en/observability/apm/repositories.asciidoc[leveloffset=+1] +// Shared docker +include::{observability-docs-root}/docs/en/observability/apm/shared-docker.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/getting-started-apm/get-started-with-fleet-apm-server.asciidoc b/docs/en/observability/apm/getting-started-apm/get-started-with-fleet-apm-server.asciidoc new file mode 100644 index 0000000000..261bf4617a --- /dev/null +++ b/docs/en/observability/apm/getting-started-apm/get-started-with-fleet-apm-server.asciidoc @@ -0,0 +1,70 @@ +[[get-started-with-fleet-apm-server]] += Fleet-managed APM Server + +This guide will explain how to set up and configure a Fleet-managed APM Server. + +[float] +== Prerequisites + +You need {es} for storing and searching your data, and {kib} for visualizing and managing it. +When setting these components up, you need: + +include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/prereq.asciidoc[tag=self-managed] + +[float] +== Step 1: Set up Fleet + +Use {fleet} in {kib} to get APM data into the {stack}. +The first time you use {fleet}, you'll need to set it up and add a +{fleet-server}: + +include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/add-fleet-server/content.asciidoc[tag=self-managed] + +For more information, refer to {fleet-guide}/fleet-server.html[{fleet-server}]. + +[float] +[[add-apm-integration]] +== Step 2: Add and configure the APM integration + +include::{observability-docs-root}/docs/en/observability/tab-widgets/add-apm-integration/content.asciidoc[tag=self-managed] + +**** +An internet connection is required to install the APM integration via the Fleet UI in Kibana. + +-- +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc[leveloffset=+2,tag=install-apm-integration-no-internet] +-- +**** + +[float] +== Step 3: Install APM agents + +APM agents are written in the same language as your service. +To monitor a new service, you must install the agent and configure it with a service name, +APM Server host, and Secret token. + +* **Service name**: The APM integration maps an instrumented service's name–defined in each {apm-agent}'s configuration– +to the index that its data is stored in {es}. +Service names are case-insensitive and must be unique. +For example, you cannot have a service named `Foo` and another named `foo`. +Special characters will be removed from service names and replaced with underscores (`_`). + +* **APM Server URL**: The host and port that APM Server listens for events on. +This should match the host and port defined when setting up the APM integration. + +* **Secret token**: Authentication method for {apm-agent} and APM Server communication. +This should match the secret token defined when setting up the APM integration. + +TIP: You can edit your APM integration settings if you need to change the APM Server URL +or secret token to match your APM agents. + +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc[] + +[float] +== Step 4: View your data + +Back in {kib}, under {observability}, select APM. +You should see application performance monitoring data flowing into the {stack}! + +[role="screenshot"] +image::./images/kibana-apm-sample-data.png[APM UI with data] diff --git a/docs/en/observability/apm/getting-started-apm/index.asciidoc b/docs/en/observability/apm/getting-started-apm/index.asciidoc new file mode 100644 index 0000000000..44dca348f9 --- /dev/null +++ b/docs/en/observability/apm/getting-started-apm/index.asciidoc @@ -0,0 +1,154 @@ +[[apm-getting-started-apm-server]] += Get started with APM + +++++ +Get started +++++ + +**** +The easiest way to get started with Elastic APM is by using our +{ess-product}[hosted {es} Service] on {ecloud}. +The {es} Service is available on AWS, GCP, and Azure. +*To get started in minutes, follow the steps in <>.* +**** + +// TODO: MOVE THIS +IMPORTANT: Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage APM index templates, +{ilm-init} policies, and ingest pipelines. APM Server will only send data to {es} _after_ the APM integration has been installed. + +The APM Server receives performance data from your APM agents, +validates and processes it, and then transforms the data into {es} documents. +If you're on this page, then you've chosen to self-manage the Elastic Stack, +and you now must decide how to run and configure the APM Server. +There are two options, and the components required are different for each: + +* **<>** +* **<>** +// * **<>** + +[float] +[[apm-setup-fleet-managed-apm]] +== Fleet-managed APM Server + +Fleet is a web-based UI in {kib} that is used to centrally manage {agent}s. +In this deployment model, use {agent} to spin up APM Server instances that can be centrally-managed in a custom-curated user interface. + +NOTE: Fleet-managed APM Server does not have full feature parity with the APM Server binary method of running Elastic APM. + +image::./images/fm-ov.png[APM Server fleet overview] + +// (outputs, stable APIs) +// not the best option for a simple test setup or if only interested in centrally running APM Server + +[cols="1,3"] +|=== +| *Pros* +a| Conveniently manage one, some, or many different +integrations from one central {fleet} UI. + +| *Supported outputs* +a| * {es} +* {ess} + +| *Required{nbsp}components* +a| * APM agents +* APM Server +* {agent} +* Fleet Server +* {stack} + +| *Configuration method* +| {kib} UI +|=== + +[float] +[[apm-setup-apm-server-binary]] +== APM Server binary + +Install, configure, and run the APM Server binary wherever you need it. + +image::./images/bin-ov.png[APM Server binary overview] + +[cols="1,3"] +|=== +| *Pros* +a| * Simplest self-managed option +* No addition component knowledge required +* YAML configuration simplifies automation + +| *Supported outputs* +a| * {es} +* {ess} +* {ls} +* Kafka +* Redis +* File +* Console + +| *Required components* +a| * APM agents +* APM Server +* {stack} + +| *Configuration method* +a| YAML +|=== + +// [float] +// [[apm-setup-apm-server-ea]] +// === Standalone Elastic Agent-managed APM Server +// // I really don't know how to sell this option +// Instead of installing and configuring the APM Server binary, let {agent} orchestrate it for you. +// Install {agent} and manually configure the agent locally on the system where it's installed. +// You are responsible for managing and upgrading {agent}. This approach is recommended for advanced users only. + +// **Pros**: + +// - Easily add integrations for other data sources +// useful if EA already in place for other integrations, and customers want to customize setup rather than using Fleet for configuration +// // TODO: +// // maybe get some more hints on this one from the EA team to align with highlighting the same pros & cons. + +// **Available on Elastic Cloud**: ❌ + +// This supports all of the same outputs as binary +// see https://github.com/elastic/apm-server/issues/10467 +// **Supported outputs**: + +// **Configuration method**: YAML + +// image::./images/ea-ov.png[APM Server ea overview] + +// @simitt's notes for how to include EA-managed in the decision tree: +// **** +// If we generally describe Standalone Elastic Agent managed APM Server then we should also add it to this diagram: +// Do you want to use other integrations? +// -> yes: Would you like to use the comfort of Fleet UI based management? -> yes: Fleet managed APM Server; -> no: Standalone Elastic Agent managed APM Server +// -> no: What is your prefered way of configuration? -> yaml: APM Server binary; -> Kibana UI: Fleet managed APM Server +// **** + +// Components required: + +// [options="header"] +// |==== +// | Installation method | APM Server | Elastic Agent | Fleet Server +// | APM Server binary | ✔️ | | +// // | Standalone Elastic Agent-managed APM Server | ✔️ | ✔️ | +// | Fleet-managed APM Server | ✔️ | ✔️ | ✔️ +// |==== + +[float] +== Help me decide + +Use the decision tree below to help determine which method of configuring and running the APM Server is best for your use case. + +[subs=attributes+] +include::{observability-docs-root}/docs/en/observability/apm/diagrams/apm-decision-tree.asciidoc[APM Server decision tree] + +//// +Subsections +//// +:leveloffset: +1 +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/get-started-with-fleet-apm-server.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc[] +:leveloffset!: diff --git a/docs/en/observability/apm/how-to.asciidoc b/docs/en/observability/apm/how-to.asciidoc deleted file mode 100644 index 266c611ffd..0000000000 --- a/docs/en/observability/apm/how-to.asciidoc +++ /dev/null @@ -1,47 +0,0 @@ -[[apm-how-to-guides]] -== Perform common tasks in the APM UI - -Learn how to perform common tasks in the APM UI: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -include::../apm-ui/agent-configuration.asciidoc[] - -include::../apm-ui/apm-spaces.asciidoc[] - -include::../apm-ui/apm-alerts.asciidoc[] - -include::./source-map-how-to.asciidoc[] - -include::../apm-ui/custom-links.asciidoc[] - -include::../apm-ui/filters.asciidoc[] - -include::../apm-ui/correlations.asciidoc[] - -include::../apm-ui/agent-explorer.asciidoc[] - -include::../apm-ui/machine-learning.asciidoc[] - -include::../apm-ui/mobile-session-explorer.asciidoc[] - -include::../apm-ui/lambda.asciidoc[] - -include::../apm-ui/advanced-queries.asciidoc[] - -include::../apm-ui/storage-explorer.asciidoc[] - -include::../apm-ui/deployment-annotations.asciidoc[] diff --git a/docs/en/observability/apm-ui/images/active-alert-service.png b/docs/en/observability/apm/images/active-alert-service.png similarity index 100% rename from docs/en/observability/apm-ui/images/active-alert-service.png rename to docs/en/observability/apm/images/active-alert-service.png diff --git a/docs/en/observability/apm-ui/images/add-variable.png b/docs/en/observability/apm/images/add-variable.png similarity index 100% rename from docs/en/observability/apm-ui/images/add-variable.png rename to docs/en/observability/apm/images/add-variable.png diff --git a/docs/en/observability/apm-ui/images/advanced-discover.png b/docs/en/observability/apm/images/advanced-discover.png similarity index 100% rename from docs/en/observability/apm-ui/images/advanced-discover.png rename to docs/en/observability/apm/images/advanced-discover.png diff --git a/docs/en/observability/apm-ui/images/all-instances.png b/docs/en/observability/apm/images/all-instances.png similarity index 100% rename from docs/en/observability/apm-ui/images/all-instances.png rename to docs/en/observability/apm/images/all-instances.png diff --git a/docs/en/observability/apm-ui/images/apm-agent-configuration.png b/docs/en/observability/apm/images/apm-agent-configuration.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-agent-configuration.png rename to docs/en/observability/apm/images/apm-agent-configuration.png diff --git a/docs/en/observability/apm-ui/images/apm-agent-explorer-flyout.png b/docs/en/observability/apm/images/apm-agent-explorer-flyout.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-agent-explorer-flyout.png rename to docs/en/observability/apm/images/apm-agent-explorer-flyout.png diff --git a/docs/en/observability/apm-ui/images/apm-agent-explorer.png b/docs/en/observability/apm/images/apm-agent-explorer.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-agent-explorer.png rename to docs/en/observability/apm/images/apm-agent-explorer.png diff --git a/docs/en/observability/apm-ui/images/apm-alert.png b/docs/en/observability/apm/images/apm-alert.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-alert.png rename to docs/en/observability/apm/images/apm-alert.png diff --git a/docs/en/observability/apm-ui/images/apm-anomaly-alert.png b/docs/en/observability/apm/images/apm-anomaly-alert.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-anomaly-alert.png rename to docs/en/observability/apm/images/apm-anomaly-alert.png diff --git a/docs/en/observability/apm-ui/images/apm-distributed-tracing.png b/docs/en/observability/apm/images/apm-distributed-tracing-apm-ui.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-distributed-tracing.png rename to docs/en/observability/apm/images/apm-distributed-tracing-apm-ui.png diff --git a/docs/en/observability/apm-ui/images/apm-error-group.png b/docs/en/observability/apm/images/apm-error-group.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-error-group.png rename to docs/en/observability/apm/images/apm-error-group.png diff --git a/docs/en/observability/apm-ui/images/apm-errors-overview.png b/docs/en/observability/apm/images/apm-errors-overview.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-errors-overview.png rename to docs/en/observability/apm/images/apm-errors-overview.png diff --git a/docs/en/observability/apm-ui/images/apm-errors-watcher-assistant.png b/docs/en/observability/apm/images/apm-errors-watcher-assistant.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-errors-watcher-assistant.png rename to docs/en/observability/apm/images/apm-errors-watcher-assistant.png diff --git a/docs/en/observability/apm-ui/images/apm-geo-ui.png b/docs/en/observability/apm/images/apm-geo-ui.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-geo-ui.png rename to docs/en/observability/apm/images/apm-geo-ui.png diff --git a/docs/en/observability/apm-ui/images/apm-index-pattern.png b/docs/en/observability/apm/images/apm-index-pattern.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-index-pattern.png rename to docs/en/observability/apm/images/apm-index-pattern.png diff --git a/docs/en/observability/apm-ui/images/apm-integration-config.png b/docs/en/observability/apm/images/apm-integration-config.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-integration-config.png rename to docs/en/observability/apm/images/apm-integration-config.png diff --git a/docs/en/observability/apm-ui/images/apm-logs-tab.png b/docs/en/observability/apm/images/apm-logs-tab.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-logs-tab.png rename to docs/en/observability/apm/images/apm-logs-tab.png diff --git a/docs/en/observability/apm-ui/images/apm-metrics.png b/docs/en/observability/apm/images/apm-metrics.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-metrics.png rename to docs/en/observability/apm/images/apm-metrics.png diff --git a/docs/en/observability/apm-ui/images/apm-ml-integration.png b/docs/en/observability/apm/images/apm-ml-integration.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-ml-integration.png rename to docs/en/observability/apm/images/apm-ml-integration.png diff --git a/docs/en/observability/apm-ui/images/apm-query-bar.png b/docs/en/observability/apm/images/apm-query-bar.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-query-bar.png rename to docs/en/observability/apm/images/apm-query-bar.png diff --git a/docs/en/observability/apm-ui/images/apm-roles-config.png b/docs/en/observability/apm/images/apm-roles-config.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-roles-config.png rename to docs/en/observability/apm/images/apm-roles-config.png diff --git a/docs/en/observability/apm-ui/images/apm-service-group.png b/docs/en/observability/apm/images/apm-service-group.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-service-group.png rename to docs/en/observability/apm/images/apm-service-group.png diff --git a/docs/en/observability/apm-ui/images/apm-service-map-anomaly.png b/docs/en/observability/apm/images/apm-service-map-anomaly.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-service-map-anomaly.png rename to docs/en/observability/apm/images/apm-service-map-anomaly.png diff --git a/docs/en/observability/apm-ui/images/apm-services-overview.png b/docs/en/observability/apm/images/apm-services-overview.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-services-overview.png rename to docs/en/observability/apm/images/apm-services-overview.png diff --git a/docs/en/observability/apm-ui/images/apm-services-trace.png b/docs/en/observability/apm/images/apm-services-trace.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-services-trace.png rename to docs/en/observability/apm/images/apm-services-trace.png diff --git a/docs/en/observability/apm-ui/images/apm-settings.png b/docs/en/observability/apm/images/apm-settings.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-settings.png rename to docs/en/observability/apm/images/apm-settings.png diff --git a/docs/en/observability/apm-ui/images/apm-setup.png b/docs/en/observability/apm/images/apm-setup.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-setup.png rename to docs/en/observability/apm/images/apm-setup.png diff --git a/docs/en/observability/apm-ui/images/apm-span-detail.png b/docs/en/observability/apm/images/apm-span-detail.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-span-detail.png rename to docs/en/observability/apm/images/apm-span-detail.png diff --git a/docs/en/observability/apm-ui/images/apm-traces.png b/docs/en/observability/apm/images/apm-traces.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-traces.png rename to docs/en/observability/apm/images/apm-traces.png diff --git a/docs/en/observability/apm-ui/images/apm-transaction-annotation.png b/docs/en/observability/apm/images/apm-transaction-annotation.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-transaction-annotation.png rename to docs/en/observability/apm/images/apm-transaction-annotation.png diff --git a/docs/en/observability/apm-ui/images/apm-transaction-duration-dist.png b/docs/en/observability/apm/images/apm-transaction-duration-dist.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-transaction-duration-dist.png rename to docs/en/observability/apm/images/apm-transaction-duration-dist.png diff --git a/docs/en/observability/apm-ui/images/apm-transaction-response-dist.png b/docs/en/observability/apm/images/apm-transaction-response-dist.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-transaction-response-dist.png rename to docs/en/observability/apm/images/apm-transaction-response-dist.png diff --git a/docs/en/observability/apm-ui/images/apm-transaction-sample.png b/docs/en/observability/apm/images/apm-transaction-sample.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-transaction-sample.png rename to docs/en/observability/apm/images/apm-transaction-sample.png diff --git a/docs/en/observability/apm-ui/images/apm-transactions-overview.png b/docs/en/observability/apm/images/apm-transactions-overview.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-transactions-overview.png rename to docs/en/observability/apm/images/apm-transactions-overview.png diff --git a/docs/en/observability/apm-ui/images/apm-transactions-table.png b/docs/en/observability/apm/images/apm-transactions-table.png similarity index 100% rename from docs/en/observability/apm-ui/images/apm-transactions-table.png rename to docs/en/observability/apm/images/apm-transactions-table.png diff --git a/docs/en/observability/apm-ui/images/correlations-failed-transactions.png b/docs/en/observability/apm/images/correlations-failed-transactions.png similarity index 100% rename from docs/en/observability/apm-ui/images/correlations-failed-transactions.png rename to docs/en/observability/apm/images/correlations-failed-transactions.png diff --git a/docs/en/observability/apm-ui/images/correlations-hover.png b/docs/en/observability/apm/images/correlations-hover.png similarity index 100% rename from docs/en/observability/apm-ui/images/correlations-hover.png rename to docs/en/observability/apm/images/correlations-hover.png diff --git a/docs/en/observability/apm-ui/images/create-github-issue.png b/docs/en/observability/apm/images/create-github-issue.png similarity index 100% rename from docs/en/observability/apm-ui/images/create-github-issue.png rename to docs/en/observability/apm/images/create-github-issue.png diff --git a/docs/en/observability/apm-ui/images/create-jira-issue.png b/docs/en/observability/apm/images/create-jira-issue.png similarity index 100% rename from docs/en/observability/apm-ui/images/create-jira-issue.png rename to docs/en/observability/apm/images/create-jira-issue.png diff --git a/docs/en/observability/apm-ui/images/dependencies-drilldown.png b/docs/en/observability/apm/images/dependencies-drilldown.png similarity index 100% rename from docs/en/observability/apm-ui/images/dependencies-drilldown.png rename to docs/en/observability/apm/images/dependencies-drilldown.png diff --git a/docs/en/observability/apm-ui/images/dependencies.png b/docs/en/observability/apm/images/dependencies.png similarity index 100% rename from docs/en/observability/apm-ui/images/dependencies.png rename to docs/en/observability/apm/images/dependencies.png diff --git a/docs/en/observability/apm/images/diagram-of-a-trace.png b/docs/en/observability/apm/images/diagram-of-a-trace.png new file mode 100644 index 0000000000..a80dd9d0fb Binary files /dev/null and b/docs/en/observability/apm/images/diagram-of-a-trace.png differ diff --git a/docs/en/observability/apm/images/distributed-traces.png b/docs/en/observability/apm/images/distributed-traces.png new file mode 100644 index 0000000000..14c32a7e00 Binary files /dev/null and b/docs/en/observability/apm/images/distributed-traces.png differ diff --git a/docs/en/observability/apm-ui/images/dynamic-config.svg b/docs/en/observability/apm/images/dynamic-config.svg similarity index 100% rename from docs/en/observability/apm-ui/images/dynamic-config.svg rename to docs/en/observability/apm/images/dynamic-config.svg diff --git a/docs/en/observability/apm-ui/images/error-rate.png b/docs/en/observability/apm/images/error-rate.png similarity index 100% rename from docs/en/observability/apm-ui/images/error-rate.png rename to docs/en/observability/apm/images/error-rate.png diff --git a/docs/en/observability/apm-ui/images/example-metadata.png b/docs/en/observability/apm/images/example-metadata.png similarity index 100% rename from docs/en/observability/apm-ui/images/example-metadata.png rename to docs/en/observability/apm/images/example-metadata.png diff --git a/docs/en/observability/apm-ui/images/global-filters.png b/docs/en/observability/apm/images/global-filters.png similarity index 100% rename from docs/en/observability/apm-ui/images/global-filters.png rename to docs/en/observability/apm/images/global-filters.png diff --git a/docs/en/observability/apm-ui/images/green-service.png b/docs/en/observability/apm/images/green-service.png similarity index 100% rename from docs/en/observability/apm-ui/images/green-service.png rename to docs/en/observability/apm/images/green-service.png diff --git a/docs/en/observability/apm-ui/images/infra.png b/docs/en/observability/apm/images/infra.png similarity index 100% rename from docs/en/observability/apm-ui/images/infra.png rename to docs/en/observability/apm/images/infra.png diff --git a/docs/en/observability/apm-ui/images/jvm-metrics-overview.png b/docs/en/observability/apm/images/jvm-metrics-overview.png similarity index 100% rename from docs/en/observability/apm-ui/images/jvm-metrics-overview.png rename to docs/en/observability/apm/images/jvm-metrics-overview.png diff --git a/docs/en/observability/apm-ui/images/jvm-metrics.png b/docs/en/observability/apm/images/jvm-metrics.png similarity index 100% rename from docs/en/observability/apm-ui/images/jvm-metrics.png rename to docs/en/observability/apm/images/jvm-metrics.png diff --git a/docs/en/observability/apm-ui/images/lambda-cold-start-trace.png b/docs/en/observability/apm/images/lambda-cold-start-trace.png similarity index 100% rename from docs/en/observability/apm-ui/images/lambda-cold-start-trace.png rename to docs/en/observability/apm/images/lambda-cold-start-trace.png diff --git a/docs/en/observability/apm-ui/images/lambda-correlations.png b/docs/en/observability/apm/images/lambda-correlations.png similarity index 100% rename from docs/en/observability/apm-ui/images/lambda-correlations.png rename to docs/en/observability/apm/images/lambda-correlations.png diff --git a/docs/en/observability/apm-ui/images/lambda-overview.png b/docs/en/observability/apm/images/lambda-overview.png similarity index 100% rename from docs/en/observability/apm-ui/images/lambda-overview.png rename to docs/en/observability/apm/images/lambda-overview.png diff --git a/docs/en/observability/apm-ui/images/latency.png b/docs/en/observability/apm/images/latency.png similarity index 100% rename from docs/en/observability/apm-ui/images/latency.png rename to docs/en/observability/apm/images/latency.png diff --git a/docs/en/observability/apm-ui/images/local-filter.png b/docs/en/observability/apm/images/local-filter.png similarity index 100% rename from docs/en/observability/apm-ui/images/local-filter.png rename to docs/en/observability/apm/images/local-filter.png diff --git a/docs/en/observability/apm-ui/images/logs.png b/docs/en/observability/apm/images/logs.png similarity index 100% rename from docs/en/observability/apm-ui/images/logs.png rename to docs/en/observability/apm/images/logs.png diff --git a/docs/en/observability/apm-ui/images/metadata-icons.png b/docs/en/observability/apm/images/metadata-icons.png similarity index 100% rename from docs/en/observability/apm-ui/images/metadata-icons.png rename to docs/en/observability/apm/images/metadata-icons.png diff --git a/docs/en/observability/apm-ui/images/mobile-location.png b/docs/en/observability/apm/images/mobile-location.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-location.png rename to docs/en/observability/apm/images/mobile-location.png diff --git a/docs/en/observability/apm-ui/images/mobile-most-used.png b/docs/en/observability/apm/images/mobile-most-used.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-most-used.png rename to docs/en/observability/apm/images/mobile-most-used.png diff --git a/docs/en/observability/apm-ui/images/mobile-session-error-details.png b/docs/en/observability/apm/images/mobile-session-error-details.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-session-error-details.png rename to docs/en/observability/apm/images/mobile-session-error-details.png diff --git a/docs/en/observability/apm-ui/images/mobile-session-explorer-apm.png b/docs/en/observability/apm/images/mobile-session-explorer-apm.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-session-explorer-apm.png rename to docs/en/observability/apm/images/mobile-session-explorer-apm.png diff --git a/docs/en/observability/apm-ui/images/mobile-session-explorer-nav.png b/docs/en/observability/apm/images/mobile-session-explorer-nav.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-session-explorer-nav.png rename to docs/en/observability/apm/images/mobile-session-explorer-nav.png diff --git a/docs/en/observability/apm-ui/images/mobile-session-filter-discover.png b/docs/en/observability/apm/images/mobile-session-filter-discover.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-session-filter-discover.png rename to docs/en/observability/apm/images/mobile-session-filter-discover.png diff --git a/docs/en/observability/apm-ui/images/mobile-tp.png b/docs/en/observability/apm/images/mobile-tp.png similarity index 100% rename from docs/en/observability/apm-ui/images/mobile-tp.png rename to docs/en/observability/apm/images/mobile-tp.png diff --git a/docs/en/observability/apm-ui/images/operations-detail.png b/docs/en/observability/apm/images/operations-detail.png similarity index 100% rename from docs/en/observability/apm-ui/images/operations-detail.png rename to docs/en/observability/apm/images/operations-detail.png diff --git a/docs/en/observability/apm-ui/images/operations.png b/docs/en/observability/apm/images/operations.png similarity index 100% rename from docs/en/observability/apm-ui/images/operations.png rename to docs/en/observability/apm/images/operations.png diff --git a/docs/en/observability/apm-ui/images/red-service.png b/docs/en/observability/apm/images/red-service.png similarity index 100% rename from docs/en/observability/apm-ui/images/red-service.png rename to docs/en/observability/apm/images/red-service.png diff --git a/docs/en/observability/apm-ui/images/service-maps-java.png b/docs/en/observability/apm/images/service-maps-java.png similarity index 100% rename from docs/en/observability/apm-ui/images/service-maps-java.png rename to docs/en/observability/apm/images/service-maps-java.png diff --git a/docs/en/observability/apm-ui/images/service-maps.png b/docs/en/observability/apm/images/service-maps.png similarity index 100% rename from docs/en/observability/apm-ui/images/service-maps.png rename to docs/en/observability/apm/images/service-maps.png diff --git a/docs/en/observability/apm-ui/images/service-quick-health.png b/docs/en/observability/apm/images/service-quick-health.png similarity index 100% rename from docs/en/observability/apm-ui/images/service-quick-health.png rename to docs/en/observability/apm/images/service-quick-health.png diff --git a/docs/en/observability/apm-ui/images/spans-dependencies.png b/docs/en/observability/apm/images/spans-dependencies.png similarity index 100% rename from docs/en/observability/apm-ui/images/spans-dependencies.png rename to docs/en/observability/apm/images/spans-dependencies.png diff --git a/docs/en/observability/apm/images/spans-transactions-and-traces.png b/docs/en/observability/apm/images/spans-transactions-and-traces.png new file mode 100644 index 0000000000..06badc4454 Binary files /dev/null and b/docs/en/observability/apm/images/spans-transactions-and-traces.png differ diff --git a/docs/en/observability/apm-ui/images/specific-transaction-search.png b/docs/en/observability/apm/images/specific-transaction-search.png similarity index 100% rename from docs/en/observability/apm-ui/images/specific-transaction-search.png rename to docs/en/observability/apm/images/specific-transaction-search.png diff --git a/docs/en/observability/apm-ui/images/specific-transaction.png b/docs/en/observability/apm/images/specific-transaction.png similarity index 100% rename from docs/en/observability/apm-ui/images/specific-transaction.png rename to docs/en/observability/apm/images/specific-transaction.png diff --git a/docs/en/observability/apm-ui/images/storage-explorer-expanded.png b/docs/en/observability/apm/images/storage-explorer-expanded.png similarity index 100% rename from docs/en/observability/apm-ui/images/storage-explorer-expanded.png rename to docs/en/observability/apm/images/storage-explorer-expanded.png diff --git a/docs/en/observability/apm-ui/images/storage-explorer-overview.png b/docs/en/observability/apm/images/storage-explorer-overview.png similarity index 100% rename from docs/en/observability/apm-ui/images/storage-explorer-overview.png rename to docs/en/observability/apm/images/storage-explorer-overview.png diff --git a/docs/en/observability/apm-ui/images/time-series-expected-bounds-comparison.png b/docs/en/observability/apm/images/time-series-expected-bounds-comparison.png similarity index 100% rename from docs/en/observability/apm-ui/images/time-series-expected-bounds-comparison.png rename to docs/en/observability/apm/images/time-series-expected-bounds-comparison.png diff --git a/docs/en/observability/apm-ui/images/trace-explorer.png b/docs/en/observability/apm/images/trace-explorer.png similarity index 100% rename from docs/en/observability/apm-ui/images/trace-explorer.png rename to docs/en/observability/apm/images/trace-explorer.png diff --git a/docs/en/observability/apm-ui/images/traffic-transactions.png b/docs/en/observability/apm/images/traffic-transactions.png similarity index 100% rename from docs/en/observability/apm-ui/images/traffic-transactions.png rename to docs/en/observability/apm/images/traffic-transactions.png diff --git a/docs/en/observability/apm-ui/images/transaction-icon.png b/docs/en/observability/apm/images/transaction-icon.png similarity index 100% rename from docs/en/observability/apm-ui/images/transaction-icon.png rename to docs/en/observability/apm/images/transaction-icon.png diff --git a/docs/en/observability/apm-ui/images/yellow-service.png b/docs/en/observability/apm/images/yellow-service.png similarity index 100% rename from docs/en/observability/apm-ui/images/yellow-service.png rename to docs/en/observability/apm/images/yellow-service.png diff --git a/docs/en/observability/apm/log-correlation.asciidoc b/docs/en/observability/apm/log-correlation.asciidoc deleted file mode 100644 index 8735b4049e..0000000000 --- a/docs/en/observability/apm/log-correlation.asciidoc +++ /dev/null @@ -1,11 +0,0 @@ -[[apm-log-correlation]] -=== Logging integration - -Elastic APM integrates with popular logging frameworks, making it easy to correlate your logs and traces. -This enables you to: - -- view the context of a log and the parameters provided by a user -- view all logs belonging to a particular trace -- easily move between logs and traces when debugging application issues - -See the <> guide to get started. \ No newline at end of file diff --git a/docs/en/observability/apm/manage-storage.asciidoc b/docs/en/observability/apm/manage-storage.asciidoc deleted file mode 100644 index f2817b1732..0000000000 --- a/docs/en/observability/apm/manage-storage.asciidoc +++ /dev/null @@ -1,216 +0,0 @@ -[[apm-manage-storage]] -== Manage storage - -{agent} uses <> to store time series data across multiple indices. -<> are used to configure the backing indices of data streams as they are created. -Each data stream ships with a customizable <> that automates data retention as your indices grow and age. -Use <> to process and enrich APM documents before indexing them. - -The <> attempts to define a "typical" storage reference for Elastic APM, -and there are additional settings you can tweak to <>, -or to <>. - -In addition, the APM UI makes it easy to visualize your APM data usage with -<>. -Storage explorer allows you to analyze the storage footprint of each of your services to see -which are producing large amounts of data--so you can better reduce the data you're collecting -or forecast and prepare for future storage needs. - -include::./data-streams.asciidoc[] - -include::./ilm-how-to.asciidoc[] - -include::./custom-index-template.asciidoc[] - -include::./ingest-pipelines.asciidoc[] - -[[apm-storage-guide]] -=== Storage and sizing guide - -APM processing and storage costs are largely dominated by transactions, spans, and stack frames. - -* <> describe an event captured by an Elastic {apm-agent} instrumenting a service. -They are the highest level of work being measuring within a service. -* <> belong to transactions. They measure from the start to end of an activity, -and contain information about a specific code path that has been executed. -* *Stack frames* belong to spans. Stack frames represent a function call on the call stack, -and include attributes like function name, file name and path, line number, etc. -Stack frames can heavily influence the size of a span. - -[float] -==== Typical transactions - -Due to the high variability of APM data, it's difficult to classify a transaction as typical. -Regardless, this guide will attempt to classify Transactions as _Small_, _Medium_, or _Large_, -and make recommendations based on those classifications. - -The size of a transaction depends on the language, agent settings, and what services the agent instruments. -For instance, an agent auto-instrumenting a service with a popular tech stack -(web framework, database, caching library, etc.) is more likely to generate bigger transactions. - -In addition, all agents support manual instrumentation. -How little or much you use these APIs will also impact what a typical transaction looks like. - -If your sampling rate is very small, transactions will be the dominate storage cost. - -Here's a speculative reference: - -[options="header"] -|======================================================================= -|Transaction size |Number of Spans |Number of stack frames -|_Small_ |5-10 |5-10 -|_Medium_ |15-20 |15-20 -|_Large_ |30-40 |30-40 -|======================================================================= - -There will always be transaction outliers with hundreds of spans or stack frames, but those are very rare. -Small transactions are the most common. - -[float] -==== Typical storage - -Consider the following typical storage reference. -These numbers do not account for {es} compression. - -* 1 unsampled transaction is **~1 KB** -* 1 span with 10 stack frames is **~4 KB** -* 1 span with 50 stack frames is **~20 KB** -* 1 transaction with 10 spans, each with 10 stack frames is **~50 KB** -* 1 transaction with 25 spans, each with 25 spans is **250-300 KB** -* 100 transactions with 10 spans, each with 10 stack frames, sampled at 90% is **600 KB** - -APM data compresses quite well, so the storage cost in {es} 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 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. - -[[apm-reduce-apm-storage]] -=== Reduce storage - -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. - -Here are some ways you can reduce either the amount of APM data you're ingesting -or the amount of data you're retaining. - -[float] -[[apm-reduce-sample-rate]] -==== Reduce the sample rate - -Distributed tracing can generate a substantial amount of data. -More data can mean higher costs and more noise. -Sampling aims to lower the amount of data ingested and the effort required to analyze that data. - -See <> to learn more. - -[float] -==== Enable span compression - -In some cases, APM agents may collect large amounts of very similar or identical spans in a transaction. -These repeated, similar spans often don't provide added benefit, especially if they are of very short duration. -Span compression takes these similar spans and compresses them into a single span-- -retaining important information but reducing processing and storage overhead. - -See <> to learn more. - -[float] -[[apm-reduce-stacktrace]] -==== Reduce collected stack trace information - -Elastic APM agents collect `stacktrace` information under certain circumstances. -This can be very helpful in identifying issues in your code, -but it also comes with an overhead at collection time and increases the storage usage. - -Stack trace collection settings are managed in each agent. - -[float] -==== Delete data - -You might want to only keep data for a defined time period. -This might mean deleting old documents periodically, -deleting data collected for specific services or customers, -or deleting specific indices. - -Depending on your use case, you can delete data: - -* periodically with <> -* <> -* with the <> - -If you want to delete data for security or privacy reasons, see <>. - -[float] -[[apm-delete-data-with-ilm]] -===== Delete data with {ilm} ({ilm-init}) - -Index lifecycle management enables you to automate how you want to manage your indices over time. -You can base actions on factors such as shard size and performance requirements. -See <> to learn more. - -[float] -[[apm-delete-data-query]] -===== Delete data matching a query - -You can delete all APM documents matching a specific query with the {ref}/docs-delete-by-query.html[Delete By Query API]. -For example, to delete all documents with a given `service.name`, use the following request: - -["source","console"] ----- -POST /.ds-*-apm*/_delete_by_query -{ - "query": { - "term": { - "service.name": { - "value": "old-service-name" - } - } - } -} ----- - -[float] -[[apm-delete-data-in-kibana]] -===== Delete data with {kib} Index Management - -{kib}'s {ref}/index-mgmt.html[Index Management] allows you to manage your cluster's -indices, data streams, index templates, and much more. - -In {kib}, navigate to **Stack Management** > **Index Management** > **Data Streams**. -Select the data streams you want to delete, and click **Delete data streams**. - -[float] -[[apm-update-data]] -==== Update existing data - -You might want to update documents that are already indexed. -For example, if you your service name was set incorrectly. - -To do this, you can use the {ref}/docs-update-by-query.html[Update By Query API]. -To rename a service, send the following request: - -["source","sh"] ------------------------------------------------------------- -POST /.ds-*-apm*/_update_by_query?expand_wildcards=all -{ - "query": { - "term": { - "service.name": { - "value": "current-service-name" - } - } - }, - "script": { - "source": "ctx._source.service.name = 'new-service-name'", - "lang": "painless" - } -} ------------------------------------------------------------- -// CONSOLE - -TIP: Remember to also change the service name in the {apm-agents-ref}/index.html[{apm-agent} configuration]. - -include::{observability-docs-root}/docs/en/observability/apm/exploring-es-data.asciidoc[leveloffset=+2] diff --git a/docs/en/observability/apm/custom-index-template.asciidoc b/docs/en/observability/apm/manage-storage/custom-index-template.asciidoc similarity index 96% rename from docs/en/observability/apm/custom-index-template.asciidoc rename to docs/en/observability/apm/manage-storage/custom-index-template.asciidoc index ff83ae2e3e..51e47e3e93 100644 --- a/docs/en/observability/apm/custom-index-template.asciidoc +++ b/docs/en/observability/apm/manage-storage/custom-index-template.asciidoc @@ -5,7 +5,7 @@ ////////////////////////////////////////////////////////////////////////// [[apm-custom-index-template]] -=== View the {es} index template += View the {es} index template :append-legacy: // tag::index-template-integration[] @@ -20,7 +20,7 @@ Select any of the APM index templates to view their relevant component templates [discrete] [id="index-template-view{append-legacy}"] -=== Edit the {es} index template +== Edit the {es} index template WARNING: Custom index mappings may conflict with the mappings defined by the {es} apm-data plugin and may break the APM integration and APM UI in {kib}. @@ -42,7 +42,7 @@ Add any custom metadata, index settings, or mappings. [discrete] [[apm-custom-index-template-index-settings]] -==== Index settings +=== Index settings In the **Index settings** step, you can specify custom {ref}/index-modules.html#index-modules-settings[index settings]. For example, you could: @@ -76,7 +76,7 @@ Specify the number of replica shards: [discrete] [[apm-custom-index-template-mappings]] -==== Mappings +=== Mappings {ref}/mapping.html[Mapping] is the process of defining how a document, and the fields it contains, are stored and indexed. In the *Mappings* step, you can add custom field mappings. @@ -95,7 +95,7 @@ image::images/custom-index-template-runtime-fields.png[Editing a component templ [discrete] [[apm-custom-index-template-rollover]] -=== Roll over the data stream +== Roll over the data stream Changes to component templates are not applied retroactively to existing indices. For changes to take effect, you must create a new write index for the data stream. diff --git a/docs/en/observability/apm/data-streams.asciidoc b/docs/en/observability/apm/manage-storage/data-streams.asciidoc similarity index 97% rename from docs/en/observability/apm/data-streams.asciidoc rename to docs/en/observability/apm/manage-storage/data-streams.asciidoc index c5389aa4a8..682da3c402 100644 --- a/docs/en/observability/apm/data-streams.asciidoc +++ b/docs/en/observability/apm/manage-storage/data-streams.asciidoc @@ -1,5 +1,5 @@ [[apm-data-streams]] -=== Data streams += Data streams **** {agent} uses data streams to store append-only time series data across multiple indices. @@ -16,7 +16,7 @@ See the {fleet-guide}/data-streams.html[{fleet} and {agent} Guide] to learn more [discrete] [[apm-data-streams-naming-scheme]] -=== Data stream naming scheme +== Data stream naming scheme // tag::data-streams[] APM data follows the `--` naming scheme. @@ -30,7 +30,7 @@ Or, you might create namespaces that correspond to strategic business units with [discrete] [[apm-data-streams-list]] -=== APM data streams +== APM data streams By type, the APM data streams are: @@ -87,7 +87,7 @@ Logs are stored in the following data streams: [discrete] [[apm-data-stream-rerouting]] -=== APM data stream rerouting +== APM data stream rerouting APM supports rerouting APM data to user-defined APM data stream names other than the defaults. This can be achieved by using a {ref}/reroute-processor.html[`reroute` processor] in ingest pipelines to set the data stream dataset or namespace. @@ -116,7 +116,7 @@ For more custom APM ingest pipeline guides, see <> to learn how to create your own data retention policies. diff --git a/docs/en/observability/apm/exploring-es-data.asciidoc b/docs/en/observability/apm/manage-storage/exploring-es-data.asciidoc similarity index 100% rename from docs/en/observability/apm/exploring-es-data.asciidoc rename to docs/en/observability/apm/manage-storage/exploring-es-data.asciidoc diff --git a/docs/en/observability/apm/ilm-how-to.asciidoc b/docs/en/observability/apm/manage-storage/ilm-how-to.asciidoc similarity index 95% rename from docs/en/observability/apm/ilm-how-to.asciidoc rename to docs/en/observability/apm/manage-storage/ilm-how-to.asciidoc index 59d57bcbff..12d54c67d1 100644 --- a/docs/en/observability/apm/ilm-how-to.asciidoc +++ b/docs/en/observability/apm/manage-storage/ilm-how-to.asciidoc @@ -3,7 +3,7 @@ ////////////////////////////////////////////////////////////////////////// [[apm-ilm-how-to]] -=== {ilm-cap} += {ilm-cap} :append-legacy: // tag::ilm-integration[] @@ -17,7 +17,7 @@ See {ref}/index-lifecycle-management.html[{ilm-init}: Manage the index lifecycle [discrete] [id="index-lifecycle-policies-default{append-legacy}"] -=== Default policies +== Default policies The table below describes the default index lifecycle policy applied to each APM data stream. Each policy includes a rollover and delete definition: @@ -132,7 +132,7 @@ This is not considered a breaking change as index management should continually [discrete] [id="apm-data-streams-custom-policy{append-legacy}"] -=== Configure a custom index lifecycle policy +== Configure a custom index lifecycle policy When the APM integration is installed, {fleet} creates a default `*@custom` component template for each data stream. The easiest way to configure a custom index lifecycle policy per data stream is to edit this template. @@ -141,7 +141,7 @@ This tutorial explains how to apply a custom index lifecycle policy to the `trac [discrete] [id="apm-data-streams-custom-one{append-legacy}"] -=== Step 1: View data streams +== Step 1: View data streams The **Data Streams** view in {kib} shows you the data streams, index templates, and index lifecycle policies associated with a given integration. @@ -156,7 +156,7 @@ image::images/data-stream-overview.png[Data streams info] [discrete] [id="apm-data-streams-custom-two{append-legacy}"] -=== Step 2: Create an index lifecycle policy +== Step 2: Create an index lifecycle policy . Navigate to **{stack-manage-app}** > **Index Lifecycle Policies**. . Click **Create policy**. @@ -166,7 +166,7 @@ Customize the policy to your liking, and when you're done, click **Save policy** [discrete] [id="apm-data-streams-custom-three{append-legacy}"] -=== Step 3: Apply the index lifecycle policy +== Step 3: Apply the index lifecycle policy To apply your new index lifecycle policy to the `traces-apm-*` data stream, edit the `@custom` component template. @@ -191,7 +191,7 @@ image::images/create-component-template.png[Create component template] [discrete] [id="apm-data-streams-custom-four{append-legacy}"] -=== Step 4: Roll over the data stream (optional) +== Step 4: Roll over the data stream (optional) To confirm that the data stream is now using the new index template and {ilm-init} policy, you can either repeat <>, or navigate to **{dev-tools-app}** and run the following: @@ -231,7 +231,7 @@ POST /traces-apm-default/_rollover/ [discrete] [id="apm-data-streams-custom-policy-namespace{append-legacy}"] -=== Namespace-level index lifecycle policies +== Namespace-level index lifecycle policies It is also possible to create more granular index lifecycle policies that apply to individual namespaces. This process is similar to the above tutorial, but includes cloning and modify the existing index template to use diff --git a/docs/en/observability/apm/manage-storage/index.asciidoc b/docs/en/observability/apm/manage-storage/index.asciidoc new file mode 100644 index 0000000000..aa73b774d8 --- /dev/null +++ b/docs/en/observability/apm/manage-storage/index.asciidoc @@ -0,0 +1,37 @@ +[[apm-manage-storage]] += Manage storage + +{agent} uses <> to store time series data across multiple indices. +<> are used to configure the backing indices of data streams as they are created. +Each data stream ships with a customizable <> that automates data retention as your indices grow and age. +Use <> to process and enrich APM documents before indexing them. + +The <> attempts to define a "typical" storage reference for Elastic APM, +and there are additional settings you can tweak to <>, +or to <>. + +In addition, the APM UI makes it easy to visualize your APM data usage with +<>. +Storage explorer allows you to analyze the storage footprint of each of your services to see +which are producing large amounts of data--so you can better reduce the data you're collecting +or forecast and prepare for future storage needs. + +:leveloffset: +1 + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/storage-explorer.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/ilm-how-to.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/custom-index-template.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/ingest-pipelines.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/storage-and-sizing.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/reduce-apm-storage.asciidoc[] + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/exploring-es-data.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm/ingest-pipelines.asciidoc b/docs/en/observability/apm/manage-storage/ingest-pipelines.asciidoc similarity index 85% rename from docs/en/observability/apm/ingest-pipelines.asciidoc rename to docs/en/observability/apm/manage-storage/ingest-pipelines.asciidoc index 01353e8258..fdbf6d7b74 100644 --- a/docs/en/observability/apm/ingest-pipelines.asciidoc +++ b/docs/en/observability/apm/manage-storage/ingest-pipelines.asciidoc @@ -3,7 +3,7 @@ ////////////////////////////////////////////////////////////////////////// [[apm-ingest-pipelines]] -=== Parse data using ingest pipelines += Parse data using ingest pipelines :append-legacy: // tag::ingest-pipelines[] @@ -17,7 +17,7 @@ The default APM pipelines are defined in {es} apm-data plugin index templates. [discrete] [id="custom-ingest-pipelines{append-legacy}"] -=== Custom ingest pipelines +== Custom ingest pipelines The Elastic APM integration supports custom ingest pipelines. A custom pipeline allows you to transform data to better match your specific use case. @@ -33,15 +33,15 @@ Sending other APM data to alternate data streams, like traces (`traces-apm.*`), [discrete] [id="custom-ingest-pipeline-naming{append-legacy}"] -=== `@custom` ingest pipeline naming convention +== `@custom` ingest pipeline naming convention // tag::ingest-pipeline-naming[] `@custom` pipelines are specific to each data stream and follow a similar naming convention: `-@custom`. As a reminder, the default APM data streams are: -include::./data-streams.asciidoc[tag=traces-data-streams] -include::./data-streams.asciidoc[tag=metrics-data-streams] -include::./data-streams.asciidoc[tag=logs-data-streams] +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=traces-data-streams] +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=metrics-data-streams] +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/data-streams.asciidoc[tag=logs-data-streams] To match a custom ingest pipeline with a data stream, follow the `-@custom` template, or replace `-namespace` with `@custom` in the table above. @@ -54,7 +54,7 @@ The `@custom` pipeline will persist across all version upgrades. [discrete] [id="custom-ingest-pipeline-create{append-legacy}"] -=== Create a `@custom` ingest pipeline +== Create a `@custom` ingest pipeline The process for creating a custom ingest pipeline is as follows: diff --git a/docs/en/observability/apm/manage-storage/reduce-apm-storage.asciidoc b/docs/en/observability/apm/manage-storage/reduce-apm-storage.asciidoc new file mode 100644 index 0000000000..7b58dd4d14 --- /dev/null +++ b/docs/en/observability/apm/manage-storage/reduce-apm-storage.asciidoc @@ -0,0 +1,125 @@ +[[apm-reduce-apm-storage]] += Reduce storage + +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. + +Here are some ways you can reduce either the amount of APM data you're ingesting +or the amount of data you're retaining. + +[float] +[[apm-reduce-sample-rate]] +== Reduce the sample rate + +Distributed tracing can generate a substantial amount of data. +More data can mean higher costs and more noise. +Sampling aims to lower the amount of data ingested and the effort required to analyze that data. + +See <> to learn more. + +[float] +== Enable span compression + +In some cases, APM agents may collect large amounts of very similar or identical spans in a transaction. +These repeated, similar spans often don't provide added benefit, especially if they are of very short duration. +Span compression takes these similar spans and compresses them into a single span-- +retaining important information but reducing processing and storage overhead. + +See <> to learn more. + +[float] +[[apm-reduce-stacktrace]] +== Reduce collected stack trace information + +Elastic APM agents collect `stacktrace` information under certain circumstances. +This can be very helpful in identifying issues in your code, +but it also comes with an overhead at collection time and increases the storage usage. + +Stack trace collection settings are managed in each agent. + +[float] +== Delete data + +You might want to only keep data for a defined time period. +This might mean deleting old documents periodically, +deleting data collected for specific services or customers, +or deleting specific indices. + +Depending on your use case, you can delete data: + +* periodically with <> +* <> +* with the <> + +If you want to delete data for security or privacy reasons, see <>. + +[float] +[[apm-delete-data-with-ilm]] +=== Delete data with {ilm} ({ilm-init}) + +Index lifecycle management enables you to automate how you want to manage your indices over time. +You can base actions on factors such as shard size and performance requirements. +See <> to learn more. + +[float] +[[apm-delete-data-query]] +=== Delete data matching a query + +You can delete all APM documents matching a specific query with the {ref}/docs-delete-by-query.html[Delete By Query API]. +For example, to delete all documents with a given `service.name`, use the following request: + +["source","console"] +---- +POST /.ds-*-apm*/_delete_by_query +{ + "query": { + "term": { + "service.name": { + "value": "old-service-name" + } + } + } +} +---- + +[float] +[[apm-delete-data-in-kibana]] +=== Delete data with {kib} Index Management + +{kib}'s {ref}/index-mgmt.html[Index Management] allows you to manage your cluster's +indices, data streams, index templates, and much more. + +In {kib}, navigate to **Stack Management** > **Index Management** > **Data Streams**. +Select the data streams you want to delete, and click **Delete data streams**. + +[float] +[[apm-update-data]] +== Update existing data + +You might want to update documents that are already indexed. +For example, if you your service name was set incorrectly. + +To do this, you can use the {ref}/docs-update-by-query.html[Update By Query API]. +To rename a service, send the following request: + +["source","sh"] +------------------------------------------------------------ +POST /.ds-*-apm*/_update_by_query?expand_wildcards=all +{ + "query": { + "term": { + "service.name": { + "value": "current-service-name" + } + } + }, + "script": { + "source": "ctx._source.service.name = 'new-service-name'", + "lang": "painless" + } +} +------------------------------------------------------------ +// CONSOLE + +TIP: Remember to also change the service name in the {apm-agents-ref}/index.html[{apm-agent} configuration]. diff --git a/docs/en/observability/apm/manage-storage/storage-and-sizing.asciidoc b/docs/en/observability/apm/manage-storage/storage-and-sizing.asciidoc new file mode 100644 index 0000000000..2c550d9b26 --- /dev/null +++ b/docs/en/observability/apm/manage-storage/storage-and-sizing.asciidoc @@ -0,0 +1,62 @@ +[[apm-storage-guide]] += Storage and sizing guide + +APM processing and storage costs are largely dominated by transactions, spans, and stack frames. + +* <> describe an event captured by an Elastic {apm-agent} instrumenting a service. +They are the highest level of work being measuring within a service. +* <> belong to transactions. They measure from the start to end of an activity, +and contain information about a specific code path that has been executed. +* *Stack frames* belong to spans. Stack frames represent a function call on the call stack, +and include attributes like function name, file name and path, line number, etc. +Stack frames can heavily influence the size of a span. + +[float] +== Typical transactions + +Due to the high variability of APM data, it's difficult to classify a transaction as typical. +Regardless, this guide will attempt to classify Transactions as _Small_, _Medium_, or _Large_, +and make recommendations based on those classifications. + +The size of a transaction depends on the language, agent settings, and what services the agent instruments. +For instance, an agent auto-instrumenting a service with a popular tech stack +(web framework, database, caching library, etc.) is more likely to generate bigger transactions. + +In addition, all agents support manual instrumentation. +How little or much you use these APIs will also impact what a typical transaction looks like. + +If your sampling rate is very small, transactions will be the dominate storage cost. + +Here's a speculative reference: + +[options="header"] +|======================================================================= +|Transaction size |Number of Spans |Number of stack frames +|_Small_ |5-10 |5-10 +|_Medium_ |15-20 |15-20 +|_Large_ |30-40 |30-40 +|======================================================================= + +There will always be transaction outliers with hundreds of spans or stack frames, but those are very rare. +Small transactions are the most common. + +[float] +== Typical storage + +Consider the following typical storage reference. +These numbers do not account for {es} compression. + +* 1 unsampled transaction is **~1 KB** +* 1 span with 10 stack frames is **~4 KB** +* 1 span with 50 stack frames is **~20 KB** +* 1 transaction with 10 spans, each with 10 stack frames is **~50 KB** +* 1 transaction with 25 spans, each with 25 spans is **250-300 KB** +* 100 transactions with 10 spans, each with 10 stack frames, sampled at 90% is **600 KB** + +APM data compresses quite well, so the storage cost in {es} 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 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. diff --git a/docs/en/observability/apm-ui/storage-explorer.asciidoc b/docs/en/observability/apm/manage-storage/storage-explorer.asciidoc similarity index 93% rename from docs/en/observability/apm-ui/storage-explorer.asciidoc rename to docs/en/observability/apm/manage-storage/storage-explorer.asciidoc index c43af9f37f..3f4aee8649 100644 --- a/docs/en/observability/apm-ui/storage-explorer.asciidoc +++ b/docs/en/observability/apm/manage-storage/storage-explorer.asciidoc @@ -1,5 +1,5 @@ [[apm-storage-explorer]] -=== Storage Explorer += Storage Explorer Analyze your APM data and manage costs with **storage explorer**. For example, analyze the storage footprint of each of your services to see which are producing @@ -11,7 +11,7 @@ and prepare for future storage needs. image::./images/storage-explorer-overview.png[APM Storage Explorer] [float] -==== Index lifecycle phases +== Index lifecycle phases A default {apm-guide-ref}/ilm-how-to.html[index lifecycle policy] is applied to each APM data stream, but can be customized depending on your business needs. @@ -27,13 +27,13 @@ See {apm-guide-ref}/ilm-how-to.html[Index lifecycle management] to learn more ab the default APM index lifecycle policies. [float] -==== Service size chart +== Service size chart The service size chart displays the estimated size of each service over time. Expand the time filter to visualize data trends and estimate daily data generation. [float] -==== Service statistics table +== Service statistics table The service statistics table provides detailed information on each service: @@ -54,19 +54,19 @@ As you explore your service statistics, you might want to take action to reduce documents and therefore storage size of a particular service. [float] -===== Reduce the number of transactions +=== Reduce the number of transactions To reduce the number of transactions a service generates, configure a more aggressive {apm-guide-ref}/sampling.html[transaction sampling policy]. Transaction sampling lowers the amount of data ingested without negatively impacting the usefulness of your data. [float] -===== Reduce the number of spans +=== Reduce the number of spans To reduce the number of spans a service generates, enable {apm-guide-ref}/span-compression.html[span compression]. Span compression saves on data and transfer costs by compressing multiple, similar spans into a single span. [float] -===== Reduce the number of metrics +=== Reduce the number of metrics To reduce the number of system, runtime, and application metrics, tune the APM agent or agents that are collecting the data. You can disable the collection of specific metrics with the **disable metrics** configuration. @@ -75,17 +75,17 @@ Most APM agents support both options. See the relevant {apm-agents-ref}[APM agent configuration options] for more details. [float] -===== Reduce the number of errors +=== Reduce the number of errors To reduce the number of errors a service generate, work with your developers to change how exceptions are handled in your code. [float] -==== Privileges +== Privileges Storage Explorer requires expanded privileges to view. See <> for more information. [float] -==== Limitations +== Limitations Multi-cluster deployments are not supported. diff --git a/docs/en/observability/apm-ui/mobile-errors.asciidoc b/docs/en/observability/apm/mobile-errors.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/mobile-errors.asciidoc rename to docs/en/observability/apm/mobile-errors.asciidoc diff --git a/docs/en/observability/apm/monitor-apm-server.asciidoc b/docs/en/observability/apm/monitor-apm-server/index.asciidoc similarity index 79% rename from docs/en/observability/apm/monitor-apm-server.asciidoc rename to docs/en/observability/apm/monitor-apm-server/index.asciidoc index c882045b81..96072311da 100644 --- a/docs/en/observability/apm/monitor-apm-server.asciidoc +++ b/docs/en/observability/apm/monitor-apm-server/index.asciidoc @@ -1,9 +1,5 @@ [[apm-monitor-apm]] -== Monitor APM Server - -++++ -Monitor -++++ += Monitor APM Server Use the {stack} {monitor-features} to gain insight into the real-time health and performance of APM Server. Stack monitoring exposes key metrics, like intake response count, intake error rate, output event rate, @@ -17,7 +13,7 @@ Select your deployment method to get started: [float] [[apm-monitor-apm-cloud]] -=== {ecloud} +== {ecloud} {ecloud} manages the installation and configuration of a monitoring agent for you -- so all you have to do is flip a switch and watch the data pour in. @@ -25,7 +21,13 @@ all you have to do is flip a switch and watch the data pour in. * **{ess}** user? See {cloud}/ec-enable-logging-and-monitoring.html[ESS: Enable logging and monitoring]. * **{ece}** user? See {ece-ref}/ece-enable-logging-and-monitoring.html[ECE: Enable logging and monitoring]. +//// +Subsections +//// + +:leveloffset: +1 -include::./monitor.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/monitor-apm-server/monitor.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/monitor-apm-server/monitoring-beats.asciidoc[] -include::{observability-docs-root}/docs/en/observability/apm/monitoring/monitoring-beats.asciidoc[leveloffset=+2] +:!leveloffset: diff --git a/docs/en/observability/apm/monitor.asciidoc b/docs/en/observability/apm/monitor-apm-server/monitor.asciidoc similarity index 97% rename from docs/en/observability/apm/monitor.asciidoc rename to docs/en/observability/apm/monitor-apm-server/monitor.asciidoc index 291378d40c..1fb279d92d 100644 --- a/docs/en/observability/apm/monitor.asciidoc +++ b/docs/en/observability/apm/monitor-apm-server/monitor.asciidoc @@ -1,5 +1,5 @@ [[apm-monitor-apm-self-install]] -=== Monitor a Fleet-managed APM Server += Monitor a Fleet-managed APM Server ++++ Fleet-managed @@ -15,7 +15,7 @@ To collect and ship monitoring data: [float] [[apm-configure-ea-monitoring-data]] -==== Configure {agent} to send monitoring data +== Configure {agent} to send monitoring data **** Before you can monitor APM, @@ -52,7 +52,7 @@ See the {fleet-guide}/elastic-agent-cmd-options.html[{agent} command reference] [float] [[apm-install-config-metricbeat]] -==== Install and configure {metricbeat} to collect monitoring data +== Install and configure {metricbeat} to collect monitoring data . Install {metricbeat} on the same server as {agent}. To learn how, see {metricbeat-ref}/metricbeat-installation-configuration.html[Get started with {metricbeat}]. diff --git a/docs/en/observability/apm/monitoring/monitoring-beats.asciidoc b/docs/en/observability/apm/monitor-apm-server/monitoring-beats.asciidoc similarity index 94% rename from docs/en/observability/apm/monitoring/monitoring-beats.asciidoc rename to docs/en/observability/apm/monitor-apm-server/monitoring-beats.asciidoc index 75a021290b..7c91c3da17 100644 --- a/docs/en/observability/apm/monitoring/monitoring-beats.asciidoc +++ b/docs/en/observability/apm/monitor-apm-server/monitoring-beats.asciidoc @@ -20,9 +20,14 @@ select monitoring data directly to the standard indices of your monitoring cluster. endif::[] +//// +Subsections +//// + +:leveloffset: +1 + include::monitoring-internal-collection.asciidoc[] +include::monitoring-metricbeat.asciidoc[] include::monitoring-local-collection.asciidoc[] -ifndef::serverless[] -include::monitoring-metricbeat.asciidoc[] -endif::[] \ No newline at end of file +:!leveloffset: diff --git a/docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc b/docs/en/observability/apm/monitor-apm-server/monitoring-internal-collection.asciidoc similarity index 98% rename from docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc rename to docs/en/observability/apm/monitor-apm-server/monitoring-internal-collection.asciidoc index dc2d3dc156..3506339740 100644 --- a/docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc +++ b/docs/en/observability/apm/monitor-apm-server/monitoring-internal-collection.asciidoc @@ -1,5 +1,5 @@ [[apm-monitoring-internal-collection]] -== Use internal collection to send monitoring data += Use internal collection to send monitoring data ++++ Use internal collection ++++ diff --git a/docs/en/observability/apm/monitoring/monitoring-local-collection.asciidoc b/docs/en/observability/apm/monitor-apm-server/monitoring-local-collection.asciidoc similarity index 99% rename from docs/en/observability/apm/monitoring/monitoring-local-collection.asciidoc rename to docs/en/observability/apm/monitor-apm-server/monitoring-local-collection.asciidoc index e6522f3bc7..572ef23afb 100644 --- a/docs/en/observability/apm/monitoring/monitoring-local-collection.asciidoc +++ b/docs/en/observability/apm/monitor-apm-server/monitoring-local-collection.asciidoc @@ -1,5 +1,6 @@ [[apm-monitoring-local-collection]] = Use the select metrics emitted directly to your monitoring cluster + ++++ Use local collection ++++ diff --git a/docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc b/docs/en/observability/apm/monitor-apm-server/monitoring-metricbeat.asciidoc similarity index 98% rename from docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc rename to docs/en/observability/apm/monitor-apm-server/monitoring-metricbeat.asciidoc index 60a666dc6a..d976c8e725 100644 --- a/docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc +++ b/docs/en/observability/apm/monitor-apm-server/monitoring-metricbeat.asciidoc @@ -1,5 +1,6 @@ [[apm-monitoring-metricbeat-collection]] -== Use {metricbeat} to send monitoring data += Use {metricbeat} to send monitoring data + [subs="attributes"] ++++ Use {metricbeat} collection @@ -25,7 +26,7 @@ To collect and ship monitoring data: [float] [[apm-configure-shipper]] -=== Configure the shipper you want to monitor +== Configure the shipper you want to monitor . Enable the HTTP endpoint to allow external collection of monitoring data: + @@ -99,7 +100,7 @@ endif::[] [float] [[apm-configure-metricbeat]] -=== Install and configure {metricbeat} to collect monitoring data +== Install and configure {metricbeat} to collect monitoring data . Install {metricbeat} on the same server as APM Server. To learn how, see {metricbeat-ref}/metricbeat-installation-configuration.html[Get started with {metricbeat}]. diff --git a/docs/en/observability/apm/monitoring/shared-monitor-config.asciidoc b/docs/en/observability/apm/monitor-apm-server/shared-monitor-config.asciidoc similarity index 100% rename from docs/en/observability/apm/monitoring/shared-monitor-config.asciidoc rename to docs/en/observability/apm/monitor-apm-server/shared-monitor-config.asciidoc diff --git a/docs/en/observability/apm/repositories.asciidoc b/docs/en/observability/apm/repositories.asciidoc index 56b61a6331..3cc4c4c556 100644 --- a/docs/en/observability/apm/repositories.asciidoc +++ b/docs/en/observability/apm/repositories.asciidoc @@ -1,5 +1,6 @@ +[float] [[apm-setup-repositories]] -==== Repositories for APT and YUM += Repositories for APT and YUM We have repositories available for APT and YUM-based distributions. Note that we provide binary packages, but no source packages. @@ -12,7 +13,7 @@ We use the PGP key https://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88 to sign all our packages. It is available from https://pgp.mit.edu. [float] -===== APT +== APT ifeval::["{release-state}"=="unreleased"] @@ -92,7 +93,7 @@ sudo systemctl enable apm-server endif::[] [float] -===== YUM +== YUM ifeval::["{release-state}"=="unreleased"] diff --git a/docs/en/observability/apm/secure-comms.asciidoc b/docs/en/observability/apm/secure-comms.asciidoc deleted file mode 100644 index 65b03d9543..0000000000 --- a/docs/en/observability/apm/secure-comms.asciidoc +++ /dev/null @@ -1,23 +0,0 @@ -[[apm-securing-apm-server]] -== Secure communication with the {stack} - -++++ -Secure communication -++++ - -The following topics provide information about securing the APM Server -process and connecting securely to APM agents and the {stack}. - -* <> -* <> -* <> - -:leveloffset: +1 -include::secure-agent-communication.asciidoc[] - -// APM privileges -include::{observability-docs-root}/docs/en/observability/apm/feature-roles.asciidoc[] - -// APM API keys -include::{observability-docs-root}/docs/en/observability/apm/access-api-keys.asciidoc[] -:leveloffset: -1 \ No newline at end of file diff --git a/docs/en/observability/apm/anonymous-auth.asciidoc b/docs/en/observability/apm/security/apm-agents/anonymous-auth.asciidoc similarity index 93% rename from docs/en/observability/apm/anonymous-auth.asciidoc rename to docs/en/observability/apm/security/apm-agents/anonymous-auth.asciidoc index 59fb8a9007..903514ffe8 100644 --- a/docs/en/observability/apm/anonymous-auth.asciidoc +++ b/docs/en/observability/apm/security/apm-agents/anonymous-auth.asciidoc @@ -1,5 +1,5 @@ [[apm-anonymous-auth]] -=== Anonymous authentication += Anonymous authentication Elastic APM agents can send unauthenticated (anonymous) events to the APM Server. An event is considered to be anonymous if no authentication token can be extracted from the incoming request. @@ -22,7 +22,7 @@ ingestion of unauthenticated client-side APM data while still requiring authenti [float] [[apm-anonymous-auth-config]] -=== Configuring anonymous auth for client-side services +== Configuring anonymous auth for client-side services [NOTE] ==== @@ -34,7 +34,7 @@ include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/anonymo [float] [[apm-derive-client-ip]] -=== Deriving an incoming request's `client.ip` address +== Deriving an incoming request's `client.ip` address The remote IP address of an incoming request might be different from the end-user's actual IP address, for example, because of a proxy. For this reason, @@ -49,7 +49,7 @@ If none of these headers are present, the remote address for the incoming reques [float] [[apm-derive-client-ip-concerns]] -==== Using a reverse proxy or load balancer +=== Using a reverse proxy or load balancer HTTP headers are easily modified; it's possible for anyone to spoof the derived `client.ip` value by changing or setting, diff --git a/docs/en/observability/apm/api-keys.asciidoc b/docs/en/observability/apm/security/apm-agents/api-keys.asciidoc similarity index 95% rename from docs/en/observability/apm/api-keys.asciidoc rename to docs/en/observability/apm/security/apm-agents/api-keys.asciidoc index 937f2c1179..035cd0c4c7 100644 --- a/docs/en/observability/apm/api-keys.asciidoc +++ b/docs/en/observability/apm/security/apm-agents/api-keys.asciidoc @@ -1,5 +1,5 @@ [[apm-api-key]] -=== API keys += API keys IMPORTANT: API keys are sent as plain-text, so they only provide security when used in combination with <>. @@ -22,15 +22,15 @@ make sure <> is enabled, then complete these steps: . <> . <> -[[apm-enable-api-key]] [float] -=== Enable API keys +[[apm-enable-api-key]] +== Enable API keys include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/api-key-widget.asciidoc[] -[[apm-create-api-key-user]] [float] -=== Create an API key user in {kib} +[[apm-create-api-key-user]] +== Create an API key user in {kib} API keys can only have the same or lower access rights than the user that creates them. Instead of using a superuser account to create API keys, you can create a role with the minimum required @@ -70,9 +70,9 @@ POST /_security/role/apm_agent_key_role Assign the newly created `apm_agent_key_role` role to any user that wishes to create {apm-agent} API keys. -[[apm-create-an-api-key]] [float] -=== Create an API key in the APM UI +[[apm-create-an-api-key]] +== Create an API key in the APM UI The APM UI has a built-in workflow that you can use to easily create and view {apm-agent} API keys. Only API keys created in the APM UI will show up here. @@ -91,9 +91,9 @@ You will need this for the next step, and you will not be able to view it again. [role="screenshot"] image::images/apm-ui-api-key.png[APM UI API key] -[[apm-agent-api-key]] [float] -=== Set the API key in your APM agents +[[apm-agent-api-key]] +== Set the API key in your APM agents You can now apply your newly created API keys in the configuration of each of your APM agents. See the relevant agent documentation for additional information: @@ -109,18 +109,18 @@ See the relevant agent documentation for additional information: * *Python agent*: {apm-py-ref}/configuration.html#config-api-key[`api_key`] * *Ruby agent*: {apm-ruby-ref}/configuration.html#config-api-key[`api_key`] -[[apm-configure-api-key-alternative]] [float] -=== Alternate API key creation methods +[[apm-configure-api-key-alternative]] +== Alternate API key creation methods API keys can also be created and validated outside of {kib}: * <> * <> -[[apm-create-api-key-workflow-apm-server]] [float] -==== APM Server API key workflow +[[apm-create-api-key-workflow-apm-server]] +=== APM Server API key workflow This API creation method only works with the APM Server binary. @@ -129,15 +129,15 @@ deprecated::[8.6.0, Users should create API Keys through {kib} or the {es} REST APM Server provides a command line interface for creating, retrieving, invalidating, and verifying API keys. Keys created using this method can only be used for communication with APM Server. -[[apm-create-api-key-subcommands]] [float] -===== `apikey` subcommands +[[apm-create-api-key-subcommands]] +==== `apikey` subcommands -include::{observability-docs-root}/docs/en/observability/apm/command-reference.asciidoc[tag=apikey-subcommands] +include::{observability-docs-root}/docs/en/observability/apm/configure/advanced-setup/command-reference.asciidoc[tag=apikey-subcommands] -[[apm-create-api-key-privileges]] [float] -===== Privileges +[[apm-create-api-key-privileges]] +==== Privileges If privileges are not specified at creation time, the created key will have all privileges. @@ -145,9 +145,9 @@ If privileges are not specified at creation time, the created key will have all * `--ingest` grants the `event:write` privilege * `--sourcemap` grants the `sourcemap:write` privilege -[[apm-create-api-key-workflow]] [float] -===== Create an API key +[[apm-create-api-key-workflow]] +==== Create an API key Create an API key with the `create` subcommand. @@ -208,9 +208,9 @@ Error count ........ 0 A full list of `apikey` subcommands and flags is available in the <>. -[[apm-create-api-key-workflow-es]] [float] -==== {es} API key workflow +[[apm-create-api-key-workflow-es]] +=== {es} API key workflow It is also possible to create API keys using the {es} {ref}/security-api-create-api-key.html[create API key API]. diff --git a/docs/en/observability/apm/secure-agent-communication.asciidoc b/docs/en/observability/apm/security/apm-agents/index.asciidoc similarity index 90% rename from docs/en/observability/apm/secure-agent-communication.asciidoc rename to docs/en/observability/apm/security/apm-agents/index.asciidoc index 2e34ab600b..c47dfd5e17 100644 --- a/docs/en/observability/apm/secure-agent-communication.asciidoc +++ b/docs/en/observability/apm/security/apm-agents/index.asciidoc @@ -1,9 +1,5 @@ [[apm-secure-agent-communication]] -== Secure communication with APM agents - -++++ -With APM agents -++++ += Secure communication with APM agents Communication between APM agents and {agent} can be both encrypted and authenticated. It is strongly recommended to use both TLS encryption and authentication as secrets are sent as plain text. @@ -19,10 +15,11 @@ If both API keys and a secret token are enabled, APM agents can choose whichever In some use-cases, like when an {apm-agent} is running on the client side, authentication is not possible. See <> for more information. -include::./tls-comms.asciidoc[] +:leveloffset: +1 +include::./tls-comms.asciidoc[] include::./api-keys.asciidoc[] - include::./secret-token.asciidoc[] - include::./anonymous-auth.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm/secret-token.asciidoc b/docs/en/observability/apm/security/apm-agents/secret-token.asciidoc similarity index 96% rename from docs/en/observability/apm/secret-token.asciidoc rename to docs/en/observability/apm/security/apm-agents/secret-token.asciidoc index 1ac8993a1e..62fd4a5c41 100644 --- a/docs/en/observability/apm/secret-token.asciidoc +++ b/docs/en/observability/apm/security/apm-agents/secret-token.asciidoc @@ -1,5 +1,5 @@ [[apm-secret-token]] -=== Secret token += Secret token IMPORTANT: Secret tokens are sent as plain-text, so they only provide security when used in combination with <>. @@ -18,7 +18,7 @@ as there is no way to prevent them from being publicly exposed. [float] [[apm-create-secret-token]] -=== Create a secret token +== Create a secret token // lint ignore fleet NOTE: {ess} and {ece} deployments provision a secret token when the deployment is created. @@ -28,7 +28,7 @@ include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/secret- [[apm-configure-secret-token]] [float] -=== Configure the secret token in your APM agents +== Configure the secret token in your APM agents Each Elastic {apm-agent} has a configuration option to set the value of the secret token: diff --git a/docs/en/observability/apm/tls-comms.asciidoc b/docs/en/observability/apm/security/apm-agents/tls-comms.asciidoc similarity index 93% rename from docs/en/observability/apm/tls-comms.asciidoc rename to docs/en/observability/apm/security/apm-agents/tls-comms.asciidoc index fbcbd16e51..16c111695b 100644 --- a/docs/en/observability/apm/tls-comms.asciidoc +++ b/docs/en/observability/apm/security/apm-agents/tls-comms.asciidoc @@ -1,5 +1,5 @@ [[apm-agent-tls]] -=== {apm-agent} TLS communication += {apm-agent} TLS communication TLS is disabled by default. When TLS is enabled for APM Server inbound communication, agents will verify the identity @@ -11,11 +11,11 @@ or be <>. [float] [[apm-agent-self-sign]] -=== Use a self-signed certificate +== Use a self-signed certificate [float] [[apm-agent-self-sign-1]] -==== Step 1: Create a self-signed certificate +=== Step 1: Create a self-signed certificate The {es} distribution offers the `certutil` tool for the creation of self-signed certificates: @@ -28,7 +28,7 @@ location of the output zip archive containing the certificate and the private ke [float] [[apm-agent-self-sign-2]] -==== Step 2: Configure the APM Server +=== Step 2: Configure the APM Server Enable TLS and configure the APM Server to point to the extracted certificate and key: @@ -36,7 +36,7 @@ include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/tls-wid [float] [[apm-agent-self-sign-3]] -==== Step 3: Configure APM agents +=== Step 3: Configure APM agents When the APM server uses a certificate that is not chained to a publicly-trusted certificate (e.g. self-signed), additional configuration is required in the {apm-agent}: @@ -61,7 +61,7 @@ We do not recommend disabling {apm-agent} verification of the server's certifica [float] [[apm-agent-client-cert]] -=== Client certificate authentication +== Client certificate authentication APM Server does not require agents to provide a certificate for authentication, and there is no dedicated support for SSL/TLS client certificate authentication in Elastic’s backend agents. \ No newline at end of file diff --git a/docs/en/observability/apm-ui/apm-spaces.asciidoc b/docs/en/observability/apm/security/data-security/apm-spaces.asciidoc similarity index 97% rename from docs/en/observability/apm-ui/apm-spaces.asciidoc rename to docs/en/observability/apm/security/data-security/apm-spaces.asciidoc index 8d97f3069f..5c4257e3f9 100644 --- a/docs/en/observability/apm-ui/apm-spaces.asciidoc +++ b/docs/en/observability/apm/security/data-security/apm-spaces.asciidoc @@ -1,5 +1,5 @@ [[apm-spaces]] -=== Control access to APM data += Control access to APM data Starting in version 8.2.0, the APM UI is {kibana-ref}/xpack-spaces.html[Kibana space] aware. This allows you to separate your data--and access to that data--by team, use case, service environment, @@ -15,7 +15,7 @@ is by creating filtered aliases. See the guide below for more information. [float] [[apm-spaces-example]] -=== Guide: Separate staging and production data +== Guide: Separate staging and production data This guide will explain how to separate your staging and production data. This can be helpful to either remove noise when troubleshooting a production issue, @@ -30,7 +30,7 @@ You should have documents where `service.environment: production` and `service.e If this field is empty, see <> to learn how to set this value. [float] -==== Step 1: Create filtered aliases +=== Step 1: Create filtered aliases The APM UI uses index patterns to query your APM data. An index pattern can match data streams, indices, and/or aliases. The default values are: @@ -244,7 +244,7 @@ POST /_aliases?pretty ==== [float] -==== Step 2: Create {kib} spaces +=== Step 2: Create {kib} spaces Next, you'll need to create a {Kib} space for each service environment. To create these spaces, navigate to **Stack Management** > **Spaces** > **Create a space**. @@ -253,7 +253,7 @@ For this guide, we've created two Kibana spaces, one named `production` and one See {kibana-ref}/xpack-spaces.html[Kibana spaces] for more information on creating a space. [float] -==== Step 3: Update APM index settings in each space +=== Step 3: Update APM index settings in each space Now we can change the default data views that the APM UI queries in each space. @@ -271,7 +271,7 @@ The values in each column match the names of the filtered aliases we created in |==== [float] -==== Step 4: Create {kib} access roles +=== Step 4: Create {kib} access roles In {kib}, navigate to **Stack Management** > **Roles** and click **Create role**. @@ -362,7 +362,7 @@ POST /_security/role/staging_apm_viewer ==== [float] -==== Step 5: Assign users to roles +=== Step 5: Assign users to roles The last thing to do is assign users to the newly created roles above. Users will only have access to the data within the spaces that they are granted. @@ -406,6 +406,6 @@ POST /_security/user/staging-apm-user <1> Assigns the previously created `staging_apm_viewer` role. [float] -==== Step 6: Marvel +=== Step 6: Marvel That's it! Head back to the APM UI and marvel at your space-specific data. diff --git a/docs/en/observability/apm/security/data-security/custom-filter.asciidoc b/docs/en/observability/apm/security/data-security/custom-filter.asciidoc new file mode 100644 index 0000000000..32566c4828 --- /dev/null +++ b/docs/en/observability/apm/security/data-security/custom-filter.asciidoc @@ -0,0 +1,300 @@ +[[apm-custom-filter]] += Custom filters + +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/index.asciidoc[tag=custom-filters] + +[discrete] +[[apm-filters-ingest-pipeline]] +== Create an ingest pipeline filter + +Ingest node pipelines specify a series of processors that transform data in a specific way. +Transformation happens prior to indexing--inflicting no performance overhead on the monitored application. +Pipelines are a flexible and easy way to filter or obfuscate Elastic APM data. + +[discrete] +[[apm-filters-ingest-pipeline-tutorial]] +=== Tutorial: redact sensitive information + +Say you decide to <> +but quickly notice that sensitive information is being collected in the +`http.request.body.original` field: + +[source,json] +---- +{ + "email": "test@abc.com", + "password": "hunter2" +} +---- + +**Create a pipeline** + +To obfuscate the passwords stored in the request body, +you can use a series of {ref}/processors.html[ingest processors]. +To start, create a pipeline with a simple description and an empty array of processors: + +[source,json] +---- +{ + "pipeline": { + "description": "redact http.request.body.original.password", + "processors": [] <1> + } +} +---- +<1> The processors defined below will go in this array + +**Add a JSON processor** + +Add your first processor to the processors array. +Because the agent captures the request body as a string, use the +{ref}/json-processor.html[JSON processor] to convert the original field value into a structured JSON object. +Save this JSON object in a new field: + +[source,json] +---- +{ + "json": { + "field": "http.request.body.original", + "target_field": "http.request.body.original_json", + "ignore_failure": true + } +} +---- + +**Add a set processor** + +If `body.original_json` is not `null`, i.e., it exists, we'll redact the `password` with the {ref}/set-processor.html[set processor], +by setting the value of `body.original_json.password` to `"redacted"`: + +[source,json] +---- +{ + "set": { + "field": "http.request.body.original_json.password", + "value": "redacted", + "if": "ctx?.http?.request?.body?.original_json != null" + } +} +---- + +**Add a convert processor** + +Use the {ref}/convert-processor.html[convert processor] to convert the JSON value of `body.original_json` to a string and set it as the `body.original` value: + +[source,json] +---- +{ + "convert": { + "field": "http.request.body.original_json", + "target_field": "http.request.body.original", + "type": "string", + "if": "ctx?.http?.request?.body?.original_json != null", + "ignore_failure": true + } +} +---- + +**Add a remove processor** + +Finally, use the {ref}/remove-processor.html[remove processor] to remove the `body.original_json` field: + +[source,json] +---- +{ + "remove": { + "field": "http.request.body.original", + "if": "ctx?.http?.request?.body?.original_json != null", + "ignore_failure": true + } +} +---- + +**Register the pipeline** + +Now we'll put it all together. +Use the {ref}/put-pipeline-api.html[create or update pipeline API] to register the new pipeline in {es}. +Name the pipeline `apm_redacted_body_password`: + +[source,console] +---- +PUT _ingest/pipeline/apm_redacted_body_password +{ + "description": "redact http.request.body.original.password", + "processors": [ + { + "json": { + "field": "http.request.body.original", + "target_field": "http.request.body.original_json", + "ignore_failure": true + } + }, + { + "set": { + "field": "http.request.body.original_json.password", + "value": "redacted", + "if": "ctx?.http?.request?.body?.original_json != null" + } + }, + { + "convert": { + "field": "http.request.body.original_json", + "target_field": "http.request.body.original", + "type": "string", + "if": "ctx?.http?.request?.body?.original_json != null", + "ignore_failure": true + } + }, + { + "remove": { + "field": "http.request.body.original_json", + "if": "ctx?.http?.request?.body?.original_json != null", + "ignore_failure": true + } + } + ] +} +---- + +**Test the pipeline** + +Prior to enabling this new pipeline, you can test it with the {ref}/simulate-pipeline-api.html[simulate pipeline API]. +This API allows you to run multiple documents through a pipeline to ensure it is working correctly. + +The request below simulates running three different documents through the pipeline: + +[source,console] +---- +POST _ingest/pipeline/apm_redacted_body_password/_simulate +{ + "docs": [ + { + "_source": { <1> + "http": { + "request": { + "body": { + "original": """{"email": "test@abc.com", "password": "hunter2"}""" + } + } + } + } + }, + { + "_source": { <2> + "some-other-field": true + } + }, + { + "_source": { <3> + "http": { + "request": { + "body": { + "original": """["invalid json" """ + } + } + } + } + } + ] +} +---- +<1> This document features the same sensitive data from the original example above +<2> This document only contains an unrelated field +<3> This document contains invalid JSON + +The API response should be similar to this: + +[source,json] +---- +{ + "docs" : [ + { + "doc" : { + "_source" : { + "http" : { + "request" : { + "body" : { + "original" : { + "password" : "redacted", + "email" : "test@abc.com" + } + } + } + } + } + } + }, + { + "doc" : { + "_source" : { + "nobody" : true + } + } + }, + { + "doc" : { + "_source" : { + "http" : { + "request" : { + "body" : { + "original" : """["invalid json" """ + } + } + } + } + } + } + ] +} +---- + +As expected, only the first simulated document has a redacted password field. +All other documents are unaffected. + +**Create an `@custom` pipeline** + +The final step in this process is to call the newly created `apm_redacted_body_password` pipeline +from the `@custom` pipeline of the data stream you wish to edit. + +include::{observability-docs-root}/docs/en/observability/apm/manage-storage/ingest-pipelines.asciidoc[tag=ingest-pipeline-naming] + +Use the {ref}/put-pipeline-api.html[create or update pipeline API] to register the new pipeline in {es}. +Name the pipeline `traces-apm@custom`: + +[source,console] +---- +PUT _ingest/pipeline/traces-apm@custom +{ + "processors": [ + { + "pipeline": { + "name": "apm_redacted_body_password" <1> + } + } + ] +} +---- +<1> The name of the pipeline we previously created + +TIP: If you prefer using a GUI, you can instead open {kib} and navigate to +**Stack Management** -> **Ingest Pipelines** -> **Create pipeline**. +Use the same naming convention explained previously to ensure your new pipeline matches the correct APM data stream. + +That's it! Passwords will now be redacted from your APM HTTP body data. + +To learn more about ingest pipelines, see <>. + +[discrete] +[[apm-filters-in-agent]] +== APM agent filters + +Some APM agents offer a way to manipulate or drop APM events _before_ they are sent to the APM Server. +Please see the relevant agent's documentation for more information and examples: + +// * Go: {apm-go-ref-v}/[] +// * Java: {apm-java-ref-v}/[] +* .NET: {apm-dotnet-ref-v}/public-api.html#filter-api[Filter API]. +* Node.js: {apm-node-ref-v}/agent-api.html#apm-add-filter[`addFilter()`]. +// * PHP: {apm-php-ref-v}[] +* Python: {apm-py-ref-v}/sanitizing-data.html[custom processors]. +* Ruby: {apm-ruby-ref-v}/api.html#api-agent-add-filter[`add_filter()`]. diff --git a/docs/en/observability/apm/security/data-security/delete.asciidoc b/docs/en/observability/apm/security/data-security/delete.asciidoc new file mode 100644 index 0000000000..712bf3bfe0 --- /dev/null +++ b/docs/en/observability/apm/security/data-security/delete.asciidoc @@ -0,0 +1,90 @@ +[[apm-data-security-delete]] += Delete sensitive data + +If you accidentally ingest sensitive data, follow these steps to remove or redact the offending data: + +. Stop collecting the sensitive data. +Use the *remedy* column of the <> table to determine how to stop collecting +the offending data. + +. Delete or redact the ingested data. With data collection fixed, you can now delete or redact the offending data: ++ +* <> +* <> + +[float] +[[apm-redact-field-data]] +== Redact specific fields + +To redact sensitive data in a specific field, use the {ref}/docs-update-by-query.html[update by query API]. + +For example, the following query removes the `client.ip` address +from APM documents in the `logs-apm.error-default` data stream: + +[source, console] +---- +POST /logs-apm.error-default/_update_by_query +{ + "query": { + "exists": { + "field": "client.ip" + } + } + "script": { + "source": "ctx._source.client.ip = params.redacted", + "params": { + "redacted": "[redacted]" + } + } +} +---- + +Or, perhaps you only want to redact IP addresses from European users: + +[source, console] +---- +POST /logs-apm.error-default/_update_by_query +{ + "query": { + "term": { + "client.geo.continent_name": { + "value": "Europe" + } + } + }, + "script": { + "source": "ctx._source.client.ip = params.redacted", + "params": { + "redacted": "[redacted]" + } + } +} +---- + +See {ref}/docs-update-by-query.html[update by query API] for more information and examples. + +[float] +[[apm-delete-doc-data]] +== Delete {es} documents + +WARNING: This will permanently delete your data. +You should test your queries with the {ref}/search-search.html[search API] prior to deleting data. + +To delete an {es} document, +you can use the {ref}/docs-delete-by-query.html[delete by query API]. + +For example, to delete all documents in the `apm-traces-*` data stream with a `user.email` value, run the following query: + +[source, console] +---- +POST /apm-traces-*/_delete_by_query +{ + "query": { + "exists": { + "field": "user.email" + } + } +} +---- + +See {ref}/docs-delete-by-query.html[delete by query API] for more information and examples. diff --git a/docs/en/observability/apm/security/data-security/filtering.asciidoc b/docs/en/observability/apm/security/data-security/filtering.asciidoc new file mode 100644 index 0000000000..b2297b6ca3 --- /dev/null +++ b/docs/en/observability/apm/security/data-security/filtering.asciidoc @@ -0,0 +1,122 @@ +[[apm-filtering]] += Built-in data filters + +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/index.asciidoc[tag=data-filters] + +[discrete] +[[apm-filters-http-header]] +== HTTP headers + +By default, APM agents capture HTTP request and response headers (including cookies). +Most Elastic APM agents provide the ability to sanitize HTTP header fields, +including cookies and `application/x-www-form-urlencoded` data (POST form fields). +Query string and captured request bodies, like `application/json` data, are not sanitized. + +The default list of sanitized fields attempts to target common field names for data relating to +passwords, credit card numbers, authorization, etc., but can be customized to fit your data. +This sensitive data never leaves the instrumented service. + +This setting supports <>, +which means the list of sanitized fields can be updated without needing to redeploy your services: + +* Go: {apm-go-ref-v}/configuration.html#config-sanitize-field-names[`ELASTIC_APM_SANITIZE_FIELD_NAMES`] +* Java: {apm-java-ref-v}/config-core.html#config-sanitize-field-names[`sanitize_field_names`] +* .NET: {apm-dotnet-ref-v}/config-core.html#config-sanitize-field-names[`sanitizeFieldNames`] +* Node.js: {apm-node-ref-v}/configuration.html#sanitize-field-names[`sanitizeFieldNames`] +// * PHP: {apm-php-ref-v}[``] +* Python: {apm-py-ref-v}/configuration.html#config-sanitize-field-names[`sanitize_field_names`] +* Ruby: {apm-ruby-ref-v}/configuration.html#config-sanitize-field-names[`sanitize_field_names`] + +Alternatively, you can completely disable the capturing of HTTP headers. +This setting also supports <>: + +* Go: {apm-go-ref-v}/configuration.html#config-capture-headers[`ELASTIC_APM_CAPTURE_HEADERS`] +* Java: {apm-java-ref-v}/config-core.html#config-capture-headers[`capture_headers`] +* .NET: {apm-dotnet-ref-v}/config-http.html#config-capture-headers[`CaptureHeaders`] +* Node.js: {apm-node-ref-v}/configuration.html#capture-headers[`captureHeaders`] +// * PHP: {apm-php-ref-v}[``] +* Python: {apm-py-ref-v}/configuration.html#config-capture-headers[`capture_headers`] +* Ruby: {apm-ruby-ref-v}/configuration.html#config-capture-headers[`capture_headers`] + +[discrete] +[[apm-filters-http-body]] +== HTTP bodies + +By default, the body of HTTP requests is not recorded. +Request bodies often contain sensitive data like passwords or credit card numbers, +so use care when enabling this feature. + +This setting supports <>, +which means the list of sanitized fields can be updated without needing to redeploy your services: + +* Go: {apm-go-ref-v}/configuration.html#config-capture-body[`ELASTIC_APM_CAPTURE_BODY`] +* Java: {apm-java-ref-v}/config-core.html#config-capture-body[`capture_body`] +* .NET: {apm-dotnet-ref-v}/config-http.html#config-capture-body[`CaptureBody`] +* Node.js: {apm-node-ref-v}/configuration.html#capture-body[`captureBody`] +// * PHP: {apm-php-ref-v}[``] +* Python: {apm-py-ref-v}/configuration.html#config-capture-body[`capture_body`] +* Ruby: {apm-ruby-ref-v}/configuration.html#config-capture-body[`capture_body`] + +[discrete] +[[apm-filters-personal-data]] +== Personal data + +By default, the APM Server captures some personal data associated with trace events: + +* `client.ip`: The client's IP address. Typically derived from the HTTP headers of incoming requests. +`client.ip` is also used in conjunction with the {ref}/geoip-processor.html[`geoip` processor] to assign +geographical information to trace events. To learn more about how `client.ip` is derived, +see <>. +* `user_agent`: User agent data, including the client operating system, device name, vendor, and version. + +The capturing of this data can be turned off by setting +**Capture personal data** to `false`. + +[discrete] +[[apm-filters-real-user-data]] +== Real user monitoring data + +Protecting user data is important. +For that reason, individual RUM instrumentations can be disabled in the RUM agent with the +{apm-rum-ref-v}/configuration.html#disable-instrumentations[`disableInstrumentations`] configuration variable. +Disabled instrumentations produce no spans or transactions. + +[options="header"] +|==== +|Disable |Configuration value +|HTTP requests |`fetch` and `xmlhttprequest` +|Page load metrics including static resources |`page-load` +|JavaScript errors on the browser |`error` +|User click events including URLs visited, mouse clicks, and navigation events |`eventtarget` +|Single page application route changes |`history` +|==== + +[discrete] +[[apm-filters-database-statements]] +== Database statements + +For SQL databases, APM agents do not capture the parameters of prepared statements. +Note that Elastic APM currently does not make an effort to strip parameters of regular statements. +Not using prepared statements makes your code vulnerable to SQL injection attacks, +so be sure to use prepared statements. + +For non-SQL data stores, such as {es} or MongoDB, +Elastic APM captures the full statement for queries. +For inserts or updates, the full document is not stored. +To filter or obfuscate data in non-SQL database statements, +or to remove the statement entirely, +you can set up an ingest node pipeline. + +[discrete] +[[apm-filters-agent-specific]] +== Agent-specific options + +Certain agents offer additional filtering and obfuscating options: + +**Agent configuration options** + +* (Node.js) Remove errors raised by the server-side process: +disable with {apm-node-ref-v}/configuration.html#capture-exceptions[captureExceptions]. + +* (Java) Remove process arguments from transactions: +disabled by default with {apm-java-ref-v}/config-reporter.html#config-include-process-args[`include_process_args`]. diff --git a/docs/en/observability/apm/security/data-security/index.asciidoc b/docs/en/observability/apm/security/data-security/index.asciidoc new file mode 100644 index 0000000000..0b041e6c6e --- /dev/null +++ b/docs/en/observability/apm/security/data-security/index.asciidoc @@ -0,0 +1,92 @@ +[[apm-data-security]] += Application data security + +++++ +Secure data +++++ + +When setting up Elastic APM, it's essential to review all captured data carefully to ensure +it doesn't contain sensitive information like passwords, credit card numbers, or health data. +In addition, you may wish to filter out other identifiable information, like IP addresses, user agent information, +or form field data. + +Depending on the type of data, we offer several different ways to filter, manipulate, +or obfuscate sensitive information during or before ingestion: + +* <> +* <> + +In addition to utilizing filters, you should regularly review the <> table to ensure +sensitive data is not being ingested. If it is, it's possible to remove or redact it. +See <> for more information. + +[float] +[[apm-built-in-data-filters]] +== Built-in data filters + +// tag::data-filters[] +Built-in data filters allow you to filter or turn off ingestion of the following types of data: + +[options="header"] +|==== +|Data type |Common sensitive data +|<> |Passwords, credit card numbers, authorization, etc. +|<> |Passwords, credit card numbers, etc. +|<> |Client IP address and user agent. +|<> |URLs visited, click events, user browser errors, resources used, etc. +|<> |Sensitive user or business information +|==== +// end::data-filters[] + +[float] +[[apm-custom-data-filters]] +== Custom filters + +// tag::custom-filters[] +Custom filters allow you to filter or redact other types of APM data on ingestion: + +|==== +|<> | Applied at ingestion time. +All agents and fields are supported. Data leaves the instrumented service. +There are no performance overhead implications on the instrumented service. + +|<> | Not supported by all agents. +Data is sanitized before leaving the instrumented service. +Potential overhead implications on the instrumented service +|==== +// end::custom-filters[] + +[float] +[[apm-sensitive-fields]] +== Sensitive fields + +You should review the following fields regularly to ensure sensitive data is not being captured: + +[options="header"] +|==== +| Field | Description | Remedy +| `client.ip` | The client IP address, as forwarded by proxy. | <> +| `http.request.body.original` | The body of the monitored HTTP request. | <> +| `http.request.headers` | The canonical headers of the monitored HTTP request. | <> +| `http.request.socket.remote_address` | The address of the last proxy or end-user (if no proxy). | <> +| `http.response.headers` | The canonical headers of the monitored HTTP response. | <> +| `process.args` | Process arguments. | <> +| `span.db.statement` | Database statement. | <> +| `stacktrace.vars` | A flat mapping of local variables captured in the stack frame | <> +| `url.query` | The query string of the request, e.g. `?pass=hunter2`. | <> +| `user.*` | Logged-in user information. | <> +| `user_agent.*` | Device and version making the network request. | <> +|==== + +//// +Subsections +//// + +:leveloffset: +1 + +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/apm-spaces.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/filtering.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/custom-filter.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/delete.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm/access-api-keys.asciidoc b/docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc similarity index 96% rename from docs/en/observability/apm/access-api-keys.asciidoc rename to docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc index f6fdf10eb3..3a8862fd6f 100644 --- a/docs/en/observability/apm/access-api-keys.asciidoc +++ b/docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc @@ -1,5 +1,5 @@ [[apm-beats-api-keys]] -=== Grant access using API keys += Grant access using API keys 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, @@ -15,7 +15,7 @@ You can create as many API keys per user as necessary. [float] [[apm-beats-api-key-publish]] -==== Create an API key for writing events +== Create an API key for writing events In {kib}, navigate to **{stack-manage-app}** > **API keys** and click **Create API key**. @@ -76,7 +76,7 @@ output.elasticsearch: [float] [[apm-beats-api-key-monitor]] -==== Create an API key for monitoring +== Create an API key for monitoring In {kib}, navigate to **{stack-manage-app}** > **API keys** and click **Create API key**. @@ -120,7 +120,7 @@ monitoring.elasticsearch: [float] [[apm-beats-api-key-es]] -==== Create an API key with {es} APIs +== Create an API key with {es} APIs You can also use {es}'s {ref}/security-api-create-api-key.html[Create API key API] to create a new API key. For example: @@ -165,9 +165,9 @@ POST /_security/api_key See the {ref}/security-api-create-api-key.html[Create API key] reference for more information. -[[apm-learn-more-api-keys]] [float] -==== Learn more about API keys +[[apm-learn-more-api-keys]] +== Learn more about API keys See the {es} API key documentation for more information: diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/security/elastic-stack/index.asciidoc similarity index 92% rename from docs/en/observability/apm/feature-roles.asciidoc rename to docs/en/observability/apm/security/elastic-stack/index.asciidoc index d1acdac6bc..6e67bfc0a2 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/security/elastic-stack/index.asciidoc @@ -1,16 +1,12 @@ [[apm-secure-comms-stack]] -== Secure communication with the {stack} - -++++ -With the {stack} -++++ += Secure communication with the {stack} NOTE: This documentation only applies to the APM Server binary. Use role-based access control or API keys to grant APM Server users access to secured resources. * <> -* <>. +* <> After privileged users have been created, use authentication to connect to a secured Elastic cluster. @@ -23,7 +19,7 @@ A reference of all available <Create a _writer_ user @@ -72,7 +68,7 @@ In general, there are three types of privileges you'll work with: APM users that publish events to {es} need privileges to write to APM data streams. [float] -==== General writer role +=== General writer role To grant an APM user the required privileges for writing events to {es}: @@ -102,7 +98,7 @@ that has the following privileges: //// [[apm-privileges-to-publish-monitoring]] -=== Grant privileges and roles needed for monitoring +== Grant privileges and roles needed for monitoring ++++ Create a _monitoring_ user @@ -119,7 +115,7 @@ depend on the method used to collect that data. [float] [[apm-privileges-to-publish-monitoring-write]] -==== Publish monitoring data +=== Publish monitoring data [IMPORTANT] ==== @@ -130,7 +126,7 @@ Monitoring on {ecloud} is enabled by clicking the *Enable* button in the *Monito [float] [[apm-privileges-to-publish-monitoring-internal]] -===== Internal collection +==== Internal collection If you're using <> to collect metrics about APM Server, {security-features} provides @@ -168,7 +164,7 @@ If you don't use the +apm_system+ user: [float] [[apm-privileges-to-publish-monitoring-metricbeat]] -===== {metricbeat} collection +==== {metricbeat} collection NOTE: When using {metricbeat} to collect metrics, no roles or users need to be created with APM Server. @@ -206,7 +202,7 @@ information. Assign the following roles to the *monitoring user*: [float] [[apm-privileges-to-publish-monitoring-view]] -==== View monitoring data +=== View monitoring data To grant users the required privileges for viewing monitoring data: @@ -243,7 +239,7 @@ need to view monitoring data for APM Server: //// [[apm-privileges-api-key]] -=== Grant privileges and roles needed for API key management +== Grant privileges and roles needed for API key management ++++ Create an _API key_ user @@ -275,7 +271,7 @@ Users with this role can only create API keys that have the same or lower access [float] [[apm-privileges-api-key-example]] -=== Example API key role +== Example API key role The following example assigns the required cluster privileges, and the ingest agent data `apm` API key application privileges to a role named `apm_api_key`: @@ -311,7 +307,7 @@ PUT _security/role/apm_api_key <1> //// [[apm-privileges-agent-central-config]] -=== Grant privileges and roles needed for APM Agent central configuration +== Grant privileges and roles needed for APM Agent central configuration ++++ Create a _central config_ user @@ -319,7 +315,7 @@ PUT _security/role/apm_api_key <1> [float] [[apm-privileges-agent-central-config-server]] -==== APM Server agent central configuration management +=== APM Server agent central configuration management APM Server acts as a proxy between your APM agents and the APM UI. The APM UI communicates any changed settings to APM Server so that your agents only need to poll the Server @@ -355,7 +351,7 @@ TIP: Looking for privileges and roles needed to use central configuration from t See <>. [[apm-privileges-rum-source-map]] -=== Grant privileges and roles needed for reading source maps +== Grant privileges and roles needed for reading source maps ++++ Create a _source map_ user @@ -363,7 +359,7 @@ See <>. [float] [[apm-privileges-rum-source-mapping]] -==== APM Server RUM source mapping +=== APM Server RUM source mapping If <> is enabled, additional privileges are required to read source maps. @@ -390,11 +386,4 @@ See <> for more details. *********************************** *********************************** //// -// [[apm-privileges-create-api-keys]] -// === Grant privileges and roles needed to create APM Server API keys - -// ++++ -// Create an _APM API key_ user -// ++++ - -// CONTENT \ No newline at end of file +include::{observability-docs-root}/docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/security/index.asciidoc b/docs/en/observability/apm/security/index.asciidoc new file mode 100644 index 0000000000..02ab702328 --- /dev/null +++ b/docs/en/observability/apm/security/index.asciidoc @@ -0,0 +1,45 @@ +//// +TO DO: +Does this framing make sense? +//// +[[apm-securing-apm-server]] += Use APM securely + +When setting up Elastic APM, it's critical to ensure that application data is secure from start to finish. +You should approach securing your application data from different perspectives: + +[cols="1,1"] +|=== +| *What kind of data is collected?* +| Ensure that data doesn’t contain sensitive information like passwords, + credit card numbers, health data, or other identifiable information. + + Read more in <>. + +| *How do APM agents and {agent} communicate?* +| Ensure that any communication between APM agents and {agent} + are both encrypted and authenticated. + + Read more in <>. + +| *How do APM Server and the {stack} communicate?* +| Use role-based access control to grant APM Server 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. + + Read more in <>. + +| *Who can use the APM UI?* +| Use role-based access control to grant users access to features of the APM UI. + + Read more in <>. +|=== + +//// +Subsections +//// + +include::{observability-docs-root}/docs/en/observability/apm/security/data-security/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/apm-agents/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/elastic-stack/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/user-access/index.asciidoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/en/observability/apm/security/user-access/annotation.asciidoc b/docs/en/observability/apm/security/user-access/annotation.asciidoc new file mode 100644 index 0000000000..888759bd98 --- /dev/null +++ b/docs/en/observability/apm/security/user-access/annotation.asciidoc @@ -0,0 +1,44 @@ +[[apm-app-annotation-user-create]] += APM UI annotation user + +++++ +Create an annotation user +++++ + +NOTE: By default, the `viewer` and `editor` built-in roles provide read access to Observability annotations. +You only need to create an annotation user to write to the annotations index +({kibana-ref}/apm-settings-kb.html[`xpack.observability.annotations.index`]). + +[float] +[[apm-app-annotation-user]] +== Annotation user + +View deployment annotations in the APM UI. + +. Create a new role, named something like `annotation_user`, +and assign the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`read` on +\{ANNOTATION_INDEX\}+^1^ +|Read-only access to the observability annotation index + +|Index +|`view_index_metadata` on +\{ANNOTATION_INDEX\}+^1^ +|Read-only access to observability annotation index metadata +|==== ++ +^1^ +\{ANNOTATION_INDEX\}+ should be the index name you've defined in +{kibana-ref}/apm-settings-kb.html[`xpack.observability.annotations.index`]. + +. Assign the `annotation_user` created previously, and the roles and privileges necessary to create +a <> or <> APM reader to any users that need to view annotations in the APM UI + +[float] +[[apm-app-annotation-api]] +== Annotation API + +See <>. \ No newline at end of file diff --git a/docs/en/observability/apm/security/user-access/api-ui.asciidoc b/docs/en/observability/apm/security/user-access/api-ui.asciidoc new file mode 100644 index 0000000000..7322aa39e4 --- /dev/null +++ b/docs/en/observability/apm/security/user-access/api-ui.asciidoc @@ -0,0 +1,82 @@ +[[apm-app-api-user]] += APM UI API user + +++++ +Create an API user +++++ + +[float] +[[apm-app-api-config-manager]] +== Central configuration API + +Users can list, search, create, update, and delete central configurations via the APM UI API. + +. Assign the following Kibana feature privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Kibana +|`all` on the APM and User Experience feature +|Allow all access to the APM and User Experience apps +|==== + +[float] +[[apm-app-api-config-reader]] +== Central configuration API reader + +Sometimes a user only needs to list and search central configurations via the APM UI API. + +. Assign the following Kibana feature privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Kibana +|`read` on the APM and User Experience feature +|Allow read access to the APM and User Experience apps +|==== + +[float] +[[apm-app-api-annotation-manager]] +== Annotation API + +Users can use the annotation API to create annotations on their APM data. + +. Create a new role, named something like `annotation_role`, +and assign the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`manage` on +observability-annotations+ index +|Check if the +observability-annotations+ index exists + +|Index +|`read` on +observability-annotations+ index +|Read the +observability-annotations+ index + +|Index +|`create_index` on +observability-annotations+ index +|Create the +observability-annotations+ index + +|Index +|`create_doc` on +observability-annotations+ index +|Create new annotations in the +observability-annotations+ index +|==== + +. Assign the `annotation_role` created previously, +and the following Kibana feature privileges to any annotation API users: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Kibana +|`all` on the APM and User Experience feature +|Allow all access to the APM and User Experience apps +|==== \ No newline at end of file diff --git a/docs/en/observability/apm/security/user-access/central-config.asciidoc b/docs/en/observability/apm/security/user-access/central-config.asciidoc new file mode 100644 index 0000000000..59e189901a --- /dev/null +++ b/docs/en/observability/apm/security/user-access/central-config.asciidoc @@ -0,0 +1,67 @@ +[[apm-app-central-config-user]] += APM UI central config user + +++++ +Create a central config user +++++ + +[float] +[[apm-app-central-config-manager]] +== Central configuration manager + +Central configuration users need to be able to view, create, update, and delete APM agent configurations. + +. Create a new role, named something like `central-config-manager`, and assign the following privileges: ++ +-- +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/central-config-users/widget.asciidoc[] +-- ++ +TIP: Using the deprecated APM Server binaries? +Add the privileges under the **Classic APM indices** tab above. + +. Assign the `central-config-manager` role created in the previous step, +and the following Kibana feature privileges to anyone who needs to manage central configurations: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Kibana +|`All` on the APM and User Experience feature +|Allow full use of the APM and User Experience apps +|==== + +[float] +[[apm-app-central-config-reader]] +== Central configuration reader + +In some instances, you may wish to create a user that can only read central configurations, +but not create, update, or delete them. + +. Create a new role, named something like `central-config-reader`, and assign the following privileges: ++ +-- +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/central-config-users/widget.asciidoc[] +-- ++ +TIP: Using the deprecated APM Server binaries? +Add the privileges under the **Classic APM indices** tab above. + +. Assign the `central-config-reader` role created in the previous step, +and the following Kibana feature privileges to anyone who needs to read central configurations: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Kibana +|`read` on the APM and User Experience feature +|Allow read access to the APM and User Experience apps +|==== + +[float] +[[apm-app-central-config-api]] +== Central configuration API + +See <>. \ No newline at end of file diff --git a/docs/en/observability/apm/security/user-access/index.asciidoc b/docs/en/observability/apm/security/user-access/index.asciidoc new file mode 100644 index 0000000000..4011f17066 --- /dev/null +++ b/docs/en/observability/apm/security/user-access/index.asciidoc @@ -0,0 +1,37 @@ +[[apm-app-users]] += Secure access to the APM UI + +:beat_default_index_prefix: apm +:annotation_index: observability-annotations + +++++ +Secure access to the APM UI +++++ + +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. + +{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a +subset of the privileges needed by APM users. +When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. +If no built-in role is available, you can assign users the privileges needed to accomplish a specific task. +In general, there are three types of privileges you'll work with: + +* **Elasticsearch cluster privileges**: Manage the actions a user can perform against your cluster. +* **Elasticsearch index privileges**: Control access to the data in specific indices your cluster. +* **Kibana feature privileges**: Grant users write or read access to features and apps within Kibana. + +Select your use-case to get started: + +* <> +* <> +* <> +* <> +* <> + +include::{observability-docs-root}/docs/en/observability/apm/security/user-access/reader.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/user-access/annotation.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/user-access/api-ui.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/user-access/central-config.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/security/user-access/storage-explorer.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm/security/user-access/reader.asciidoc b/docs/en/observability/apm/security/user-access/reader.asciidoc new file mode 100644 index 0000000000..f342e277eb --- /dev/null +++ b/docs/en/observability/apm/security/user-access/reader.asciidoc @@ -0,0 +1,77 @@ +[[apm-app-reader]] += APM reader user + +++++ +Create an APM reader user +++++ + +APM reader users typically need to view the APM UI and dashboards and visualizations that use APM data. +These users might also need to create and edit dashboards, visualizations, and machine learning jobs. + +[float] +[[apm-app-reader-full]] +== APM reader + +To create an APM reader user: + +. Create a new role, named something like `read-apm`, and assign the following privileges: ++ +-- +:apm-read-view: +:apm-monitor: +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/apm-app-reader/widget.asciidoc[] +:!apm-read-view: +:!apm-monitor: +-- + +. Assign the `read-apm` role created in the previous step, and the following built-in roles to +any APM reader users: ++ +[options="header"] +|==== +|Role | Purpose + +|`kibana_admin` +|Grants access to all features in Kibana. + +|`machine_learning_admin` +|Grants the privileges required to create, update, and view machine learning jobs +|==== + +[float] +[[apm-app-reader-partial]] +== Partial APM reader + +In some instances, you may wish to restrict certain Kibana apps that a user has access to. + +. Create a new role, named something like `read-apm-partial`, and assign the following privileges: ++ +-- +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/apm-app-reader/widget.asciidoc[] +-- + +. Assign feature privileges to any Kibana feature that the user needs access to. +Here are two examples: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Kibana +| `Read` or `All` on the APM and User Experience feature +| Allow the use of the the APM and User Experience apps + +| Kibana +| `Read` or `All` on Dashboards and Discover +| Allow the user to view, edit, and create dashboards, as well as browse data. +|==== + +. Finally, assign the following role if a user needs to enable and edit machine learning features: ++ +[options="header"] +|==== +|Role | Purpose + +|`machine_learning_admin` +|Grants the privileges required to create, update, and view machine learning jobs +|==== diff --git a/docs/en/observability/apm/security/user-access/storage-explorer.asciidoc b/docs/en/observability/apm/security/user-access/storage-explorer.asciidoc new file mode 100644 index 0000000000..429fb7fe78 --- /dev/null +++ b/docs/en/observability/apm/security/user-access/storage-explorer.asciidoc @@ -0,0 +1,22 @@ +[[apm-app-storage-explorer-user-create]] += APM UI storage explorer user + +++++ +Create a storage explorer user +++++ + +[float] +[[apm-app-storage-explorer-user]] +== Storage Explorer user + +View the **Storage Explorer** in the APM UI. + +. Create a new role, named something like `storage-explorer_user`, +and assign the following privileges: ++ +-- +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/storage-explorer-user/widget.asciidoc[] +-- + +. Assign the `storage-explorer_user` created previously, and the roles and privileges necessary to create +a <> or <> APM reader to any users that need to view **Storage Explorer** in the APM UI. \ No newline at end of file diff --git a/docs/en/observability/apm/setting-up-and-running.asciidoc b/docs/en/observability/apm/setting-up-and-running.asciidoc deleted file mode 100644 index a9a065f614..0000000000 --- a/docs/en/observability/apm/setting-up-and-running.asciidoc +++ /dev/null @@ -1,31 +0,0 @@ - -[[apm-setting-up-and-running]] -== APM Server advanced setup - -++++ -Advanced setup -++++ - -Before reading this section, see the <> -for basic installation and running instructions. - -This section includes additional information on how to set up and run APM Server, including: - -* <> -* <> -* <> -* <> -* <> -* <> - -include::{observability-docs-root}/docs/en/observability/apm/shared-directory-layout.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/keystore.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/command-reference.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/data-ingestion.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/high-availability.asciidoc[] - -include::{observability-docs-root}/docs/en/observability/apm/shared-systemd.asciidoc[] diff --git a/docs/en/observability/apm/shared-docker.asciidoc b/docs/en/observability/apm/shared-docker.asciidoc index 335e3d68f3..90f8af1547 100644 --- a/docs/en/observability/apm/shared-docker.asciidoc +++ b/docs/en/observability/apm/shared-docker.asciidoc @@ -1,5 +1,6 @@ +[float] [[apm-running-on-docker]] -==== Run APM Server on Docker += Run APM Server on Docker Docker images for APM Server are available from the Elastic Docker registry. The base image is https://hub.docker.com/_/ubuntu[ubuntu:22.04]. @@ -15,7 +16,7 @@ https://www.elastic.co/subscriptions[Subscriptions] page for information about Elastic license levels. [float] -===== Pull the image +== Pull the image Obtaining APM Server for Docker is as simple as issuing a +docker pull+ command against the Elastic Docker registry and then, optionally, verifying the image. @@ -58,7 +59,7 @@ The following checks were performed on each of these signatures: endif::[] [float] -===== Configure APM Server on Docker +== Configure APM Server on Docker The Docker image provides several methods for configuring APM Server. The conventional approach is to provide a configuration file via a volume mount, but @@ -66,7 +67,7 @@ it's also possible to create a custom image with your configuration included. [float] -====== Example configuration file +=== Example configuration file Download this example configuration file as a starting point: @@ -76,7 +77,7 @@ curl -L -O https://raw.githubusercontent.com/elastic/apm-server/{branch}/apm-ser ------------------------------------------------ [float] -====== Volume-mounted configuration +=== Volume-mounted configuration One way to configure APM Server on Docker is to provide +apm-server.docker.yml+ via a volume mount. With +docker run+, the volume mount can be specified like this. @@ -99,7 +100,7 @@ the `-E output.elasticsearch.hosts` line with the Cloud ID and elastic password using the syntax shown earlier. [float] -====== Customize your configuration +=== Customize your configuration ifdef::has_docker_label_ex[] The +apm-server.docker.yml+ file you downloaded earlier is configured to deploy {beats} modules based on the Docker labels applied to your containers. See <> for more details. Add labels to your application Docker containers, and they will be picked up by the {beats} autodiscover feature when they are deployed. Here is an example command for an Apache HTTP Server container with labels to configure the {filebeat} and {metricbeat} modules for the Apache HTTP Server: @@ -125,7 +126,7 @@ The +apm-server.docker.yml+ downloaded earlier should be customized for your env endif::[] [float] -====== Custom image configuration +=== Custom image configuration It's possible to embed your APM Server configuration in a custom image. Here is an example Dockerfile to achieve this: diff --git a/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/content.asciidoc b/docs/en/observability/apm/tab-widgets/apm-app-reader/content.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/tab-widgets/apm-app-reader/content.asciidoc rename to docs/en/observability/apm/tab-widgets/apm-app-reader/content.asciidoc diff --git a/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/widget.asciidoc b/docs/en/observability/apm/tab-widgets/apm-app-reader/widget.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/tab-widgets/apm-app-reader/widget.asciidoc rename to docs/en/observability/apm/tab-widgets/apm-app-reader/widget.asciidoc diff --git a/docs/en/observability/apm-ui/tab-widgets/central-config-users/content.asciidoc b/docs/en/observability/apm/tab-widgets/central-config-users/content.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/tab-widgets/central-config-users/content.asciidoc rename to docs/en/observability/apm/tab-widgets/central-config-users/content.asciidoc diff --git a/docs/en/observability/apm-ui/tab-widgets/central-config-users/widget.asciidoc b/docs/en/observability/apm/tab-widgets/central-config-users/widget.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/tab-widgets/central-config-users/widget.asciidoc rename to docs/en/observability/apm/tab-widgets/central-config-users/widget.asciidoc diff --git a/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc b/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc index 84ddaa7c5d..4979d12366 100644 --- a/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc +++ b/docs/en/observability/apm/tab-widgets/install-agents-widget.asciidoc @@ -196,7 +196,7 @@ include::install-agents.asciidoc[tag=rum] hidden=""> ++++ -include::../open-telemetry.asciidoc[tag=otel-get-started] +include::../collect-application-data/open-telemetry/index.asciidoc[tag=otel-get-started] ++++ diff --git a/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/content.asciidoc b/docs/en/observability/apm/tab-widgets/storage-explorer-user/content.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/content.asciidoc rename to docs/en/observability/apm/tab-widgets/storage-explorer-user/content.asciidoc diff --git a/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/widget.asciidoc b/docs/en/observability/apm/tab-widgets/storage-explorer-user/widget.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/widget.asciidoc rename to docs/en/observability/apm/tab-widgets/storage-explorer-user/widget.asciidoc diff --git a/docs/en/observability/apm/apm-performance-diagnostic.asciidoc b/docs/en/observability/apm/troubleshooting/apm-performance-diagnostic.asciidoc similarity index 97% rename from docs/en/observability/apm/apm-performance-diagnostic.asciidoc rename to docs/en/observability/apm/troubleshooting/apm-performance-diagnostic.asciidoc index daa4d6f12a..e7f5e28f71 100644 --- a/docs/en/observability/apm/apm-performance-diagnostic.asciidoc +++ b/docs/en/observability/apm/troubleshooting/apm-performance-diagnostic.asciidoc @@ -1,13 +1,13 @@ [[apm-performance-diagnostic]] -=== APM Server performance diagnostic += APM Server performance diagnostic [[apm-es-backpressure]] [float] -==== Diagnosing backpressure from {es} +== Diagnosing backpressure from {es} When {es} is under excessive load or indexing pressure, APM Server could experience the downstream backpressure when indexing new documents into {es}. Most commonly, backpressure from {es} will manifest itself in the form of higher indexing latency and/or rejected requests, which in return could lead APM Server to deny incoming requests. -As a result, APM agents connected to the affected APM Server will suffer from throttling and/or request timeout when shipping APM events. +As a result, APM agents connected to the affected APM Server will suffer from throttling and/or request timeout when shipping APM events. To quickly identify possible issues try looking for similar error logs lines in APM Server logs: diff --git a/docs/en/observability/apm/apm-response-codes.asciidoc b/docs/en/observability/apm/troubleshooting/apm-response-codes.asciidoc similarity index 86% rename from docs/en/observability/apm/apm-response-codes.asciidoc rename to docs/en/observability/apm/troubleshooting/apm-response-codes.asciidoc index d6d1dc1f01..468a14650e 100644 --- a/docs/en/observability/apm/apm-response-codes.asciidoc +++ b/docs/en/observability/apm/troubleshooting/apm-response-codes.asciidoc @@ -1,30 +1,30 @@ [[apm-common-response-codes]] -=== APM Server response codes += APM Server response codes [[apm-bad-request]] [float] -==== HTTP 400: Data decoding error / Data validation error +== HTTP 400: Data decoding error / Data validation error The most likely cause for this error is using incompatible versions of {apm-agent} and APM Server. See the <> to verify compatibility. [[apm-event-too-large]] [float] -==== HTTP 400: Event too large +== HTTP 400: Event too large APM agents communicate with the APM server by sending events in an HTTP request. Each event is sent as its own line in the HTTP request body. If events are too large, you should consider increasing the <> setting in the APM integration, and adjusting relevant settings in the agent. [[apm-unauthorized]] [float] -==== HTTP 401: Invalid token +== HTTP 401: Invalid token Either the <> in the request header doesn't match the secret token configured in the APM integration, or the <> is invalid. [[apm-forbidden]] [float] -==== HTTP 403: Forbidden request +== HTTP 403: Forbidden request Either you are sending requests to a <> endpoint without RUM enabled, or a request is coming from an origin not specified in the APM integration settings. @@ -32,7 +32,7 @@ See the <> setting for more information. [[apm-request-timed-out]] [float] -==== HTTP 503: Request timed out waiting to be processed +== HTTP 503: Request timed out waiting to be processed This happens when APM Server exceeds the maximum number of requests that it can process concurrently. To alleviate this problem, you can try to: reduce the sample rate and/or reduce the collected stack trace information. diff --git a/docs/en/observability/apm/apm-server-down.asciidoc b/docs/en/observability/apm/troubleshooting/apm-server-down.asciidoc similarity index 96% rename from docs/en/observability/apm/apm-server-down.asciidoc rename to docs/en/observability/apm/troubleshooting/apm-server-down.asciidoc index f9e3d00378..599277aca3 100644 --- a/docs/en/observability/apm/apm-server-down.asciidoc +++ b/docs/en/observability/apm/troubleshooting/apm-server-down.asciidoc @@ -1,5 +1,5 @@ [[apm-server-es-down]] -=== What happens when APM Server or {es} is down? += What happens when APM Server or {es} is down? *If {es} is down* diff --git a/docs/en/observability/apm-ui/troubleshooting.asciidoc b/docs/en/observability/apm/troubleshooting/common-problems.asciidoc similarity index 52% rename from docs/en/observability/apm-ui/troubleshooting.asciidoc rename to docs/en/observability/apm/troubleshooting/common-problems.asciidoc index 2dced7c1c2..d3451c3554 100644 --- a/docs/en/observability/apm-ui/troubleshooting.asciidoc +++ b/docs/en/observability/apm/troubleshooting/common-problems.asciidoc @@ -1,29 +1,17 @@ -[[apm-app-troubleshooting]] -== Troubleshoot - -++++ -Troubleshoot -++++ - -This section describes common problems you might encounter with the APM UI. -If your issue is potentially related to other components of the APM ecosystem, -don't forget to check our other troubleshooting guides or discussion forum: - -* {apm-guide-ref}/troubleshoot-apm.html[APM Server troubleshooting] -* {apm-dotnet-ref}/troubleshooting.html[.NET agent troubleshooting] -* {apm-go-ref}/troubleshooting.html[Go agent troubleshooting] -* {apm-ios-ref}/troubleshooting.html[iOS agent troubleshooting] -* {apm-java-ref}/trouble-shooting.html[Java agent troubleshooting] -* {apm-node-ref}/troubleshooting.html[Node.js agent troubleshooting] -* {apm-php-ref}/troubleshooting.html[PHP agent troubleshooting] -* {apm-py-ref}/troubleshooting.html[Python agent troubleshooting] -* {apm-ruby-ref}/debugging.html[Ruby agent troubleshooting] -* {apm-rum-ref}/troubleshooting.html[RUM troubleshooting] -* https://discuss.elastic.co/c/apm[APM discussion forum]. - -[discrete] -[[troubleshooting-apm-app]] -== Troubleshoot common APM UI problems +[[apm-common-problems]] += Common problems + +This section describes common problems you might encounter when using APM Server and the APM UI in {kib}. + +*APM Server*: + +* <> +* <> +* <> +* <> +* <> + +*APM UI*: * <> * <> @@ -31,9 +19,148 @@ don't forget to check our other troubleshooting guides or discussion forum: * <> * <> +[float] +[[apm-no-data-indexed]] +== No data is indexed + +If no data shows up in {es}, first make sure that your APM components are properly connected. + +include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/no-data-indexed-widget.asciidoc[] + + +[float] +[[apm-common-ssl-problems]] +== Common SSL-related problems + +* <> +* <> +* <> +* <> +* <> + + +[float] +[[apm-ssl-client-fails]] +=== SSL client fails to connect + +The target host might be unreachable or the certificate may not be valid. +To fix this problem: + +. Make sure that the APM Server process on the target host is running and you can connect to it. +Try to ping the target host to verify that you can reach it from the host running APM Server. +Then use either `nc` or `telnet` to make sure that the port is available. For example: ++ +[source,shell] +---- +ping +telnet 5044 +---- + +. Verify that the certificate is valid and that the hostname and IP match. +. Use OpenSSL to test connectivity to the target server and diagnose problems. +See the https://www.openssl.org/docs/manmaster/man1/openssl-s_client.html[OpenSSL documentation] for more info. + +[float] +[[apm-cannot-validate-certificate]] +=== x509: cannot validate certificate for because it doesn't contain any IP SANs + +This happens because your certificate is only valid for the hostname present in the Subject field. +To resolve this problem, try one of these solutions: + +* Create a DNS entry for the hostname, mapping it to the server's IP. +* Create an entry in `/etc/hosts` for the hostname. Or, on Windows, add an entry to +`C:\Windows\System32\drivers\etc\hosts`. +* Re-create the server certificate and add a Subject Alternative Name (SAN) for the IP address of the server. This makes the +server's certificate valid for both the hostname and the IP address. + +[float] +[[apm-getsockopt-no-route-to-host]] +=== getsockopt: no route to host + +This is not an SSL problem. It's a networking problem. Make sure the two hosts can communicate. + +[float] +[[apm-getsockopt-connection-refused]] +=== getsockopt: connection refused + +This is not an SSL problem. Make sure that {ls} is running and that there is no firewall blocking the traffic. + +[float] +[[apm-target-machine-refused-connection]] +=== No connection could be made because the target machine actively refused it + +A firewall is refusing the connection. Check if a firewall is blocking the traffic on the client, the network, or the +destination host. + +[[apm-io-timeout]] +[float] +== I/O Timeout + +I/O Timeouts can occur when your timeout settings across the stack are not configured correctly, +especially when using a load balancer. + +You may see an error like the one below in the {apm-agent} logs, and/or a similar error on the APM Server side: + +[source,logs] +---- +[ElasticAPM] APM Server responded with an error: +"read tcp 123.34.22.313:8200->123.34.22.40:41602: i/o timeout" +---- + +To fix this, ensure timeouts are incrementing from the {apm-agent}, +through your load balancer, to the APM Server. + +By default, the agent timeouts are set at 10 seconds, and the server timeout is set at 3600 seconds. +Your load balancer should be set somewhere between these numbers. + +For example: + +[source,txt] +---- +APM agent --> Load Balancer --> APM Server + 10s 15s 3600s +---- + +The APM Server timeout can be configured by updating the +<>. + +[[apm-field-limit-exceeded]] +[float] +== Field limit exceeded + +When adding too many distinct tag keys on a transaction or span, +you risk creating a link:{ref}/mapping.html#mapping-limit-settings[mapping explosion]. + +For example, you should avoid that user-specified data, +like URL parameters, is used as a tag key. +Likewise, using the current timestamp or a user ID as a tag key is not a good idea. +However, tag *values* with a high cardinality are not a problem. +Just try to keep the number of distinct tag keys at a minimum. + +The symptom of a mapping explosion is that transactions and spans are not indexed anymore after a certain time. Usually, on the next day, +the spans and transactions will be indexed again because a new index is created each day. +But as soon as the field limit is reached, indexing stops again. + +In the agent logs, you won't see a sign of failures as the APM server asynchronously sends the data it received from the agents to {es}. However, the APM server and {es} log a warning like this: + +[source,logs] +---- +{\"type\":\"illegal_argument_exception\",\"reason\":\"Limit of total fields [1000] in [INDEX_NAME] has been exceeded\"} +---- + +[[apm-tail-based-sampling-memory-disk-io]] +[float] +== Tail-based sampling causing high system memory usage and high disk IO + +Tail-based sampling requires minimal memory to run, and there should not be a noticeable increase in RSS memory usage. +However, since tail-based sampling writes data to disk, +it is possible to see a significant increase in OS page cache memory usage due to disk IO. +If you see a drop in throughput and excessive disk activity after enabling tail-based sampling, +please ensure that there is enough memory headroom in the system for OS page cache to perform disk IO efficiently. + [float] [[no-apm-data-found]] -=== No APM data found +== Data doesn't appear in the APM UI This section can help with any of the following: @@ -45,15 +172,64 @@ This section can help with any of the following: These problems are likely to be caused by a missing index template or ingest pipeline. By default, {fleet} sets up these and other APM assets when the APM integration is installed. Try reinstalling the APM integration by navigating to -**Integrations** > **Elastic APM** > **Manage in Fleet** > **Settings** > **Reinstall Elastic APM**. +**Integrations** → **Elastic APM** → **Manage in Fleet** → **Settings** → **Reinstall Elastic APM**. Because assets cannot be applied to indices retroactively, after reinstalling the APM integration you must either wait for the index to rollover or force a rollover. To force a rollover, use the {ref}/indices-rollover-index.html[rollover API] to target the relevant {apm-guide-ref}/apm-data-streams.html[APM data streams]. +[float] +[[apm-data-indexed-no-apm]] +=== Data is indexed but doesn't appear in the APM UI + +The APM UI relies on index mappings to query and display data. +If your APM data isn't showing up in the APM UI, but is elsewhere in {kib}, like the Discover app, +you may have a missing index mapping. + +You can determine if a field was mapped correctly with the `_mapping` API. +For example, run the following command in the {kib} {kibana-ref}/console-kibana.html[console]. +This will display the field data type of the `service.name` field. + +[source,curl] +---- +GET *apm*/_mapping/field/service.name +---- + +If the `mapping.name.type` is `"text"`, your APM indices were not set up correctly. + +[source,yml] +---- +".ds-metrics-apm.transaction.1m-default-2023.04.12-000038": { + "mappings": { + "service.name": { + "full_name": "service.name", + "mapping": { + "name": { + "type": "text" <1> + } + } + } + } +} +---- +<1> The `service.name` `mapping.name.type` would be `"keyword"` if this field had been set up correctly. + +To fix this problem, install the APM integration by following these steps: + +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc[leveloffset=+2,tag=install-apm-integration] + +This will reinstall the APM index templates and trigger a data stream index rollover. + +You can verify the correct index templates were installed by running the following command in the {kib} console: + +[source,curl] +---- +GET /_index_template/traces-apm +---- + [float] [[troubleshooting-too-many-transactions]] -=== Too many unique transaction names +== Too many unique transaction names Transaction names are defined in each APM agent; when an APM agent supports a framework, it includes logic for naming the transactions that the framework creates. @@ -118,7 +294,7 @@ See the relevant {apm-agents-ref}[Agent API documentation] to adjust how you're [float] [[troubleshooting-unknown-route]] -=== Unknown route +== Unknown route The <> will only display helpful information when the transactions in your services are named correctly. @@ -139,7 +315,7 @@ You can also use the agent's public API to manually set a name for the transacti [float] [[troubleshooting-fields-unsearchable]] -=== Fields are not searchable +== Fields are not searchable In Elasticsearch, index templates are used to define settings and mappings that determine how fields should be analyzed. The recommended index templates for APM are installed by {fleet} when the Elastic APM integration is installed. @@ -173,7 +349,7 @@ These are dynamic by default, which means they will be indexed and become search [float] [[service-map-rum-connections]] -=== Service Maps: no connection between client and server +== Service Maps: no connection between client and server If the service map is not showing an expected connection between the client and server, it's likely because you haven't configured diff --git a/docs/en/observability/apm/debugging.asciidoc b/docs/en/observability/apm/troubleshooting/debugging.asciidoc similarity index 97% rename from docs/en/observability/apm/debugging.asciidoc rename to docs/en/observability/apm/troubleshooting/debugging.asciidoc index 15bd1f613c..680fc8746a 100644 --- a/docs/en/observability/apm/debugging.asciidoc +++ b/docs/en/observability/apm/troubleshooting/debugging.asciidoc @@ -1,5 +1,5 @@ [[apm-enable-apm-server-debugging]] -=== Enable APM Server binary debugging += Enable APM Server binary debugging ++++ APM Server binary debugging diff --git a/docs/en/observability/apm/troubleshoot-apm.asciidoc b/docs/en/observability/apm/troubleshooting/index.asciidoc similarity index 66% rename from docs/en/observability/apm/troubleshoot-apm.asciidoc rename to docs/en/observability/apm/troubleshooting/index.asciidoc index 5823d9c248..089d18859d 100644 --- a/docs/en/observability/apm/troubleshoot-apm.asciidoc +++ b/docs/en/observability/apm/troubleshooting/index.asciidoc @@ -1,5 +1,9 @@ [[apm-troubleshoot-apm]] -== Troubleshoot += Troubleshooting APM + +++++ +Troubleshooting +++++ This section provides solutions to common questions and problems, and processing and performance guidance. @@ -15,12 +19,11 @@ For additional help with other APM components, see the links below. [float] [[apm-troubleshooting-docs]] -=== Troubleshooting documentation +== Troubleshooting documentation {agent}, the APM UI, and each {apm-agent} has its own troubleshooting guide: * {fleet-guide}/troubleshooting-intro.html[*{fleet} and {agent}* troubleshooting] -* <> * {apm-android-ref}/faq.html[*Android agent* FAQ] * {apm-dotnet-ref-v}/troubleshooting.html[*.NET agent* troubleshooting] * {apm-go-ref-v}/troubleshooting.html[*Go agent* troubleshooting] @@ -34,7 +37,7 @@ For additional help with other APM components, see the links below. [float] [[apm-elastic-support]] -=== Elastic Support +== Elastic Support We offer a support experience unlike any other. Our team of professionals 'speak human and code' and love making your day. @@ -42,19 +45,18 @@ https://www.elastic.co/subscriptions[Learn more about subscriptions]. [float] [[apm-discussion-forum]] -=== Discussion forum +== Discussion forum For additional questions and feature requests, visit our https://discuss.elastic.co/c/apm[discussion forum]. -include::common-problems.asciidoc[] - -include::apm-server-down.asciidoc[] - -include::apm-response-codes.asciidoc[] - -include::processing-performance.asciidoc[] +:leveloffset: +1 -include::{observability-docs-root}/docs/en/observability/apm/debugging.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/common-problems.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/apm-server-down.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/apm-response-codes.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/processing-performance.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/debugging.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/troubleshooting/apm-performance-diagnostic.asciidoc[] -include::apm-performance-diagnostic.asciidoc[] \ No newline at end of file +:!leveloffset: diff --git a/docs/en/observability/apm/processing-performance.asciidoc b/docs/en/observability/apm/troubleshooting/processing-performance.asciidoc similarity index 98% rename from docs/en/observability/apm/processing-performance.asciidoc rename to docs/en/observability/apm/troubleshooting/processing-performance.asciidoc index 6e98bbba0f..9db4040411 100644 --- a/docs/en/observability/apm/processing-performance.asciidoc +++ b/docs/en/observability/apm/troubleshooting/processing-performance.asciidoc @@ -1,5 +1,5 @@ [[apm-processing-and-performance]] -=== Processing and performance += Processing and performance APM Server performance depends on a number of factors: memory and CPU available, network latency, transaction sizes, workload patterns, diff --git a/docs/en/observability/apm/upgrading-to-8.x.asciidoc b/docs/en/observability/apm/upgrading-to-8.x.asciidoc index 35bd9536ff..5279a463dc 100644 --- a/docs/en/observability/apm/upgrading-to-8.x.asciidoc +++ b/docs/en/observability/apm/upgrading-to-8.x.asciidoc @@ -80,10 +80,10 @@ See the {stack-ref}/upgrading-elastic-stack.html[{stack} Installation and Upgrad . **Install the APM integration via the {fleet} UI** + -include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm-server.asciidoc[tag=why-apm-integration] +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc[leveloffset=+2,tag=why-apm-integration] + -- -include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm-server.asciidoc[tag=install-apm-integration] +include::{observability-docs-root}/docs/en/observability/apm/getting-started-apm/get-started-with-apm-server-binary.asciidoc[leveloffset=+2,tag=install-apm-integration] -- . **Install the {version} APM Server release** diff --git a/docs/en/observability/apm-ui/agent-explorer.asciidoc b/docs/en/observability/apm/view-and-analyze/agent-explorer.asciidoc similarity index 95% rename from docs/en/observability/apm-ui/agent-explorer.asciidoc rename to docs/en/observability/apm/view-and-analyze/agent-explorer.asciidoc index 1197b7538e..925c5f62c3 100644 --- a/docs/en/observability/apm-ui/agent-explorer.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/agent-explorer.asciidoc @@ -1,5 +1,5 @@ [[apm-agent-explorer]] -=== APM Agent explorer += APM Agent explorer ++++ Identify deployment details for APM agents diff --git a/docs/en/observability/apm-ui/errors.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/errors.asciidoc similarity index 99% rename from docs/en/observability/apm-ui/errors.asciidoc rename to docs/en/observability/apm/view-and-analyze/drill-down/errors.asciidoc index cf6ed775c3..32627e40af 100644 --- a/docs/en/observability/apm-ui/errors.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/drill-down/errors.asciidoc @@ -1,5 +1,5 @@ [[apm-errors]] -=== Errors += Errors TIP: {apm-guide-ref}/data-model-errors.html[Errors] are groups of exceptions with a similar exception or log message. diff --git a/docs/en/observability/apm/view-and-analyze/drill-down/index.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/index.asciidoc new file mode 100644 index 0000000000..27ee8cb860 --- /dev/null +++ b/docs/en/observability/apm/view-and-analyze/drill-down/index.asciidoc @@ -0,0 +1,26 @@ +[[apm-ui-drill-down]] += Drill down into application data + +++++ +Drill down into data +++++ + +Notice something awry? Select a service or trace and dive deeper with: + +* <> +* <> +* <> +* <> +* <> +* <> + +:leveloffset: +1 + +include::transactions.asciidoc[] +include::spans.asciidoc[] +include::errors.asciidoc[] +include::metrics.asciidoc[] +include::infrastructure.asciidoc[] +include::logs.asciidoc[] + +:!leveloffset: diff --git a/docs/en/observability/apm-ui/infrastructure.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/infrastructure.asciidoc similarity index 97% rename from docs/en/observability/apm-ui/infrastructure.asciidoc rename to docs/en/observability/apm/view-and-analyze/drill-down/infrastructure.asciidoc index 41648d2178..5ab523e232 100644 --- a/docs/en/observability/apm-ui/infrastructure.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/drill-down/infrastructure.asciidoc @@ -1,5 +1,5 @@ [[apm-infrastructure]] -=== Infrastructure += Infrastructure beta::[] diff --git a/docs/en/observability/apm-ui/logs.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/logs.asciidoc similarity index 63% rename from docs/en/observability/apm-ui/logs.asciidoc rename to docs/en/observability/apm/view-and-analyze/drill-down/logs.asciidoc index 879ba8fa0e..d65da83508 100644 --- a/docs/en/observability/apm-ui/logs.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/drill-down/logs.asciidoc @@ -1,5 +1,5 @@ [[apm-logs]] -=== Logs += Logs The *Logs* tab shows contextual logs for the selected service. @@ -16,3 +16,15 @@ see {observability-guide}/application-logs.html[log correlation] image::./images/logs.png[Example view of the Logs tab in APM UI in Kibana] TIP: Logs displayed on this page are filtered on `service.name` + +[[apm-logs-correlation]] +== Integrate with logging frameworks + +Elastic APM integrates with popular logging frameworks, making it easy to correlate your logs and traces. +This enables you to: + +* View the context of a log and the parameters provided by a user +* View all logs belonging to a particular trace +* Easily move between logs and traces when debugging application issues + +See the <> guide to get started. diff --git a/docs/en/observability/apm-ui/metrics.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/metrics.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/metrics.asciidoc rename to docs/en/observability/apm/view-and-analyze/drill-down/metrics.asciidoc index 987581c9d0..72e30e4c95 100644 --- a/docs/en/observability/apm-ui/metrics.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/drill-down/metrics.asciidoc @@ -1,5 +1,5 @@ [[apm-metrics]] -=== Metrics += Metrics The *Metrics* overview provides APM agent-specific metrics, which lets you perform more in-depth root cause analysis investigations within the APM UI. diff --git a/docs/en/observability/apm-ui/spans.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/spans.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/spans.asciidoc rename to docs/en/observability/apm/view-and-analyze/drill-down/spans.asciidoc index 495cb5c3f9..2759849a21 100644 --- a/docs/en/observability/apm-ui/spans.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/drill-down/spans.asciidoc @@ -1,5 +1,5 @@ [[apm-spans]] -=== Trace sample timeline += Trace sample timeline The trace sample timeline visualization is a bird's-eye view of what your application was doing while it was trying to respond to a request. This makes it useful for visualizing where a selected transaction spent most of its time. @@ -24,7 +24,7 @@ image::./images/apm-span-detail.png[Example view of a span detail in the APM UI [float] [[trace-sample-investigate]] -==== Investigate +== Investigate The trace sample timeline features an **Investigate** button which provides a quick way to jump to other areas of the Elastic Observability UI while maintaining the context of the currently selected trace sample. @@ -40,7 +40,7 @@ For example, quickly view: [float] [[distributed-tracing]] -==== Distributed tracing +== Distributed tracing When a trace travels through multiple services it is known as a _distributed trace_. In APM, the colors in a distributed trace represent different services and diff --git a/docs/en/observability/apm-ui/transactions.asciidoc b/docs/en/observability/apm/view-and-analyze/drill-down/transactions.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/transactions.asciidoc rename to docs/en/observability/apm/view-and-analyze/drill-down/transactions.asciidoc index 9a4a7c436b..eae2e0e4ee 100644 --- a/docs/en/observability/apm-ui/transactions.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/drill-down/transactions.asciidoc @@ -1,5 +1,5 @@ [[apm-transactions]] -=== Transactions += Transactions TIP: A {apm-guide-ref}/data-model-transactions.html[transaction] describes an event captured by an Elastic APM agent instrumenting a service. APM agents automatically collect performance metrics on HTTP requests, database queries, and much more. @@ -53,7 +53,7 @@ See <> for more information. [discrete] [[transactions-table]] -=== Transactions table +== Transactions table The *Transactions* table displays a list of _transaction groups_ for the selected service. In other words, this view groups all transactions of the same name together, @@ -78,7 +78,7 @@ refer to the documentation for each {apm-agents-ref}[APM Agent] you've implement [discrete] [[rum-transaction-overview]] -=== RUM Transaction overview +== RUM Transaction overview The transaction overview page is customized for the JavaScript RUM agent. Specifically, the page highlights *page load times* for your service: @@ -93,7 +93,7 @@ are available in the Observability User Experience tab. [discrete] [[transaction-details]] -=== Transaction details +== Transaction details Selecting a transaction group will bring you to the *transaction* details. This page is visually similar to the transaction overview, but it shows data from all transactions within @@ -104,7 +104,7 @@ image::./images/apm-transactions-overview.png[Example view of response time dist [discrete] [[transaction-duration-distribution]] -==== Latency distribution +=== Latency distribution The latency distribution shows a plot of all transaction durations for the given time period. The following screenshot shows a typical distribution @@ -118,7 +118,7 @@ Click and drag to select a latency duration _bucket_ to display up to 500 trace [discrete] [[transaction-trace-sample]] -==== Trace samples +=== Trace samples Trace samples are based on the _bucket_ selection in the *Latency distribution* chart; update the samples by selecting a new _bucket_. @@ -170,7 +170,7 @@ image::./images/apm-logs-tab.png[APM logs tab] [discrete] [[transaction-latency-correlations]] -==== Correlations +=== Correlations Correlations surface attributes of your data that are potentially correlated with high-latency or erroneous transactions. To learn more, see <>. diff --git a/docs/en/observability/apm-ui/advanced-queries.asciidoc b/docs/en/observability/apm/view-and-analyze/filter-and-search/advanced-queries.asciidoc similarity index 95% rename from docs/en/observability/apm-ui/advanced-queries.asciidoc rename to docs/en/observability/apm/view-and-analyze/filter-and-search/advanced-queries.asciidoc index 6b5f20dd27..a37d7cf7d3 100644 --- a/docs/en/observability/apm-ui/advanced-queries.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/filter-and-search/advanced-queries.asciidoc @@ -1,5 +1,9 @@ [[apm-advanced-queries]] -=== Query your data += Use advanced queries on your application data + +++++ +Advanced queries +++++ Querying your APM data is an essential tool that can make finding bottlenecks in your code even more straightforward. @@ -11,7 +15,7 @@ You can select the query bar and hit the down arrow on your keyboard to begin sc [float] [[apm-app-advanced-queries]] -=== Querying in the APM UI +== Querying in the APM UI When querying in the APM UI, you’re merely searching and selecting data from fields in {es} documents. Queries entered into the query bar are also added as parameters to the URL, so it’s easy to share a specific query or view with others. @@ -28,7 +32,7 @@ To learn more about the {kib} query language capabilities, see the {kibana-ref}/ [float] [[apm-app-queries]] -==== APM UI queries +=== APM UI queries APM queries can be handy for removing noise from your data in the <>, <>, <>, <>, and <> views. @@ -46,7 +50,7 @@ Or filter the list by including the service version and the Kubernetes pod it's [float] [[discover-advanced-queries]] -=== Querying in Discover +== Querying in Discover Alternatively, you can query your APM documents in {kibana-ref}/discover.html[*Discover*]. Querying documents in *Discover* works the same way as queries in the APM UI, @@ -54,7 +58,7 @@ and *Discover* supports all of the example APM UI queries shown on this page. [float] [[discover-queries]] -==== Discover queries +=== Discover queries One example where you may want to make use of *Discover* is to view _all_ transactions for an endpoint instead of just a sample. diff --git a/docs/en/observability/apm/cross-cluster-search.asciidoc b/docs/en/observability/apm/view-and-analyze/filter-and-search/cross-cluster-search.asciidoc similarity index 94% rename from docs/en/observability/apm/cross-cluster-search.asciidoc rename to docs/en/observability/apm/view-and-analyze/filter-and-search/cross-cluster-search.asciidoc index 282767474e..5fa57c4030 100644 --- a/docs/en/observability/apm/cross-cluster-search.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/filter-and-search/cross-cluster-search.asciidoc @@ -1,5 +1,9 @@ [[apm-cross-cluster-search]] -=== Cross-cluster search += Cross-cluster search with application data + +++++ +Cross-cluster search +++++ Elastic APM utilizes {es}'s cross-cluster search functionality. Cross-cluster search lets you run a single search request against one or more @@ -10,7 +14,7 @@ and allowing for better performance while managing multiple observability use ca [float] [[apm-set-up-cross-cluster-search]] -==== Set up cross-cluster search +== Set up cross-cluster search *Step 1. Set up remote clusters.* diff --git a/docs/en/observability/apm-ui/filters.asciidoc b/docs/en/observability/apm/view-and-analyze/filter-and-search/filters.asciidoc similarity index 94% rename from docs/en/observability/apm-ui/filters.asciidoc rename to docs/en/observability/apm/view-and-analyze/filter-and-search/filters.asciidoc index b2aa0f0fbd..573bcc0653 100644 --- a/docs/en/observability/apm-ui/filters.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/filter-and-search/filters.asciidoc @@ -1,8 +1,8 @@ [[apm-filters]] -=== Filters += Filter application data ++++ -Filter data +Filters ++++ Global filters are ways you can filter data across the APM UI based on a specific @@ -20,13 +20,13 @@ of information, see <>. [discrete] [[global-time-range]] -==== Global time range +== Global time range The global time range filter in {kib} restricts APM data to a specific time period. [discrete] [[environment-selector]] -==== Service environment filter +== Service environment filter The environment selector is a global filter for `service.environment`. It allows you to view only relevant data and is especially useful for separating development from production environments. diff --git a/docs/en/observability/apm/view-and-analyze/filter-and-search/index.asciidoc b/docs/en/observability/apm/view-and-analyze/filter-and-search/index.asciidoc new file mode 100644 index 0000000000..4b93e3ceee --- /dev/null +++ b/docs/en/observability/apm/view-and-analyze/filter-and-search/index.asciidoc @@ -0,0 +1,22 @@ +[[apm-filter-and-search-data]] += Filter and search application data + +++++ +Filter and search data +++++ + +Because Elastic APM is built on top of the {stack}, you have the full power of Elastic's powerful +search capabilities to filter and search through your application data. Mastering how to filter and +search your data can help you find bottlenecks in your code faster: + +* Use global filters to <> across the APM UI based on a specific time range or environment. +* Use <> on your data to filter on specific pieces of information. +* Use {es}'s <> functionality to search APM data across multiple sources. + +:leveloffset: +1 + +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/filter-and-search/filters.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/filter-and-search/advanced-queries.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/filter-and-search/cross-cluster-search.asciidoc[] + +:!leveloffset: \ No newline at end of file diff --git a/docs/en/observability/apm/view-and-analyze/index.asciidoc b/docs/en/observability/apm/view-and-analyze/index.asciidoc new file mode 100644 index 0000000000..a9a946c0c2 --- /dev/null +++ b/docs/en/observability/apm/view-and-analyze/index.asciidoc @@ -0,0 +1,39 @@ +[[apm-view-and-analyze-data]] += View and analyze data + +After you've started <>, +you can open the APM UI in {kib} to view your data in a variety of visualizations and +start analyzing data. + +The APM UI allows you to monitor your software services and applications in real-time. +You can visualize detailed performance information on your services, +identify and analyze errors, +and monitor host-level and APM agent-specific metrics like JVM and Go runtime metrics. + +Having access to application-level insights with just a few clicks can drastically decrease the time you spend +debugging errors, slow response times, and crashes. + +For example, you can see information about response times, requests per minute, and status codes per endpoint. +You can even dive into a specific request sample and get a complete waterfall view of what your application is spending its time on. +You might see that your bottlenecks are in database queries, cache calls, or external requests. +For each incoming request and each application error, +you can also see contextual information such as the request header, user information, +system values, or custom data that you manually attached to the request. + +To get started with the APM UI: + +* Start with quick, high-level <> that show you the overall health and performance of + your application. +* <> for specific services or traces to get additional insight into + your application. +* Learn how to get the most out of your data by mastering how to <> + in {kib}, getting tips on <>, and taking advantage of + <>. + +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/ui-overview/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/drill-down/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/filter-and-search/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/interpret/index.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/machine-learning.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/agent-explorer.asciidoc[leveloffset=+1] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/settings.asciidoc[leveloffset=+1] diff --git a/docs/en/observability/apm-ui/correlations.asciidoc b/docs/en/observability/apm/view-and-analyze/interpret/correlations.asciidoc similarity index 96% rename from docs/en/observability/apm-ui/correlations.asciidoc rename to docs/en/observability/apm/view-and-analyze/interpret/correlations.asciidoc index b03e3b7895..36ba4cc963 100644 --- a/docs/en/observability/apm-ui/correlations.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/interpret/correlations.asciidoc @@ -1,5 +1,5 @@ [[apm-correlations]] -=== Find transaction latency and failure correlations += Find transaction latency and failure correlations Correlations surface attributes of your data that are potentially correlated with high-latency or erroneous transactions. For example, if you are a site @@ -17,7 +17,7 @@ NOTE: Queries within the APM UI are also applied to the correlations. [discrete] [[correlations-latency]] -==== Find high transaction latency correlations +== Find high transaction latency correlations The correlations on the *Latency correlations* tab help you discover which attributes are contributing to increased transaction latency. @@ -57,7 +57,7 @@ filtered out, you can begin viewing sample traces to continue your investigation [discrete] [[correlations-error-rate]] -==== Find failed transaction correlations +== Find failed transaction correlations The correlations on the *Failed transaction correlations* tab help you discover which attributes are most influential in distinguishing between transaction diff --git a/docs/en/observability/apm-ui/deployment-annotations.asciidoc b/docs/en/observability/apm/view-and-analyze/interpret/deployment-annotations.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/deployment-annotations.asciidoc rename to docs/en/observability/apm/view-and-analyze/interpret/deployment-annotations.asciidoc index 64ec043eac..7c455096a2 100644 --- a/docs/en/observability/apm-ui/deployment-annotations.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/interpret/deployment-annotations.asciidoc @@ -1,5 +1,5 @@ [[apm-transactions-annotations]] -=== Track deployments with annotations += Track deployments with annotations ++++ Track deployments with annotations diff --git a/docs/en/observability/apm/view-and-analyze/interpret/index.asciidoc b/docs/en/observability/apm/view-and-analyze/interpret/index.asciidoc new file mode 100644 index 0000000000..668061b4ff --- /dev/null +++ b/docs/en/observability/apm/view-and-analyze/interpret/index.asciidoc @@ -0,0 +1,33 @@ +[[apm-interpret-data]] += Interpret application data + +++++ +Interpret data +++++ + +Learn how to get the most out of your data using the APM UI. + +[cols="1,1"] +|=== +| <> +| Surface characteristics of your data that are potentially correlated with high-latency or erroneous transactions. + +| <> +| Annotations enable you to easily determine if your deployment has increased response times for an end-user or if the memory/CPU footprint of your application has changed. + +| <> +| Use session tracking via a globally unique identifier to explore the activities of a specific user during a specific period of time. + +| <> +| Learn how your AWS Lambda functions relate to and depend on other services, and get insight into function execution and runtime behavior, like lambda duration, cold start rate, cold start duration, compute usage, memory usage, and more. + +|=== + +:leveloffset: +1 + +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/interpret/correlations.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/interpret/deployment-annotations.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/interpret/mobile-session-explorer.asciidoc[] +include::{observability-docs-root}/docs/en/observability/apm/view-and-analyze/interpret/lambda.asciidoc[] + +:!leveloffset: \ No newline at end of file diff --git a/docs/en/observability/apm-ui/lambda.asciidoc b/docs/en/observability/apm/view-and-analyze/interpret/lambda.asciidoc similarity index 94% rename from docs/en/observability/apm-ui/lambda.asciidoc rename to docs/en/observability/apm/view-and-analyze/interpret/lambda.asciidoc index e0cbf756ce..d72b210e2d 100644 --- a/docs/en/observability/apm-ui/lambda.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/interpret/lambda.asciidoc @@ -1,5 +1,5 @@ [[apm-lambda]] -=== Observe Lambda functions += Observe Lambda functions Elastic APM provides performance and error monitoring for AWS Lambda functions. See how your Lambda functions relate to and depend on other services, and @@ -13,7 +13,7 @@ image::./images/lambda-overview.png[lambda overview] [float] [[apm-lambda-cold-start-info]] -==== Cold starts +== Cold starts A cold start occurs when a Lambda function has not been used for a certain period of time. A lambda worker receives a request to run the function and prepares an execution environment. @@ -21,7 +21,7 @@ Cold starts are an unavoidable byproduct of the serverless world, but visibility [float] [[apm-lambda-cold-start-rate]] -===== Cold start rate +=== Cold start rate The cold start rate (i.e. proportion of requests that experience a cold start) is displayed per service and per transaction. @@ -32,7 +32,7 @@ image::./images/lambda-cold-start-trace.png[lambda cold start trace] [float] [[apm-lambda-cold-start-latency]] -===== Latency distribution correlation +=== Latency distribution correlation The <> feature can be used to visualize the impact of Lambda cold starts on latency--just select the `faas.coldstart` field. @@ -41,7 +41,7 @@ image::./images/lambda-correlations.png[lambda correlations example] [float] [[apm-lambda-service-config]] -==== AWS Lambda function grouping +== AWS Lambda function grouping The default APM agent configuration results in one APM service per AWS Lambda function, where the Lambda function name is the service name. diff --git a/docs/en/observability/apm-ui/mobile-session-explorer.asciidoc b/docs/en/observability/apm/view-and-analyze/interpret/mobile-session-explorer.asciidoc similarity index 95% rename from docs/en/observability/apm-ui/mobile-session-explorer.asciidoc rename to docs/en/observability/apm/view-and-analyze/interpret/mobile-session-explorer.asciidoc index dc1a2fb8cb..62329f7dc4 100644 --- a/docs/en/observability/apm-ui/mobile-session-explorer.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/interpret/mobile-session-explorer.asciidoc @@ -1,12 +1,12 @@ [[apm-mobile-session-explorer]] -=== Explore mobile sessions with Discover += Explore mobile sessions with Discover Elastic Mobile APM provides session tracking by attaching a `session.id`, a guid, to every span and event. This allows for the recall of the activities of a specific user during a specific period of time. The best way recall these data points is using {kibana-ref}/document-explorer.html[Discover]. This guide will explain how to do that. [discrete] [[viewing-sessions-with-discover]] -=== Viewing sessions with Discover +== Viewing sessions with Discover The first step is to find the relevant `session.id`. In this example, we'll walk through investigating a crash. Since all events and spans have `session.id` attributes, a crash is no different. diff --git a/docs/en/observability/apm-ui/machine-learning.asciidoc b/docs/en/observability/apm/view-and-analyze/machine-learning.asciidoc similarity index 96% rename from docs/en/observability/apm-ui/machine-learning.asciidoc rename to docs/en/observability/apm/view-and-analyze/machine-learning.asciidoc index adfff00d5c..6bc0dbc25f 100644 --- a/docs/en/observability/apm-ui/machine-learning.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/machine-learning.asciidoc @@ -1,5 +1,5 @@ [[apm-machine-learning-integration]] -=== Machine learning integration += Machine learning integration ++++ Integrate with machine learning @@ -32,7 +32,7 @@ image::./images/apm-service-map-anomaly.png[Example view of anomaly scores on se [float] [[create-ml-integration]] -=== Enable anomaly detection +== Enable anomaly detection To enable machine learning anomaly detection: @@ -53,7 +53,7 @@ To manage existing jobs, click **Manage jobs**. [float] [[warning-ml-integration]] -=== Anomaly detection warning +== Anomaly detection warning To make machine learning as easy as possible to set up, the APM UI will warn you when filtered to an environment without a machine learning job. @@ -63,7 +63,7 @@ image::./images/apm-anomaly-alert.png[Example view of anomaly alert in the APM U [float] [[unkown-ml-integration]] -=== Unknown service health +== Unknown service health After enabling anomaly detection, service health may display as "Unknown". Here are some reasons why this can occur: diff --git a/docs/en/observability/apm-ui/settings.asciidoc b/docs/en/observability/apm/view-and-analyze/settings.asciidoc similarity index 95% rename from docs/en/observability/apm-ui/settings.asciidoc rename to docs/en/observability/apm/view-and-analyze/settings.asciidoc index e678768fcb..7b3bfa55e4 100644 --- a/docs/en/observability/apm-ui/settings.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/settings.asciidoc @@ -1,5 +1,5 @@ [[apm-settings-in-kibana]] -== APM UI settings += APM UI settings ++++ Settings @@ -10,7 +10,7 @@ If you'd like to adjust the default settings, see {kibana-ref}/apm-settings-kb.h [float] [[apm-indices-settings]] -=== APM Indices +== APM Indices The APM UI uses data views to query APM indices. To change the default APM indices that the APM UI queries, open the APM UI and select **Settings** > **Indices**. @@ -22,7 +22,7 @@ See <> for more information. [float] [[apm-labs]] -=== APM Labs +== APM Labs **APM Labs** allows you to easily try out new features that are technical preview. diff --git a/docs/en/observability/apm-ui/dependencies.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/dependencies.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/dependencies.asciidoc rename to docs/en/observability/apm/view-and-analyze/ui-overview/dependencies.asciidoc index 28072b4439..cf801c042c 100644 --- a/docs/en/observability/apm-ui/dependencies.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/ui-overview/dependencies.asciidoc @@ -1,5 +1,5 @@ [[apm-dependencies]] -=== Dependencies += Dependencies APM agents collect details about external calls made from instrumented services. Sometimes, these external calls resolve into a downstream service that's instrumented -- in these cases, @@ -32,7 +32,7 @@ impacted services to determine why that pattern change has occurred. [float] [[dependencies-operations]] -==== Operations +== Operations beta::[] diff --git a/docs/en/observability/apm/view-and-analyze/ui-overview/index.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/index.asciidoc new file mode 100644 index 0000000000..d371f73c3e --- /dev/null +++ b/docs/en/observability/apm/view-and-analyze/ui-overview/index.asciidoc @@ -0,0 +1,31 @@ +[[apm-ui]] += High-level overviews of application data + +++++ +Overviews +++++ + +For a quick, high-level overview of the health and performance of your application, +start with: + +* <> +* <> +* <> +* <> + +View an individual service: + +* <> +* <> + +:leveloffset: +1 + +include::services.asciidoc[] +include::new-experience-services.asciidoc[] +include::traces.asciidoc[] +include::dependencies.asciidoc[] +include::service-maps.asciidoc[] +include::service-overview.asciidoc[] +include::mobile-service.asciidoc[] + +:!leveloffset: \ No newline at end of file diff --git a/docs/en/observability/apm-ui/mobile-service.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/mobile-service.asciidoc similarity index 94% rename from docs/en/observability/apm-ui/mobile-service.asciidoc rename to docs/en/observability/apm/view-and-analyze/ui-overview/mobile-service.asciidoc index b1d7352429..934b2fa0c5 100644 --- a/docs/en/observability/apm-ui/mobile-service.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/ui-overview/mobile-service.asciidoc @@ -1,5 +1,5 @@ [[apm-mobile-service-overview]] -=== Mobile service overview += Mobile service overview Selecting a mobile service brings you to the *Mobile service overview*. The *Mobile service overview* contains a wide variety of charts and tables that provide @@ -22,7 +22,7 @@ of their mobile application environment and the impact of backend errors and bot [discrete] [[mobile-service-stats]] -=== Quick stats +== Quick stats Understand the impact of slow application load times and variations in application crash rate on user traffic (coming soon). Visualize session and HTTP trends, and see where your users are located--enabling you to optimize your infrastructure deployment and routing topology. @@ -34,7 +34,7 @@ image::./images/mobile-location.png[mobile service overview centered on location [discrete] [[mobile-service-most-used]] -=== Most used +== Most used Optimize your end-user experience and your application QA strategy based on your most used device models and operating system versions. @@ -44,13 +44,13 @@ image::./images/mobile-most-used.png[mobile service overview showing most used d [discrete] [[mobile-throughput-transactions]] -=== Throughput and transactions +== Throughput and transactions include::./service-overview.asciidoc[tag=throughput-transactions] [discrete] [[mobile-error-and-dependencies]] -=== Failed transaction rate and dependencies +== Failed transaction rate and dependencies include::./service-overview.asciidoc[tag=ftr] diff --git a/docs/en/observability/apm-ui/new-experience-services.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/new-experience-services.asciidoc similarity index 100% rename from docs/en/observability/apm-ui/new-experience-services.asciidoc rename to docs/en/observability/apm/view-and-analyze/ui-overview/new-experience-services.asciidoc diff --git a/docs/en/observability/apm-ui/service-maps.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/service-maps.asciidoc similarity index 97% rename from docs/en/observability/apm-ui/service-maps.asciidoc rename to docs/en/observability/apm/view-and-analyze/ui-overview/service-maps.asciidoc index 84f1cb7dd4..ffe627d401 100644 --- a/docs/en/observability/apm-ui/service-maps.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/ui-overview/service-maps.asciidoc @@ -1,5 +1,5 @@ [[apm-service-maps]] -=== Service Map += Service Map A service map is a real-time visual representation of the instrumented services in your application's architecture. It shows you how these services are connected, along with high-level metrics like average transaction duration, @@ -37,7 +37,7 @@ We currently surface two types of service maps: [float] [[service-maps-how]] -=== How do service maps work? +== How do service maps work? Service Maps rely on distributed traces to draw connections between services. As {apm-guide-ref}/apm-distributed-tracing.html[distributed tracing] is enabled out-of-the-box for supported technologies, so are service maps. @@ -47,7 +47,7 @@ distributed tracing will not work, and the connection will not be drawn on the m [float] [[visualize-your-architecture]] -=== Visualize your architecture +== Visualize your architecture Select the **Service Map** tab to get started. By default, all instrumented services and connections are shown. @@ -70,7 +70,7 @@ image::./images/service-maps-java.png[Example view of service maps in the APM UI [float] [[service-map-anomaly-detection]] -=== Anomaly detection with machine learning +== Anomaly detection with machine learning You can create machine learning jobs to calculate anomaly scores on APM transaction durations within the selected service. When these jobs are active, service maps will display a color-coded anomaly indicator based on the detected anomaly score: @@ -90,7 +90,7 @@ To learn how to create a machine learning job, see <> brings you to the *Service overview*. The *Service overview* contains a wide variety of charts and tables that provide @@ -14,7 +14,7 @@ high-level visibility into how a service is performing across your infrastructur [discrete] [[service-time-comparison]] -=== Time series and expected bounds comparison +== Time series and expected bounds comparison For insight into the health of your services, you can compare how a service performs relative to a previous time frame or to the expected bounds from the @@ -48,7 +48,7 @@ environment and you have [discrete] [[service-latency]] -=== Latency +== Latency Response times for the service. You can filter the *Latency* chart to display the average, 95th, or 99th percentile latency times for the service. @@ -58,7 +58,7 @@ image::./images/latency.png[Service latency] [discrete] [[service-throughput-transactions]] -=== Throughput and transactions +== Throughput and transactions // tag::throughput-transactions[] The *Throughput* chart visualizes the average number of transactions per minute for the selected service. @@ -77,7 +77,7 @@ image::./images/traffic-transactions.png[Traffic and transactions] [discrete] [[service-error-rates]] -=== Failed transaction rate and errors +== Failed transaction rate and errors // tag::ftr[] The failed transaction rate represents the percentage of failed transactions from the perspective of the selected service. @@ -104,7 +104,7 @@ image::./images/error-rate.png[failed transaction rate and errors] [discrete] [[service-span-duration]] -=== Span types average duration and dependencies +== Span types average duration and dependencies The *Time spent by span type* chart visualizes each span type's average duration and helps you determine which spans could be slowing down transactions. The "app" label displayed under the @@ -127,7 +127,7 @@ image::./images/spans-dependencies.png[Span type duration and dependencies] [discrete] [[service-cold-start]] -=== Cold start rate +== Cold start rate The cold start rate chart is specific to serverless services, and displays the percentage of requests that trigger a cold start of a serverless function. @@ -140,7 +140,7 @@ functions and Azure functions. [discrete] [[service-instances]] -=== Instances +== Instances The *Instances* table displays a list of all the available service instances within the selected time range. Depending on how the service runs, the instance could be a host or a container. The table displays latency, throughput, @@ -151,7 +151,7 @@ image::./images/all-instances.png[All instances] [discrete] [[service-metadata]] -=== Service metadata +== Service metadata To view metadata relating to the service agent, and if relevant, the container and cloud provider, click on each icon located at the top of the page beside the service name. diff --git a/docs/en/observability/apm-ui/services.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/services.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/services.asciidoc rename to docs/en/observability/apm/view-and-analyze/ui-overview/services.asciidoc index de30fff587..4194e1f087 100644 --- a/docs/en/observability/apm-ui/services.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/ui-overview/services.asciidoc @@ -1,5 +1,5 @@ [[apm-services]] -=== Services += Services *Service* inventory provides a quick, high-level overview of the health and general performance of all instrumented services. @@ -18,7 +18,7 @@ TIP: Want to monitor service logs without instrumenting all your services? Learn [float] [[service-groups]] -==== Service groups +== Service groups beta::[] diff --git a/docs/en/observability/apm-ui/traces.asciidoc b/docs/en/observability/apm/view-and-analyze/ui-overview/traces.asciidoc similarity index 98% rename from docs/en/observability/apm-ui/traces.asciidoc rename to docs/en/observability/apm/view-and-analyze/ui-overview/traces.asciidoc index 4a082198b5..229a08a7e0 100644 --- a/docs/en/observability/apm-ui/traces.asciidoc +++ b/docs/en/observability/apm/view-and-analyze/ui-overview/traces.asciidoc @@ -1,5 +1,5 @@ [[apm-traces]] -=== Traces += Traces TIP: Traces link together related transactions to show an end-to-end performance of how a request was served and which services were part of it. @@ -25,7 +25,7 @@ image::./images/apm-traces.png[Example view of the Traces overview in APM UI in [float] [[trace-explorer]] -==== Trace explorer +== Trace explorer preview::[] diff --git a/docs/en/observability/create-alerts.asciidoc b/docs/en/observability/create-alerts.asciidoc index 8b22a26b31..e5e0d1ce12 100644 --- a/docs/en/observability/create-alerts.asciidoc +++ b/docs/en/observability/create-alerts.asciidoc @@ -162,6 +162,8 @@ xpack.observability.unsafe.alertingExperience.enabled: 'false' ---- +include::apm-alerts.asciidoc[leveloffset=+2] + include::threshold-alert.asciidoc[leveloffset=+2] include::logs-threshold-alert.asciidoc[leveloffset=+2] diff --git a/docs/en/observability/images/icons/check.svg b/docs/en/observability/images/icons/check.svg new file mode 100644 index 0000000000..1145dd301d --- /dev/null +++ b/docs/en/observability/images/icons/check.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/observability/images/icons/cross.svg b/docs/en/observability/images/icons/cross.svg new file mode 100644 index 0000000000..82df3e03d3 --- /dev/null +++ b/docs/en/observability/images/icons/cross.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/en/observability/redirects.asciidoc b/docs/en/observability/redirects.asciidoc index ca06f129e0..e841392382 100644 --- a/docs/en/observability/redirects.asciidoc +++ b/docs/en/observability/redirects.asciidoc @@ -901,3 +901,28 @@ Refer to <>. === AWS Lambda support Refer to <>. + +[role="exclude",id="apm-log-correlation"] +=== Logging integration + +Refer to <>. + +[role="exclude",id="apm-app-troubleshooting"] +=== Troubleshoot the APM UI + +Refer to <>. + +[role="exclude",id="apm-how-to-guides"] +=== Perform common tasks in the APM UI + +Refer to <>. + +[role="exclude",id="apm-span-compression"] +=== Span compression + +Refer to <>. + +[role="exclude",id="apm-features"] +=== Features + +Refer to <>.