diff --git a/docs/en/apm-server/redirects.asciidoc b/docs/en/apm-server/redirects.asciidoc index 030d2b242c..986593cbb4 100644 --- a/docs/en/apm-server/redirects.asciidoc +++ b/docs/en/apm-server/redirects.asciidoc @@ -226,23 +226,23 @@ This section has moved. Please see {observability-guide}/apm-tune-data-ingestion [role="exclude",id="load-dashboards-logstash"] === Tuning APM Server using both v1 and v2 intake API -Loading dashboards from APM Server is no longer supported. Please see the {kibana-ref}/xpack-apm.html[{kib} APM UI] documentation. +Loading dashboards from APM Server is no longer supported. Please see the {observability-guide}/apm-ui.html[{kib} APM UI] documentation. [role="exclude",id="url-option"] === setup.dashboards.url -Loading dashboards from APM Server is no longer supported. Please see the {kibana-ref}/xpack-apm.html[{kib} APM UI] documentation. +Loading dashboards from APM Server is no longer supported. Please see the {observability-guide}/apm-ui.html[{kib} APM UI] documentation. [role="exclude",id="file-option"] === setup.dashboards.file -Loading dashboards from APM Server is no longer supported. Please see the {kibana-ref}/xpack-apm.html[{kib} APM UI] documentation. +Loading dashboards from APM Server is no longer supported. Please see the {observability-guide}/apm-ui.html[{kib} APM UI] documentation. [role="exclude",id="load-kibana-dashboards"] === Dashboards Loading {kib} dashboards from APM Server is no longer supported. -Please use the {kibana-ref}/xpack-apm.html[{kib} APM UI] instead. +Please use the {observability-guide}/apm-ui.html[{kib} APM UI] instead. As an alternative, a small number of dashboards and visualizations are available in the https://github.com/elastic/apm-contrib/tree/main/kibana[apm-contrib] repository. diff --git a/docs/en/observability/apm-ui/advanced-queries.asciidoc b/docs/en/observability/apm-ui/advanced-queries.asciidoc new file mode 100644 index 0000000000..6b5f20dd27 --- /dev/null +++ b/docs/en/observability/apm-ui/advanced-queries.asciidoc @@ -0,0 +1,84 @@ +[[apm-advanced-queries]] +=== Query your data + +Querying your APM data is an essential tool that can make finding bottlenecks in your code even more straightforward. + +Using the query bar, a powerful data query feature, you can pass advanced queries on your data +to filter on specific pieces of information you’re interested in. + +The query bar comes with a handy autocomplete that helps find the fields and even provides suggestions to the data they include. +You can select the query bar and hit the down arrow on your keyboard to begin scanning recommendations. + +[float] +[[apm-app-advanced-queries]] +=== 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. + +When you type, you can begin to see some of the transaction fields available for filtering: + +[role="screenshot"] +image::./images/apm-query-bar.png[Example of the Kibana Query bar in APM UI in Kibana] + +[TIP] +===== +To learn more about the {kib} query language capabilities, see the {kibana-ref}/kuery-query.html[Kibana Query Language Enhancements] documentation. +===== + +[float] +[[apm-app-queries]] +==== APM UI queries + +APM queries can be handy for removing noise from your data in the <>, <>, +<>, <>, and <> views. + +For example, in the *Services* view, you can quickly view a list of all the instrumented services running on your production +environment: `service.environment : production`. Or filter the list by including the APM agent's name and the host it’s running on: +`service.environment : "production" and agent.name : "java" and host.name : "prod-server1"`. + +On the *Traces* view, you might want to view failed transaction results from any of your running containers: +`transaction.result :"FAILURE" and container.id : *`. + +On the *Transactions* view, you may want to list only the slower transactions than a specified time threshold: `transaction.duration.us > 2000000`. +Or filter the list by including the service version and the Kubernetes pod it's running on: +`transaction.duration.us > 2000000 and service.version : "7.12.0" and kubernetes.pod.name : "pod-5468b47f57-pqk2m"`. + +[float] +[[discover-advanced-queries]] +=== 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, +and *Discover* supports all of the example APM UI queries shown on this page. + +[float] +[[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. + +TIP: Starting in v7.6, you can view ten samples per bucket in the APM UI, instead of just one. + +Use the APM UI to find a transaction name and time bucket that you're interested in learning more about. +Then, switch to *Discover* and make a search: + +["source","sh"] +----- +processor.event: "transaction" AND transaction.name: "" and transaction.duration.us > 13000 and transaction.duration.us < 14000` +----- + +In this example, we're interested in viewing all of the `APIRestController#customers` transactions +that took between 13 and 14 milliseconds. Here's what Discover returns: + +[role="screenshot"] +image::./images/advanced-discover.png[View all transactions in bucket] + +You can now explore the data until you find a specific transaction that you're interested in. +Copy that transaction's `transaction.id` and paste it into the APM UI to view the data in the context of the APM UI: + +[role="screenshot"] +image::./images/specific-transaction-search.png[View specific transaction in APM UI] +[role="screenshot"] +image::./images/specific-transaction.png[View specific transaction in APM UI] diff --git a/docs/en/observability/apm-ui/agent-configuration.asciidoc b/docs/en/observability/apm-ui/agent-configuration.asciidoc new file mode 100644 index 0000000000..13d929dd53 --- /dev/null +++ b/docs/en/observability/apm-ui/agent-configuration.asciidoc @@ -0,0 +1,55 @@ +[[apm-agent-configuration]] +=== APM Agent central configuration + +++++ +Configure APM agents with central config +++++ + +APM Agent configuration allows you to fine-tune your APM agent configuration from within the APM UI. +Changes are automatically propagated to your APM agents, so there's no need to redeploy. + +To get started, choose the services and environments you wish to configure. +The APM UI will let you know when your APM agents have applied your configurations. + +[role="screenshot"] +image::./images/apm-agent-configuration.png[APM Agent configuration in Kibana] + +[float] +==== 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., +APM agents will use local defaults until they're able to update the configuration. +For this reason, it is still essential to set custom default configurations locally in each of your APM agents. + +[float] +==== Supported configurations + +Each APM agent has a list of supported configurations. +After selecting a Service name and environment in the APM UI, +a list of all supported configuration options, +including descriptions and default values, will be displayed. + +Supported configurations are also tagged with the image:./images/dynamic-config.svg[] badge in each APM agent's configuration reference: + +[horizontal] +Android agent:: {apm-android-ref}/configuration.html[Configuration reference] +Go agent:: {apm-go-ref}/configuration.html[Configuration reference] +iOS agent:: {apm-ios-ref}/configuration.html[Configuration reference] +Java agent:: {apm-java-ref}/configuration.html[Configuration reference] +.NET agent:: {apm-dotnet-ref}/configuration.html[Configuration reference] +Node.js agent:: {apm-node-ref}/configuration.html[Configuration reference] +PHP agent:: {apm-php-ref}/configuration.html[Configuration reference] +Python agent:: {apm-py-ref}/configuration.html[Configuration reference] +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 + +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, +or because your {es} credentials don't have sufficient privileges. + +See {apm-guide-ref}/configure-agent-config.html[configure APM agent configuration] +to learn how to configure APM Server to avoid these problems. diff --git a/docs/en/observability/apm-ui/agent-explorer.asciidoc b/docs/en/observability/apm-ui/agent-explorer.asciidoc new file mode 100644 index 0000000000..1197b7538e --- /dev/null +++ b/docs/en/observability/apm-ui/agent-explorer.asciidoc @@ -0,0 +1,18 @@ +[[apm-agent-explorer]] +=== APM Agent explorer + +++++ +Identify deployment details for APM agents +++++ + +beta::[] + +APM agent explorer provides a centralized panel to identify APM agent deployment details, like service name, environment, instances, and agent name, version, and documentation. + +[role="screenshot"] +image::./images/apm-agent-explorer.png[APM agent explorer] + +Select an APM agent to expand it and view the details of each agent instance. + +[role="screenshot"] +image::./images/apm-agent-explorer-flyout.png[APM agent explorer flyout] diff --git a/docs/en/observability/apm-ui/api.asciidoc b/docs/en/observability/apm-ui/api.asciidoc new file mode 100644 index 0000000000..06399693f4 --- /dev/null +++ b/docs/en/observability/apm-ui/api.asciidoc @@ -0,0 +1,817 @@ +[[apm-app-api]] +== APM UI API + +Some APM UI features are provided via a REST API: + +* <> +* <> +* <> +* <> + +[float] +[[apm-api-example]] +=== Using the APIs + +// The following content is reused throughout the API docs +// tag::using-the-APIs[] +Interact with APM APIs using cURL or another API tool. +All APM APIs are Kibana APIs, not Elasticsearch APIs; +because of this, the Kibana dev tools console cannot be used to interact with APM APIs. + +For all APM APIs, you must use a request header. +Supported headers are `Authorization`, `kbn-xsrf`, and `Content-Type`. + +`Authorization: ApiKey {credentials}`:: +Kibana supports token-based authentication with the Elasticsearch API key service. +The API key returned by the {ref}/security-api-create-api-key.html[Elasticsearch create API key API] +can be used by sending a request with an `Authorization` header that has a value of `ApiKey` followed by the `{credentials}`, +where `{credentials}` is the base64 encoding of `id` and `api_key` joined by a colon. ++ +Alternatively, you can create a user and use their username and password to authenticate API access: `-u $USER:$PASSWORD`. ++ +Whether using `Authorization: ApiKey {credentials}`, or `-u $USER:$PASSWORD`, +users interacting with APM APIs must have <>. + +`kbn-xsrf: true`:: + By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios: + +* The API endpoint uses the `GET` or `HEAD` operations +* The path is allowed using the `server.xsrf.allowlist` setting +* XSRF protections are disabled using the `server.xsrf.disableProtection` setting + +`Content-Type: application/json`:: + Applicable only when you send a payload in the API request. + {kib} API requests and responses use JSON. + Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. +// end::using-the-APIs[] + +Here's an example CURL request that adds an annotation to the APM UI: + +[source,curl] +---- +curl -X POST \ + http://localhost:5601/api/apm/services/opbeans-java/annotation \ +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \ +-d '{ + "@timestamp": "2020-05-11T10:31:30.452Z", + "service": { + "version": "1.2" + }, + "message": "Revert upgrade", + "tags": [ + "elastic.co", "customer" + ] + }' +---- + +[float] +[[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. + +//// +******************************************************* +******************************************************* +//// + +[[apm-agent-config-api]] +=== Agent Configuration API + +The APM agent configuration API allows you to fine-tune your APM agent configuration, +without needing to redeploy your application. + +The following APM agent configuration APIs are available: + +* <> to create or update an APM agent configuration +* <> to delete an APM agent configuration. +* <> to list all APM agent configurations. +* <> to search for an APM agent configuration. + +[float] +[[use-agent-config-api]] +==== How to use APM APIs + +.Expand for required headers, privileges, and usage details +[%collapsible%closed] +====== +include::api.asciidoc[tag=using-the-APIs] +====== + +//// +******************************************************* +//// + +[[apm-update-config]] +==== Create or update configuration + +[[apm-update-config-req]] +===== Request + +`PUT /api/apm/settings/agent-configuration` + +[role="child_attributes"] +[[apm-update-config-req-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. + +`agent_name`:: +(optional) The agent name is used by the UI to determine which settings to display. + + +[[apm-update-config-example]] +===== Example + +[source,curl] +-------------------------------------------------- +PUT /api/apm/settings/agent-configuration +{ + "service": { + "name": "frontend", + "environment": "production" + }, + "settings": { + "transaction_sample_rate": "0.4", + "capture_body": "off", + "transaction_max_spans": "500" + }, + "agent_name": "nodejs" +} +-------------------------------------------------- + +//// +******************************************************* +//// + + +[[apm-delete-config]] +==== Delete configuration + +[[apm-delete-config-req]] +===== Request + +`DELETE /api/apm/settings/agent-configuration` + +[role="child_attributes"] +[[apm-delete-config-req-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 +====== + + +[[apm-delete-config-example]] +===== Example + +[source,curl] +-------------------------------------------------- +DELETE /api/apm/settings/agent-configuration +{ + "service" : { + "name": "frontend", + "environment": "production" + } +} +-------------------------------------------------- + +//// +******************************************************* +//// + +[[apm-list-config]] +==== List configuration + +[[apm-list-config-req]] +===== Request + +`GET /api/apm/settings/agent-configuration` + +[[apm-list-config-body]] +===== Response body + +[source,js] +-------------------------------------------------- +[ + { + "agent_name": "go", + "service": { + "name": "opbeans-go", + "environment": "production" + }, + "settings": { + "transaction_sample_rate": "1", + "capture_body": "off", + "transaction_max_spans": "200" + }, + "@timestamp": 1581934104843, + "applied_by_agent": false, + "etag": "1e58c178efeebae15c25c539da740d21dee422fc" + }, + { + "agent_name": "go", + "service": { + "name": "opbeans-go" + }, + "settings": { + "transaction_sample_rate": "1", + "capture_body": "off", + "transaction_max_spans": "300" + }, + "@timestamp": 1581934111727, + "applied_by_agent": false, + "etag": "3eed916d3db434d9fb7f039daa681c7a04539a64" + }, + { + "agent_name": "nodejs", + "service": { + "name": "frontend" + }, + "settings": { + "transaction_sample_rate": "1", + }, + "@timestamp": 1582031336265, + "applied_by_agent": false, + "etag": "5080ed25785b7b19f32713681e79f46996801a5b" + } +] +-------------------------------------------------- + +[[apm-list-config-example]] +===== Example + +[source,curl] +-------------------------------------------------- +GET /api/apm/settings/agent-configuration +-------------------------------------------------- + +//// +******************************************************* +//// + +[[apm-search-config]] +==== Search configuration + +[[apm-search-config-req]] +===== Request + +`POST /api/apm/settings/agent-configuration/search` + +[role="child_attributes"] +[[apm-search-config-req-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`. + +[[apm-search-config-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{ + "_index": ".apm-agent-configuration", + "_id": "CIaqXXABmQCdPphWj8EJ", + "_score": 2, + "_source": { + "agent_name": "nodejs", + "service": { + "name": "frontend" + }, + "settings": { + "transaction_sample_rate": "1", + }, + "@timestamp": 1582031336265, + "applied_by_agent": false, + "etag": "5080ed25785b7b19f32713681e79f46996801a5b" + } +} +-------------------------------------------------- + +[[apm-search-config-example]] +===== Example + +[source,curl] +-------------------------------------------------- +POST /api/apm/settings/agent-configuration/search +{ + "etag": "1e58c178efeebae15c25c539da740d21dee422fc", + "service" : { + "name": "frontend", + "environment": "production" + } +} +-------------------------------------------------- + +//// +******************************************************* +******************************************************* +//// + +[[apm-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. + +By default, annotations are stored in a newly created `observability-annotations` index. +The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`. +If you change the default index name, you'll also need to <> accordingly. + +The following APIs are available: + +* <> to create an annotation for APM. +// * <> POST /api/observability/annotation +// * <> GET /api/observability/annotation/:id +// * <> DELETE /api/observability/annotation/:id + +[float] +[[use-annotation-api]] +==== How to use APM APIs + +.Expand for required headers, privileges, and usage details +[%collapsible%closed] +====== +include::api.asciidoc[tag=using-the-APIs] +====== + +//// +******************************************************* +//// + +[[apm-annotation-create]] +==== Create or update annotation + +[[apm-annotation-config-req]] +===== Request + +`POST /api/apm/services/:serviceName/annotation` + +[role="child_attributes"] +[[apm-annotation-config-req-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. + +`message`:: +(optional, string) The message displayed in the annotation. Defaults to `service.version`. + +`tags`:: +(optional, array) Tags are used by the APM UI to distinguish APM annotations from other annotations. +Tags may have additional functionality in future releases. Defaults to `[apm]`. +While you can add additional tags, you cannot remove the `apm` tag. + +[[apm-annotation-config-example]] +===== Example + +The following example creates an annotation for a service named `opbeans-java`. + +[source,curl] +-------------------------------------------------- +curl -X POST \ + http://localhost:5601/api/apm/services/opbeans-java/annotation \ +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \ +-d '{ + "@timestamp": "2020-05-08T10:31:30.452Z", + "service": { + "version": "1.2" + }, + "message": "Deployment 1.2" + }' +-------------------------------------------------- + +[[apm-annotation-config-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{ + "_index": "observability-annotations", + "_id": "Lc9I93EBh6DbmkeV7nFX", + "_version": 1, + "_seq_no": 12, + "_primary_term": 1, + "found": true, + "_source": { + "message": "Deployment 1.2", + "@timestamp": "2020-05-08T10:31:30.452Z", + "service": { + "version": "1.2", + "name": "opbeans-java" + }, + "tags": [ + "apm", + "elastic.co", + "customer" + ], + "annotation": { + "type": "deployment" + }, + "event": { + "created": "2020-05-09T02:34:43.937Z" + } + } +} +-------------------------------------------------- + +//// +******************************************************* +******************************************************* +//// + +[[apm-rum-sourcemap-api]] +=== RUM source map API + +IMPORTANT: This endpoint is only compatible with the +{apm-guide-ref}/index.html[APM integration for Elastic Agent]. + +A source map allows minified files to be mapped back to original source code -- +allowing you to maintain the speed advantage of minified code, +without losing the ability to quickly and easily debug your application. + +For best results, uploading source maps should become a part of your deployment procedure, +and not something you only do when you see unhelpful errors. +That’s because uploading source maps after errors happen won’t make old errors magically readable -- +errors must occur again for source mapping to occur. + +The following APIs are available: + +* <> +* <> +* <> + +[float] +[[limit-sourcemap-api]] +==== 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. + +Before uploading source maps that exceed this default, change the maximum payload size allowed by {kib} +with the `server.maxPayload` variable. + +[float] +[[use-sourcemap-api]] +==== How to use APM APIs + +.Expand for required headers, privileges, and usage details +[%collapsible%closed] +====== +include::api.asciidoc[tag=using-the-APIs] +====== + +//// +******************************************************* +//// + +[[rum-sourcemap-post]] +==== Create or update source map + +Create or update a source map for a specific service and version. + +[[rum-sourcemap-post-privs]] +===== 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]. + +[[apm-sourcemap-post-req]] +===== Request + +`POST /api/apm/sourcemaps` + +[role="child_attributes"] +[[apm-sourcemap-post-req-body]] +===== Request body + +`service_name`:: +(required, string) The name of the service that the service map should apply to. + +`service_version`:: +(required, string) The version of the service that the service map should apply to. + +`bundle_filepath`:: +(required, string) The absolute path of the final bundle as used in the web application. + +`sourcemap`:: +(required, string or file upload) The source map. It must follow the +https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k[source map revision 3 proposal]. + +[[apm-sourcemap-post-example]] +===== Examples + +The following example uploads a source map for a service named `foo` and a service version of `1.0.0`: + +[source,curl] +-------------------------------------------------- +curl -X POST "http://localhost:5601/api/apm/sourcemaps" \ +-H 'Content-Type: multipart/form-data' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: ApiKey ${YOUR_API_KEY}' \ +-F 'service_name="foo"' \ +-F 'service_version="1.0.0"' \ +-F 'bundle_filepath="/test/e2e/general-usecase/bundle.js"' \ +-F 'sourcemap="{\"version\":3,\"file\":\"static/js/main.chunk.js\",\"sources\":[\"fleet-source-map-client/src/index.css\",\"fleet-source-map-client/src/App.js\",\"webpack:///./src/index.css?bb0a\",\"fleet-source-map-client/src/index.js\",\"fleet-source-map-client/src/reportWebVitals.js\"],\"sourcesContent\":[\"content\"],\"mappings\":\"mapping\",\"sourceRoot\":\"\"}"' <1> +-------------------------------------------------- +<1> Alternatively, upload the source map as a file with `-F 'sourcemap=@path/to/source_map/bundle.js.map'` + +[[apm-sourcemap-post-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{ + "type": "sourcemap", + "identifier": "foo-1.0.0", + "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456", + "body": "eJyFkL1OwzAUhd/Fc+MbYMuCEBIbHRjKgBgc96R16tiWr1OQqr47NwqJxEK3q/PzWccXxchnZ7E1A1SjuhjVZtF2yOxiEPlO17oWox3D3uPFeSRTjmJQARfCPeiAgGx8NTKsYdAc1T3rwaSJGcds8Sp3c1HnhfywUZ3QhMTFFGepZxqMC9oex3CS9tpk1XyozgOlmoVKuJX1DqEQZ0su7PGtLU+V/3JPKc3cL7TJ2FNDRPov4bFta3MDM4f7W69lpJjLO9qdK8bzVPhcJz3HUCQ4LbO/p5hCSC4cZPByrp/wFqOklbpefwAhzpqI", + "created": "2021-07-09T20:47:44.812Z", + "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456", + "compressionAlgorithm": "zlib", + "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456", + "decodedSize": 441, + "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24", + "encodedSize": 237, + "encryptionAlgorithm": "none", + "packageName": "apm" +} +-------------------------------------------------- + +//// +******************************************************* +//// + +[[rum-sourcemap-get]] +==== Get source maps + +Returns an array of Fleet artifacts, including source map uploads. + +[[rum-sourcemap-get-privs]] +===== 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]. + +[[apm-sourcemap-get-req]] +===== Request + +`GET /api/apm/sourcemaps` + +[[apm-sourcemap-get-example]] +===== Example + +The following example requests all uploaded source maps: + +[source,curl] +-------------------------------------------------- +curl -X GET "http://localhost:5601/api/apm/sourcemaps" \ +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: ApiKey ${YOUR_API_KEY}' +-------------------------------------------------- + +[[apm-sourcemap-get-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{ + "artifacts": [ + { + "type": "sourcemap", + "identifier": "foo-1.0.0", + "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456", + "body": { + "serviceName": "foo", + "serviceVersion": "1.0.0", + "bundleFilepath": "/test/e2e/general-usecase/bundle.js", + "sourceMap": { + "version": 3, + "file": "static/js/main.chunk.js", + "sources": [ + "fleet-source-map-client/src/index.css", + "fleet-source-map-client/src/App.js", + "webpack:///./src/index.css?bb0a", + "fleet-source-map-client/src/index.js", + "fleet-source-map-client/src/reportWebVitals.js" + ], + "sourcesContent": [ + "content" + ], + "mappings": "mapping", + "sourceRoot": "" + } + }, + "created": "2021-07-09T20:47:44.812Z", + "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456", + "compressionAlgorithm": "zlib", + "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456", + "decodedSize": 441, + "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24", + "encodedSize": 237, + "encryptionAlgorithm": "none", + "packageName": "apm" + } + ] +} +-------------------------------------------------- + +//// +******************************************************* +//// + +[[rum-sourcemap-delete]] +==== Delete source map + +Delete a previously uploaded source map. + +[[rum-sourcemap-delete-privs]] +===== 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]. + +[[apm-sourcemap-delete-req]] +===== Request + +`DELETE /api/apm/sourcemaps/:id` + +[[apm-sourcemap-delete-example]] +===== Example + +The following example deletes a source map with an id of `apm:foo-1.0.0-644fd5a9`: + +[source,curl] +-------------------------------------------------- +curl -X DELETE "http://localhost:5601/api/apm/sourcemaps/apm:foo-1.0.0-644fd5a9" \ +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: ApiKey ${YOUR_API_KEY}' +-------------------------------------------------- + +[[apm-sourcemap-delete-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{} +-------------------------------------------------- + +//// +******************************************************* +******************************************************* +//// + +[[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. + +The following APM agent key APIs are available: + +* <> to create an APM agent key + +[float] +[[use-agent-key-api]] +==== How to use APM APIs + +.Expand for required headers, privileges, and usage details +[%collapsible%closed] +====== +include::api.asciidoc[tag=using-the-APIs] +====== + +//// +******************************************************* +//// + +[[apm-create-agent-key]] +==== Create agent key + +Create an APM agent API key. Specify API key privileges in the request body at creation time. + +[[apm-create-agent-key-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. + +====== 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. + +[source,js] +-------------------------------------------------- +POST /_security/role/apm_agent_key_user +{ + "cluster": ["manage_own_api_key"], + "applications": [{ + "application": "apm", + "privileges": ["event:write", "config_agent:read"], + "resources": ["*"] + }] +} +-------------------------------------------------- + +[[apm-create-agent-key-req]] +===== Request + +`POST /api/apm/agent_keys` + +[role="child_attributes"] +[[apm-create-agent-key-req-body]] +===== Request body + +`name`:: +(required, string) Name of the APM agent key. + +`privileges`:: +(required, array) APM agent key privileges. It can take one or more of the following values: + + - `event:write`. Required for ingesting APM agent events. + - `config_agent:read`. Required for APM agents to read agent configuration remotely. + +[[apm-agent-key-create-example]] +===== Example + +[source,curl] +-------------------------------------------------- +POST /api/apm/agent_keys +{ + "name": "apm-key", + "privileges": ["event:write", "config_agent:read"] +} +-------------------------------------------------- + +[[apm-agent-key-create-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{ + "agentKey": { + "id": "3DCLmn0B3ZMhLUa7WBG9", + "name": "apm-key", + "api_key": "PjGloCGOTzaZr8ilUPvkjA", + "encoded": "M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ==" + } +} +-------------------------------------------------- + +Once created, you can copy the API key (Base64 encoded) and use it to to authorize requests from APM agents to the APM Server. \ No newline at end of file diff --git a/docs/en/observability/apm-ui/apm-alerts.asciidoc b/docs/en/observability/apm-ui/apm-alerts.asciidoc new file mode 100644 index 0000000000..99a6b6f5ef --- /dev/null +++ b/docs/en/observability/apm-ui/apm-alerts.asciidoc @@ -0,0 +1,174 @@ +[[apm-alerts]] +=== Alerts and rules + +++++ +Create an alert +++++ + +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. + +The following **rules** are supported: + +* **Threshold rule**: +Alert when the latency or failed transaction rate is abnormal. +Threshold rules can be as broad or as granular as you'd like, enabling you to define exactly when you want to be alerted--whether that's at the environment level, service name level, transaction type level, and/or transaction name level. +* **Anomaly rule**: +Alert when either the latency of a service is anomalous. Anomaly rules can be set at the environment level, service level, and/or transaction type level. +* **Error count rule**: +Alert when the number of errors in a service exceeds a defined threshold. Error count rules can be set at the environment level, service level, and error group level. + +[role="screenshot"] +image::./images/apm-alert.png[Create an alert in the APM UI] + +Below, we'll walk through the creation of two APM rules. + +For a complete walkthrough of the **Create rule** flyout panel, including detailed information on each configurable property, +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 + +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 +tolerance for latency, we'll target a specific transaction within a service. + +Before continuing, identify the service name, transaction type, and environment that you'd like to create a latency anomaly rule for. +This guide will create an alert for all services based on the following criteria: + +* Service: `{your_service.name}` +* Transaction: `{your_transaction.name}` +* Environment: `{your_service.environment}` +* Severity level: critical +* Check every five minutes +* Send an alert to a Slack channel when the rule status changes + +From any page in the APM UI, select **Alerts and rules** > **Create anomaly rule**. +Change the name of the rule, but do not edit the tags. + +Based on the criteria above, define the following rule details: + +* **Service** - `{your_service.name}` +* **Type** - `{your_transaction.name}` +* **Environment** - `{your_service.environment}` +* **Has anomaly with severity** - `critical` +* **Check every** - `5 minutes` + +Next, add a connector type. Multiple connectors can be selected, but in this example we're interested in Slack. +Select **Slack** > **Create a connector**. +Enter a name for the connector, +and paste your Slack webhook URL. +See Slack's webhook documentation if you need to create one. + +A default message is provided as a starting point for your alert. +You can use the https://mustache.github.io/[Mustache] template syntax, i.e., `{{variable}}` +to pass additional alert values at the time a condition is detected to an action. +A list of available variables can be accessed by selecting the +**add variable** button image:./images/add-variable.png[add variable button]. + +Click **Save**. Your rule has been created and is now active! + +[float] +[[apm-create-error-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. + +Before continuing, identify the service name, environment name, and error group ID that you'd like to create a latency anomaly rule for. +The easiest way to find an error group ID is to select the service that you're interested in and navigating to the **Errors** tab. + +This guide will create an alert for an error group ID based on the following criteria: + +* Service: `{your_service.name}` +* Environment: `{your_service.environment}` +* Error Grouping Key: `{your_error.ID}` +* Error rate is above 25 errors for the last five minutes +* Group alerts by `service.name` and `service.environment` +* Check every 1 minute +* Send the alert via email to the site reliability team + +From any page in the APM UI, select **Alerts and rules** > **Create error count rule**. +Change the name of the alert, but do not edit the tags. + +Based on the criteria above, define the following rule details: + +* **Service**: `{your_service.name}` +* **Environment**: `{your_service.environment}` +* **Error Grouping Key**: `{your_error.ID}` +* **Is above** - `25 errors` +* **For the last** - `5 minutes` +* **Group alerts by** - `service.name` `service.environment` +* **Check every** - `1 minute` + +[NOTE] +==== +Alternatively, you can use a KQL filter to limit the scope of the alert: + +. Toggle on *Use KQL Filter*. +. Add a filter, for example to achieve the same effect as the example above: ++ +[source,txt] +------ +service.name:"{your_service.name}" and service.environment:"{your_service.environment}" and error.grouping_key:"{your_error.ID}" +------ + +Using a KQL Filter to limit the scope is available for _Latency threshold_, _Failed transaction rate threshold_, and +_Error count threshold_ rules. +==== + +Select the **Email** connector and click **Create a connector**. +Fill out the required details: sender, host, port, etc., and click **save**. + +A default message is provided as a starting point for your alert. +You can use the https://mustache.github.io/[Mustache] template syntax, i.e., `{{variable}}` +to pass additional alert values at the time a condition is detected to an action. +A list of available variables can be accessed by selecting the +**add variable** button image:./images/add-variable.png[add variable button]. + +Click **Save**. The alert has been created and is now active! + +[float] +[[apm-alert-view-active]] +=== 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 + +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. + +[role="screenshot"] +image::./images/apm-service-group.png[Example view of service group in the APM UI in Kibana] + +[float] +[[apm-alert-view-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. + +[role="screenshot"] +image::./images/active-alert-service.png[View active alerts by service] + +[float] +[[apm-alert-manage]] +=== Manage alerts and rules + +From the APM UI, select **Alerts and rules** > **Manage rules** to be taken to +the {kib} *{rules-ui}* page. +From this page, you can disable, mute, and delete APM alerts. + +[float] +[[apm-alert-more-info]] +=== More information + +See {kibana-ref}/alerting-getting-started.html[Alerting] for more information. + +NOTE: If you are using an **on-premise** Elastic Stack deployment with security, +communication between Elasticsearch and Kibana must have TLS configured. +More information is in the alerting {kibana-ref}/alerting-setup.html#alerting-prerequisites[prerequisites]. diff --git a/docs/en/observability/apm-ui/apm-app-users.asciidoc b/docs/en/observability/apm-ui/apm-app-users.asciidoc new file mode 100644 index 0000000000..ff62381ce0 --- /dev/null +++ b/docs/en/observability/apm-ui/apm-app-users.asciidoc @@ -0,0 +1,340 @@ +[[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. + +[[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 +|==== + +[[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`]). + +[[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 + +[[apm-app-annotation-api]] +==== Annotation API + +See <>. + +//// +*********************************** *********************************** +//// + +[[apm-app-central-config-user]] +=== APM UI central config user + +++++ +Create a central config user +++++ + +[[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 +|==== + +[[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 +|==== + +[[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 +++++ + +[[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 +++++ + +[[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 +|==== + +[[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 +|==== + +[[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/apm-spaces.asciidoc b/docs/en/observability/apm-ui/apm-spaces.asciidoc new file mode 100644 index 0000000000..8d97f3069f --- /dev/null +++ b/docs/en/observability/apm-ui/apm-spaces.asciidoc @@ -0,0 +1,411 @@ +[[apm-spaces]] +=== 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, +or any other filter that you choose. + +To take advantage of this feature, your APM data needs to be written to different data steams. +One way to accomplish this is with different namespaces. +For example, you can send production data to an APM integration with a namespace of `production`, +while sending staging data to a different APM integration with a namespace of `staging`. + +Multiple APM integration instances is not required though. The simplest way to take advantage of this feature +is by creating filtered aliases. See the guide below for more information. + +[float] +[[apm-spaces-example]] +=== 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, +or to create more granular access control for certain data. + +This guide assumes that you: + +* Are sending both staging and production APM data to an {es} cluster. +* Have configured the `environment` variable in your APM agent configurations. +This variable sets the `service.environment` field in APM documents. +You should have documents where `service.environment: production` and `service.environment: staging`. +If this field is empty, see <> to learn how to set this value. + +[float] +==== 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: + +[options="header"] +|==== +| Index setting | Default index pattern +| Error | `logs-apm*` +| Span/Transaction | `traces-apm*` +| Metrics | `metrics-apm*` +|==== + +NOTE: The default index settings also query the `apm-*` data view. +This data view matches APM data shipped in earlier versions of APM (prior to v8.0). + +Instead of querying the default APM data views, we can create filtered aliases for the APM UI to query. +A filtered alias is a secondary name for a group of data streams that has a user-defined +filter to limit the documents that the alias can access. + +To separate `staging` and `production` APM data, we'd need to create six filtered aliases--three +aliases for each service environment: + +[options="header"] +|==== +| Index setting | `production` env | `staging` env +| Error | `production-logs-apm` | `staging-logs-apm` +| Span/Transaction | `production-traces-apm` | `staging-traces-apm` +| Metrics | `production-metrics-apm` | `staging-metrics-apm` +|==== + +The `production--apm` aliases will contain a filter that only provides access to documents +where the `service.environment` is `production`. +Similarly, the `staging--apm` aliases will contain a filter that only provides access to documents +where the `service.environment` is `staging`. + +To create these six filtered aliases, use the {es} {ref}/indices-aliases.html[Aliases API]. +In {kib}, open **Dev Tools** and run the following POST requests. + +[%collapsible%open] +.`traces-apm*` production alias example +==== +[source, console] +---- +POST /_aliases?pretty +{ + "actions": [ + { + "add": { + "index": "traces-apm*", <1> + "alias": "production-traces-apm", <2> + "filter": { + "term": { + "service.environment": { + "value": "production" <3> + } + } + } + } + } + ] +} +---- +<1> This example matches the APM traces data stream +<2> The alias must not match the default APM index (`traces-apm*,apm-*`) +<3> Only match documents where `service.environment: production` +==== + +[%collapsible] +.`logs-apm*` production alias example +==== +[source, console] +---- +POST /_aliases?pretty +{ + "actions": [ + { + "add": { + "index": "logs-apm*", <1> + "alias": "production-logs-apm", <2> + "filter": { + "term": { + "service.environment": { + "value": "production" <3> + } + } + } + } + } + ] +} +---- +<1> This example matches the APM logs data stream +<2> The alias must not match the default APM index (`logs-apm*,apm-*`) +<3> Only match documents where `service.environment: production` +==== + +[%collapsible] +.`metrics-apm*` production alias example +==== +[source, console] +---- +POST /_aliases?pretty +{ + "actions": [ + { + "add": { + "index": "metrics-apm*", <1> + "alias": "production-metrics-apm", <2> + "filter": { + "term": { + "service.environment": { + "value": "production" <3> + } + } + } + } + } + ] +} +---- +<1> This example matches the APM metrics data stream +<2> The alias must not match the default APM index (`metrics-apm*,apm-*`) +<3> Only match documents where `service.environment: production` +==== + +[%collapsible] +.`traces-apm*` staging alias example +==== +[source, console] +---- +POST /_aliases?pretty +{ + "actions": [ + { + "add": { + "index": "traces-apm*", <1> + "alias": "staging-traces-apm", <2> + "filter": { + "term": { + "service.environment": { + "value": "staging" <3> + } + } + } + } + } + ] +} +---- +<1> This example matches the APM traces data stream +<2> The alias must not match the default APM index (`traces-apm*,apm-*`) +<3> Only match documents where `service.environment: staging` +==== + +[%collapsible] +.`logs-apm*` staging alias example +==== +[source, console] +---- +POST /_aliases?pretty +{ + "actions": [ + { + "add": { + "index": "logs-apm*", <1> + "alias": "staging-logs-apm", <2> + "filter": { + "term": { + "service.environment": { + "value": "staging" <3> + } + } + } + } + } + ] +} +---- +<1> This example matches the APM logs data stream +<2> The alias must not match the default APM index (`logs-apm*,apm-*`) +<3> Only match documents where `service.environment: staging` +==== + +[%collapsible] +.`metrics-apm*` staging alias example +==== +[source, console] +---- +POST /_aliases?pretty +{ + "actions": [ + { + "add": { + "index": "metrics-apm*", <1> + "alias": "staging-metrics-apm", <2> + "filter": { + "term": { + "service.environment": { + "value": "staging" <3> + } + } + } + } + } + ] +} +---- +<1> This example matches the APM metrics data stream +<2> The alias must not match the default APM index (`metrics-apm*,apm-*`) +<3> Only match documents where `service.environment: staging` +==== + +[float] +==== 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**. +For this guide, we've created two Kibana spaces, one named `production` and one named `staging`. + +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 + +Now we can change the default data views that the APM UI queries in each space. + +Open the APM UI and navigate to **Settings** > **Indices**. +Use the table below to update your settings for each space. +The values in each column match the names of the filtered aliases we created in step one. + +[options="header"] +|==== +| Index setting | `production` space | `staging` space +| Error indices | `production-logs-apm` | `staging-logs-apm` +| Span indices | `production-traces-apm` | `staging-traces-apm` +| Transaction indices | `production-traces-apm` | `staging-traces-apm` +| Metrics indices | `production-metrics-apm` | `staging-metrics-apm` +|==== + +[float] +==== Step 4: Create {kib} access roles + +In {kib}, navigate to **Stack Management** > **Roles** and click **Create role**. + +You'll need to create two roles: one for `staging` users (we'll call this role `staging_apm_viewer`) +and one for `production` users (we'll call this role `production_apm_viewer`). + +Using the table below, assign each role the following privileges: + +[options="header"] +|==== +| Privileges | `production_apm_viewer` | `staging_apm_viewer` +| Index privileges | index: `production-*-apm`, privilege: `read` | index: `staging-*-apm`, privilege: `read` +| Kibana privileges | space: `production`, feature privileges: `APM and User Experience: read` | space: `staging`, feature privileges: `APM and User Experience: read` +|==== + +[role="screenshot"] +image::./images/apm-roles-config.png[APM role config example] + +Alternatively, you can use the +{es} {ref}/security-api-put-role.html[Create or update roles API]: + +[%collapsible%open] +.Create a `production_apm_viewer` role +==== +This request creates a `production_apm_viewer` role: + +[source, console] +---- +POST /_security/role/production_apm_viewer +{ + "cluster": [ ], + "indices": [ + { + "names": ["production-*-apm"], <1> + "privileges": ["read"] + } + ], + "applications": [ + { + "application" : "kibana-.kibana", + "privileges" : [ + "feature_apm.read" <2> + ], + "resources" : [ + "space:production" <3> + ] + } + ] +} +---- +<1> This data view matches all of the production aliases created in step one. +<2> Assigns `read` privileges for the APM and User Experience apps. +<3> Provides access to the space named `production`. +==== + +[%collapsible] +.Create a `staging_apm_viewer` role +==== +This request creates a `staging_apm_viewer` role: + +[source, console] +---- +POST /_security/role/staging_apm_viewer +{ + "cluster": [ ], + "indices": [ + { + "names": ["staging-*-apm"], <1> + "privileges": ["read"] + } + ], + "applications": [ + { + "application" : "kibana-.kibana", + "privileges" : [ + "feature_apm.read" <2> + ], + "resources" : [ + "space:staging" <3> + ] + } + ] +} +---- +<1> This data view matches all of the staging aliases created in step one. +<2> Assigns `read` privileges for the APM and User Experience apps. +<3> Provides access to the space named `staging`. +==== + +[float] +==== 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. + +For information on how to create users and assign them roles with the {kib} UI, +see {kibana-ref}/tutorial-secure-access-to-kibana.html[Securing access to Kibana]. + +Alternatively, you can use the +{es} {ref}/security-api-put-user.html[Create or update users API]. + +This example creates a new user and assigns them the `production_apm_viewer` role created in the previous step. +This user will only have access to the production space and data with a `service.environment` of `production`. +Remember to change the `password`, `full_name`, and `email` fields. + +[source, console] +---- +POST /_security/user/production-apm-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "production_apm_viewer" ], <1> + "full_name" : "Jane Production Smith", + "email" : "janesmith@example.com" +} +---- +<1> Assigns the previously created `production_apm_viewer` role. + +This example creates a new user and assigns them the `staging_apm_viewer` role created in the previous step. +This user will only have access to the staging space and data with a `service.environment` of `staging`. +Remember to change the `password`, `full_name`, and `email` fields. + +[source, console] +---- +POST /_security/user/staging-apm-user +{ + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "staging_apm_viewer" ], <1> + "full_name" : "John Staging Doe", + "email" : "johndoe@example.com" +} +---- +<1> Assigns the previously created `staging_apm_viewer` role. + +[float] +==== 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-ui/correlations.asciidoc b/docs/en/observability/apm-ui/correlations.asciidoc new file mode 100644 index 0000000000..b03e3b7895 --- /dev/null +++ b/docs/en/observability/apm-ui/correlations.asciidoc @@ -0,0 +1,88 @@ +[[apm-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 +reliability engineer who is responsible for keeping production systems up and +running, you want to understand what is causing slow transactions. Identifying +attributes that are responsible for higher latency transactions can potentially +point you toward the root cause. You may find a correlation with a particular +piece of hardware, like a host or pod. Or, perhaps a set of users, based on IP +address or region, is facing increased latency due to local data center issues. + +To find correlations, select a service on the *Services* page in the APM UI +then select a transaction group from the *Transactions* tab. + +NOTE: Queries within the APM UI are also applied to the correlations. + +[discrete] +[[correlations-latency]] +==== Find high transaction latency correlations + +The correlations on the *Latency correlations* tab help you discover which +attributes are contributing to increased transaction latency. + +[role="screenshot"] +image::./images/correlations-hover.png[Latency correlations] + +The progress bar indicates the status of the asynchronous analysis, which +performs statistical searches across a large number of attributes. For large +time ranges and services with high transaction throughput, this might take some +time. To improve performance, reduce the time range. + +The latency distribution chart visualizes the overall latency of the +transactions in the transaction group. If there are attributes that have a +statistically significant correlation with slow response times, they are listed +in a table below the chart. The table is sorted by correlation coefficients that +range from 0 to 1. Attributes with higher correlation values are more likely to +contribute to high latency transactions. By default, the attribute with the +highest correlation value is added to the chart. To see the latency distribution +for other attributes, select their row in the table. + +If a correlated attribute seems noteworthy, use the **Filter** quick links: + +* `+` creates a new query in the APM UI for filtering transactions containing +the selected value. +* `-` creates a new query in the APM UI to filter out transactions containing +the selected value. + +You can also click the icon beside the field name to view and filter its most +popular values. + +In this example screenshot, there are transactions that are skewed to the right +with slower response times than the overall latency distribution. If you select +the `+` filter in the appropriate row of the table, it creates a new query in +the APM UI for transactions with this attribute. With the "noise" now +filtered out, you can begin viewing sample traces to continue your investigation. + +[discrete] +[[correlations-error-rate]] +==== Find failed transaction correlations + +The correlations on the *Failed transaction correlations* tab help you discover +which attributes are most influential in distinguishing between transaction +failures and successes. In this context, the success or failure of a transaction +is determined by its {ecs-ref}/ecs-event.html#field-event-outcome[event.outcome] +value. For example, APM agents set the `event.outcome` to `failure` when an HTTP +transaction returns a `5xx` status code. + +The chart highlights the failed transactions in the overall latency distribution +for the transaction group. If there are attributes that have a statistically +significant correlation with failed transactions, they are listed in a table. +The table is sorted by scores, which are mapped to high, medium, or low impact +levels. Attributes with high impact levels are more likely to contribute to +failed transactions. By default, the attribute with the highest score is added +to the chart. To see a different attribute in the chart, select its row in the +table. + +For example, in the screenshot below, there are attributes such as a specific +node and pod name that have medium impact on the failed transactions. + +[role="screenshot"] +image::./images/correlations-failed-transactions.png[Failed transaction correlations] + +Select the `+` filter to create a new query in the APM UI for transactions +with one or more of these attributes. If you are unfamiliar with a field, click +the icon beside its name to view its most popular values and optionally filter +on those values too. Each time that you add another attribute, it is filtering +out more and more noise and bringing you closer to a diagnosis. diff --git a/docs/en/observability/apm-ui/custom-links.asciidoc b/docs/en/observability/apm-ui/custom-links.asciidoc new file mode 100644 index 0000000000..0e235c125e --- /dev/null +++ b/docs/en/observability/apm-ui/custom-links.asciidoc @@ -0,0 +1,221 @@ +[[apm-custom-links]] +=== Custom links + +++++ +Create custom links +++++ + +Elastic's custom link feature allows you to easily create up to 500 dynamic links +based on your specific APM data. +Custom links can be filtered to only appear in the APM UI for relevant services, +environments, transaction types, or transaction names. + +Ready to dive in? Jump straight to the <>. + +[float] +[[custom-links-create]] +=== 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. +This method will automatically apply filters, scoping the link to that specific service, +environment, transaction type, and transaction name. + +Alternatively, you can create a custom link in the APM UI by navigating to **Settings** > **Customize UI**, +and selecting **Create custom link**. + +[float] +[[custom-links-label]] +==== Label + +The name of your custom link. +The actions context menu displays this text, so keep it as short as possible. + +TIP: Custom links are displayed alphabetically in the actions menu. + +[float] +[[custom-links-url]] +==== URL + +The URL your link points to. +URLs support dynamic field name variables, encapsulated in double curly brackets: `{{field.name}}`. +These variables will be replaced with transaction metadata when the link is clicked. + +Because everyone's data is different, +you'll need to examine your traces to see what metadata is available for use. +To do this, select a trace in the APM UI, and click **Metadata** in the **Trace Sample** table. + +[role="screenshot"] +image::./images/example-metadata.png[Example metadata] + +[float] +[[custom-links-filters]] +==== Filters + +Filter each link to only appear for specific services or transactions. +You can filter on the following fields: + +* `service.name` +* `service.env` +* `transaction.type` +* `transaction.name` + +Multiple values are allowed when comma-separated. + +[float] +[[custom-links-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 +:github-query-params: https://help.github.com/en/github/managing-your-work-on-github/about-automation-for-issues-and-pull-requests-with-query-parameters + +Not sure where to start with custom links? +Take a look at the examples below and customize them to your liking! + +[float] +[[custom-links-examples-email]] +==== Email + +Email the owner of a service. + +|==== +|Label |`Email engineer` +|Link |`mailto:@.com` +|Filters |`service.name:` +|==== + +**Example** + +This link opens an email addressed to the team or owner of `python-backend`. +It will only appear on services with the name `python-backend`. + +|==== +|Label |`Email python-backend engineers` +|Link |`mailto:python_team@elastic.co` +|Filters |`service.name:python-backend` +|==== + +[float] +[[custom-links-examples-gh]] +==== GitHub issue + +Open a GitHub issue with pre-populated metadata from the selected trace sample. + +|==== +|Label |`Open an issue in ` +|Link |`https://github.com///issues/new?title=&body=<BODY>` +|Filters |`service.name:client` +|==== + +**Example** + +This link opens a new GitHub issue in the apm-agent-rum repository. +It populates the issue body with relevant metadata from the currently active trace. +Clicking this link results in the following issue being created: + +[role="screenshot"] +image::./images/create-github-issue.png[Example github issue] + +|==== +|Label |`Open an issue in apm-rum-js` +|Link |`https://github.com/elastic/apm-agent-rum-js/issues/new?title=Investigate+APM+trace&body=Investigate+the+following+APM+trace%3A%0D%0A%0D%0Aservice.name%3A+{{service.name}}%0D%0Atransaction.id%3A+{{transaction.id}}%0D%0Acontainer.id%3A+{{container.id}}%0D%0Aurl.full%3A+{{url.full}}` +|Filters |`service.name:client` +|==== + +See the {github-query-params}[GitHub automation documentation] for a full list of supported query parameters. + +[float] +[[custom-links-examples-jira]] +==== Jira task + +Create a Jira task with pre-populated metadata from the selected trace sample. + +|==== +|Label |`Open an issue in Jira` +|Link |`https://<JIRA_BASE_URL>/secure/CreateIssueDetails!init.jspa?<ARGUMENTS>` +|==== + +**Example** + +This link creates a new task on the Engineering board in Jira. +It populates the issue body with relevant metadata from the currently active trace. +Clicking this link results in the following task being created in Jira: + +[role="screenshot"] +image::./images/create-jira-issue.png[Example jira issue] + +|==== +|Label |`Open a task in Jira` +|Link |`https://test-site-33.atlassian.net/secure/CreateIssueDetails!init.jspa?pid=10000&issuetype=10001&summary=Created+via+APM&description=Investigate+the+following+APM+trace%3A%0D%0A%0D%0Aservice.name%3A+{{service.name}}%0D%0Atransaction.id%3A+{{transaction.id}}%0D%0Acontainer.id%3A+{{container.id}}%0D%0Aurl.full%3A+{{url.full}}` +|==== + +See the {jira-query-params}[Jira application administration knowledge base] +for a full list of supported query parameters. + +[float] +[[custom-links-examples-kib]] +==== Kibana dashboards + +Link to a custom dashboard in Kibana. + +|==== +|Label |`Open transaction in custom visualization` +|Link |`https://kibana-instance/app/kibana#/dashboard?_g=query:(language:kuery,query:'transaction.id:{{transaction.id}}'...` +|==== + +**Example** + +This link opens the current `transaction.id` in a custom kibana dashboard. +There are no filters set. + +|==== +|Label |`Open transaction in Python drilldown viz` +|URL |`https://kibana-instance/app/kibana#/dashboard?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-24h,to:now))&_a=(description:'',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),panels:!((embeddableConfig:(),gridData:(h:15,i:cb79c1c0-1af8-472c-aaf7-d158a76946fb,w:24,x:0,y:0),id:c8c74b20-6a30-11ea-92ab-b5d3feff11df,panelIndex:cb79c1c0-1af8-472c-aaf7-d158a76946fb,type:visualization,version:'7.7')),query:(language:kuery,query:'transaction.id:{{transaction.id}}'),timeRestore:!f,title:'',viewMode:edit)` +|==== + +[float] +[[custom-links-examples-slack]] +==== Slack channel + +Open a specified slack channel. + +|==== +|Label |`Open SLACK_CHANNEL` +|Link |`https://COMPANY_SLACK.slack.com/archives/SLACK_CHANNEL` +|Filters |`service.name` : `SERVICE_NAME` +|==== + +**Example** + +This link opens a company slack channel, #apm-support. +It only appears when `transaction.name` is `GET user/login`. + +|==== +|Label |`Open #apm-user-support` +|Link |`https://microsoft.slack.com/archives/efk52kt23k` +|Filters |`transaction.name:GET user/login` +|==== + +[float] +[[custom-links-examples-web]] +==== Website + +Open an internal or external website. + +|==== +|Label |`Open <WEBSITE>` +|Link |`https://<COMPANY_SLACK>.slack.com/archives/<SLACK_CHANNEL>` +|Filters |`service.name:<SERVICE_NAME>` +|==== + +**Example** + +This link opens more data on a specific `user.email`. +It only appears on front-end transactions. + +|==== +|Label |`View user internally` +|Link |`https://internal-site.company.com/user/{{user.email}}` +|Filters |`service.name:client` +|==== diff --git a/docs/en/observability/apm-ui/dependencies.asciidoc b/docs/en/observability/apm-ui/dependencies.asciidoc new file mode 100644 index 0000000000..28072b4439 --- /dev/null +++ b/docs/en/observability/apm-ui/dependencies.asciidoc @@ -0,0 +1,47 @@ +[[apm-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, +you can utilize <<distributed-tracing,distributed tracing>> to drill down into problematic downstream services. +Other times, though, it's not possible to instrument a downstream dependency -- +like with a database or third-party service. +**Dependencies** gives you a window into these uninstrumented, downstream dependencies. + +[role="screenshot"] +image::./images/dependencies.png[Dependencies view in the APM UI in Kibana] + +Many application issues are caused by slow or unresponsive downstream dependencies. +And because a single, slow dependency can significantly impact the end-user experience, +it's important to be able to quickly identify these problems and determine the root cause. + +Select a dependency to see detailed latency, throughput, and failed transaction rate metrics. + +[role="screenshot"] +image::./images/dependencies-drilldown.png[Dependencies drilldown view in the APM UI in Kibana] + +When viewing a dependency, consider your pattern of usage with that dependency. +If your usage pattern _hasn't_ increased or decreased, +but the experience has been negatively effected -- either with an increase in latency or errors, +there's likely a problem with the dependency that needs to be addressed. + +If your usage pattern _has_ changed, the dependency view can quickly show you whether +that pattern change exists in all upstream services, or just a subset of your services. +You might then start digging into traces coming from +impacted services to determine why that pattern change has occurred. + +[float] +[[dependencies-operations]] +==== Operations + +beta::[] + +**Dependency operations** provides a granular breakdown of the operations/queries a dependency is executing. + +[role="screenshot"] +image::./images/operations.png[operations view in the APM UI in Kibana] + +Selecting an operation displays the operation's impact and performance trends over time, via key metrics like latency, throughput, and failed transaction rate. In addition, the <<apm-spans,**Trace sample timeline**>> provides a visual drill-down into an end-to-end trace sample. + +[role="screenshot"] +image::./images/operations-detail.png[operations detail view in the APM UI in Kibana] diff --git a/docs/en/observability/apm-ui/deployment-annotations.asciidoc b/docs/en/observability/apm-ui/deployment-annotations.asciidoc new file mode 100644 index 0000000000..64ec043eac --- /dev/null +++ b/docs/en/observability/apm-ui/deployment-annotations.asciidoc @@ -0,0 +1,47 @@ +[[apm-transactions-annotations]] +=== Track deployments with annotations + +++++ +<titleabbrev>Track deployments with annotations</titleabbrev> +++++ + +[role="screenshot"] +image::./images/apm-transaction-annotation.png[Example view of transactions annotation in the APM UI in Kibana] + +For enhanced visibility into your deployments, we offer deployment annotations on all transaction charts. +This feature enables 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. +Being able to quickly identify bad deployments enables you to rollback and fix issues without causing costly outages. + +By default, automatic deployment annotations are enabled. +This means the APM UI will create an annotation on your data when the `service.version` of your application changes. + +Alternatively, you can explicitly create deployment annotations with our annotation API. +The API can integrate into your CI/CD pipeline, +so that each time you deploy, a POST request is sent to the annotation API endpoint: + +[source,curl] +---- +curl -X POST \ + http://localhost:5601/api/apm/services/${SERVICE_NAME}/annotation \ <1> +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: Basic ${API_KEY}' \ <2> +-d '{ + "@timestamp": "${DEPLOY_TIME}", <3> + "service": { + "version": "${SERVICE_VERSION}" <4> + }, + "message": "${MESSAGE}" <5> + }' +---- +<1> The `service.name` of your application +<2> An APM UI API key with sufficient privileges +<3> The time of the deployment +<4> The `service.version` to be displayed in the annotation +<5> A custom message to be displayed in the annotation + +See the <<apm-annotation-api,annotation API>> reference for more information. + + +NOTE: If custom annotations have been created for the selected time period, any derived annotations, i.e., those created automatically when `service.version` changes, will not be shown. diff --git a/docs/en/observability/apm-ui/errors.asciidoc b/docs/en/observability/apm-ui/errors.asciidoc new file mode 100644 index 0000000000..cf6ed775c3 --- /dev/null +++ b/docs/en/observability/apm-ui/errors.asciidoc @@ -0,0 +1,35 @@ +[[apm-errors]] +=== Errors + +TIP: {apm-guide-ref}/data-model-errors.html[Errors] are groups of exceptions with a similar exception or log message. + +The *Errors* overview provides a high-level view of the exceptions that APM agents catch, +or that users manually report with APM agent APIs. +Like errors are grouped together to make it easy to quickly see which errors are affecting your services, +and to take actions to rectify them. + +A service returning a 5xx code from a request handler, controller, etc., will not create +an exception that an APM agent can catch, and will therefore not show up in this view. + +[role="screenshot"] +image::./images/apm-errors-overview.png[APM Errors overview] + +Selecting an error group ID or error message brings you to the *Error group*. + +[role="screenshot"] +image::./images/apm-error-group.png[APM Error group] + +The error group details page visualizes the number of error occurrences over time and compared to a recent time range. +This allows you to quickly determine if the error rate is changing or remaining constant. +You'll also see the top 5 affected transactions--enabling you to quickly narrow down which transactions are most impacted +by the selected error. + +Further down, you'll see an Error sample. +The error shown is always the most recent to occur. +The sample includes the exception message, culprit, stack trace where the error occurred, +and additional contextual information to help debug the issue--all of which can be copied with the click of a button. + +In some cases, you might also see a Transaction sample ID. +This feature allows you to make a connection between the errors and transactions, +by linking you to the specific transaction where the error occurred. +This allows you to see the whole trace, including which services the request went through. diff --git a/docs/en/observability/apm-ui/filters.asciidoc b/docs/en/observability/apm-ui/filters.asciidoc new file mode 100644 index 0000000000..b2aa0f0fbd --- /dev/null +++ b/docs/en/observability/apm-ui/filters.asciidoc @@ -0,0 +1,47 @@ +[[apm-filters]] +=== Filters + +++++ +<titleabbrev>Filter data</titleabbrev> +++++ + +Global filters are ways you can filter data across the APM UI based on a specific +time range or environment. When viewing a specific service, the filter persists +as you move between tabs. + +[role="screenshot"] +image::./images/global-filters.png[Global filters available in the APM UI in Kibana] + +[NOTE] +===== +If you prefer to use advanced queries on your data to filter on specific pieces +of information, see <<apm-advanced-queries,Query your data>>. +===== + +[discrete] +[[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 + +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. +By default, all environments are displayed. If there are no environment options, you'll see "not defined". + +Service environments are defined when configuring your APM agents. +It's vital to be consistent when naming environments in your APM agents. +To learn how to configure service environments, see the specific APM agent documentation: + +* *Go:* {apm-go-ref}/configuration.html#config-environment[`ELASTIC_APM_ENVIRONMENT`] +* *iOS agent:* _Not yet supported_ +* *Java:* {apm-java-ref}/config-core.html#config-environment[`environment`] +* *.NET:* {apm-dotnet-ref}/config-core.html#config-environment[`Environment`] +* *Node.js:* {apm-node-ref}/configuration.html#environment[`environment`] +* *PHP:* {apm-php-ref}/configuration-reference.html#config-environment[`environment`] +* *Python:* {apm-py-ref}/configuration.html#config-environment[`environment`] +* *Ruby:* {apm-ruby-ref}/configuration.html#config-environment[`environment`] +* *Real User Monitoring:* {apm-rum-ref}/configuration.html#environment[`environment`] diff --git a/docs/en/observability/apm-ui/images/active-alert-service.png b/docs/en/observability/apm-ui/images/active-alert-service.png new file mode 100644 index 0000000000..7d7deaf078 Binary files /dev/null and b/docs/en/observability/apm-ui/images/active-alert-service.png differ diff --git a/docs/en/observability/apm-ui/images/add-variable.png b/docs/en/observability/apm-ui/images/add-variable.png new file mode 100644 index 0000000000..860ab66f22 Binary files /dev/null and b/docs/en/observability/apm-ui/images/add-variable.png differ diff --git a/docs/en/observability/apm-ui/images/advanced-discover.png b/docs/en/observability/apm-ui/images/advanced-discover.png new file mode 100644 index 0000000000..5291526783 Binary files /dev/null and b/docs/en/observability/apm-ui/images/advanced-discover.png differ diff --git a/docs/en/observability/apm-ui/images/all-instances.png b/docs/en/observability/apm-ui/images/all-instances.png new file mode 100644 index 0000000000..70028b5a9b Binary files /dev/null and b/docs/en/observability/apm-ui/images/all-instances.png differ diff --git a/docs/en/observability/apm-ui/images/apm-agent-configuration.png b/docs/en/observability/apm-ui/images/apm-agent-configuration.png new file mode 100644 index 0000000000..22fd9d75c3 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-agent-configuration.png differ diff --git a/docs/en/observability/apm-ui/images/apm-agent-explorer-flyout.png b/docs/en/observability/apm-ui/images/apm-agent-explorer-flyout.png new file mode 100644 index 0000000000..9792a93a71 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-agent-explorer-flyout.png differ diff --git a/docs/en/observability/apm-ui/images/apm-agent-explorer.png b/docs/en/observability/apm-ui/images/apm-agent-explorer.png new file mode 100644 index 0000000000..c6fb7d031e Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-agent-explorer.png differ diff --git a/docs/en/observability/apm-ui/images/apm-alert.png b/docs/en/observability/apm-ui/images/apm-alert.png new file mode 100644 index 0000000000..ccaf2de64e Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-alert.png differ diff --git a/docs/en/observability/apm-ui/images/apm-anomaly-alert.png b/docs/en/observability/apm-ui/images/apm-anomaly-alert.png new file mode 100644 index 0000000000..35ce9a2296 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-anomaly-alert.png differ diff --git a/docs/en/observability/apm-ui/images/apm-distributed-tracing.png b/docs/en/observability/apm-ui/images/apm-distributed-tracing.png new file mode 100644 index 0000000000..4d1b8cde20 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-distributed-tracing.png differ diff --git a/docs/en/observability/apm-ui/images/apm-error-group.png b/docs/en/observability/apm-ui/images/apm-error-group.png new file mode 100644 index 0000000000..22bceb9d81 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-error-group.png differ diff --git a/docs/en/observability/apm-ui/images/apm-errors-overview.png b/docs/en/observability/apm-ui/images/apm-errors-overview.png new file mode 100644 index 0000000000..c390b7ddc0 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-errors-overview.png differ diff --git a/docs/en/observability/apm-ui/images/apm-errors-watcher-assistant.png b/docs/en/observability/apm-ui/images/apm-errors-watcher-assistant.png new file mode 100644 index 0000000000..1a4d6b5b4c Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-errors-watcher-assistant.png differ diff --git a/docs/en/observability/apm-ui/images/apm-geo-ui.png b/docs/en/observability/apm-ui/images/apm-geo-ui.png new file mode 100644 index 0000000000..69c1390a27 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-geo-ui.png differ diff --git a/docs/en/observability/apm-ui/images/apm-index-pattern.png b/docs/en/observability/apm-ui/images/apm-index-pattern.png new file mode 100644 index 0000000000..b389110fc4 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-index-pattern.png differ diff --git a/docs/en/observability/apm-ui/images/apm-integration-config.png b/docs/en/observability/apm-ui/images/apm-integration-config.png new file mode 100644 index 0000000000..7ff5cb5e9d Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-integration-config.png differ diff --git a/docs/en/observability/apm-ui/images/apm-logs-tab.png b/docs/en/observability/apm-ui/images/apm-logs-tab.png new file mode 100644 index 0000000000..c79be8b5eb Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-logs-tab.png differ diff --git a/docs/en/observability/apm-ui/images/apm-metrics.png b/docs/en/observability/apm-ui/images/apm-metrics.png new file mode 100644 index 0000000000..c2d609c7c4 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-metrics.png differ diff --git a/docs/en/observability/apm-ui/images/apm-ml-integration.png b/docs/en/observability/apm-ui/images/apm-ml-integration.png new file mode 100644 index 0000000000..e95dae5a41 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-ml-integration.png differ diff --git a/docs/en/observability/apm-ui/images/apm-query-bar.png b/docs/en/observability/apm-ui/images/apm-query-bar.png new file mode 100644 index 0000000000..457573f485 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-query-bar.png differ diff --git a/docs/en/observability/apm-ui/images/apm-roles-config.png b/docs/en/observability/apm-ui/images/apm-roles-config.png new file mode 100644 index 0000000000..ebd992abe9 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-roles-config.png differ diff --git a/docs/en/observability/apm-ui/images/apm-service-group.png b/docs/en/observability/apm-ui/images/apm-service-group.png new file mode 100644 index 0000000000..44a0191411 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-service-group.png differ diff --git a/docs/en/observability/apm-ui/images/apm-service-map-anomaly.png b/docs/en/observability/apm-ui/images/apm-service-map-anomaly.png new file mode 100644 index 0000000000..cd59f86690 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-service-map-anomaly.png differ diff --git a/docs/en/observability/apm-ui/images/apm-services-overview.png b/docs/en/observability/apm-ui/images/apm-services-overview.png new file mode 100644 index 0000000000..0badeea3be Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-services-overview.png differ diff --git a/docs/en/observability/apm-ui/images/apm-services-trace.png b/docs/en/observability/apm-ui/images/apm-services-trace.png new file mode 100644 index 0000000000..083c69318e Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-services-trace.png differ diff --git a/docs/en/observability/apm-ui/images/apm-settings.png b/docs/en/observability/apm-ui/images/apm-settings.png new file mode 100644 index 0000000000..2c8ebace28 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-settings.png differ diff --git a/docs/en/observability/apm-ui/images/apm-setup.png b/docs/en/observability/apm-ui/images/apm-setup.png new file mode 100644 index 0000000000..8aadd8911c Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-setup.png differ diff --git a/docs/en/observability/apm-ui/images/apm-span-detail.png b/docs/en/observability/apm-ui/images/apm-span-detail.png new file mode 100644 index 0000000000..d0b6a4de3d Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-span-detail.png differ diff --git a/docs/en/observability/apm-ui/images/apm-traces.png b/docs/en/observability/apm-ui/images/apm-traces.png new file mode 100644 index 0000000000..c8b8d40b01 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-traces.png differ diff --git a/docs/en/observability/apm-ui/images/apm-transaction-annotation.png b/docs/en/observability/apm-ui/images/apm-transaction-annotation.png new file mode 100644 index 0000000000..b9360db2ff Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-transaction-annotation.png differ diff --git a/docs/en/observability/apm-ui/images/apm-transaction-duration-dist.png b/docs/en/observability/apm-ui/images/apm-transaction-duration-dist.png new file mode 100644 index 0000000000..9c7ab5dd67 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-transaction-duration-dist.png differ diff --git a/docs/en/observability/apm-ui/images/apm-transaction-response-dist.png b/docs/en/observability/apm-ui/images/apm-transaction-response-dist.png new file mode 100644 index 0000000000..70e5ad7041 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-transaction-response-dist.png differ diff --git a/docs/en/observability/apm-ui/images/apm-transaction-sample.png b/docs/en/observability/apm-ui/images/apm-transaction-sample.png new file mode 100644 index 0000000000..a9490fc20d Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-transaction-sample.png differ diff --git a/docs/en/observability/apm-ui/images/apm-transactions-overview.png b/docs/en/observability/apm-ui/images/apm-transactions-overview.png new file mode 100644 index 0000000000..34cd0219b8 Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-transactions-overview.png differ diff --git a/docs/en/observability/apm-ui/images/apm-transactions-table.png b/docs/en/observability/apm-ui/images/apm-transactions-table.png new file mode 100644 index 0000000000..8a3415bc9a Binary files /dev/null and b/docs/en/observability/apm-ui/images/apm-transactions-table.png differ diff --git a/docs/en/observability/apm-ui/images/correlations-failed-transactions.png b/docs/en/observability/apm-ui/images/correlations-failed-transactions.png new file mode 100644 index 0000000000..19221e751e Binary files /dev/null and b/docs/en/observability/apm-ui/images/correlations-failed-transactions.png differ diff --git a/docs/en/observability/apm-ui/images/correlations-hover.png b/docs/en/observability/apm-ui/images/correlations-hover.png new file mode 100644 index 0000000000..9731517b32 Binary files /dev/null and b/docs/en/observability/apm-ui/images/correlations-hover.png differ diff --git a/docs/en/observability/apm-ui/images/create-github-issue.png b/docs/en/observability/apm-ui/images/create-github-issue.png new file mode 100644 index 0000000000..81ea4e5e78 Binary files /dev/null and b/docs/en/observability/apm-ui/images/create-github-issue.png differ diff --git a/docs/en/observability/apm-ui/images/create-jira-issue.png b/docs/en/observability/apm-ui/images/create-jira-issue.png new file mode 100644 index 0000000000..962c98df3f Binary files /dev/null and b/docs/en/observability/apm-ui/images/create-jira-issue.png differ diff --git a/docs/en/observability/apm-ui/images/dependencies-drilldown.png b/docs/en/observability/apm-ui/images/dependencies-drilldown.png new file mode 100644 index 0000000000..af82ee3d93 Binary files /dev/null and b/docs/en/observability/apm-ui/images/dependencies-drilldown.png differ diff --git a/docs/en/observability/apm-ui/images/dependencies.png b/docs/en/observability/apm-ui/images/dependencies.png new file mode 100644 index 0000000000..260025d316 Binary files /dev/null and b/docs/en/observability/apm-ui/images/dependencies.png differ diff --git a/docs/en/observability/apm-ui/images/dynamic-config.svg b/docs/en/observability/apm-ui/images/dynamic-config.svg new file mode 100644 index 0000000000..df62a3c84f --- /dev/null +++ b/docs/en/observability/apm-ui/images/dynamic-config.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="59" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="59" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#9f9f9f" d="M0 0h0v20H0z"/><path fill="#9f9f9f" d="M0 0h59v20H0z"/><path fill="url(#b)" d="M0 0h59v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"> <text x="295" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">Dynamic</text><text x="295" y="140" transform="scale(.1)" textLength="490">Dynamic</text></g> </svg> \ No newline at end of file diff --git a/docs/en/observability/apm-ui/images/error-rate.png b/docs/en/observability/apm-ui/images/error-rate.png new file mode 100644 index 0000000000..845fa2af07 Binary files /dev/null and b/docs/en/observability/apm-ui/images/error-rate.png differ diff --git a/docs/en/observability/apm-ui/images/example-metadata.png b/docs/en/observability/apm-ui/images/example-metadata.png new file mode 100644 index 0000000000..2a5bda7f08 Binary files /dev/null and b/docs/en/observability/apm-ui/images/example-metadata.png differ diff --git a/docs/en/observability/apm-ui/images/global-filters.png b/docs/en/observability/apm-ui/images/global-filters.png new file mode 100644 index 0000000000..f93a5214c3 Binary files /dev/null and b/docs/en/observability/apm-ui/images/global-filters.png differ diff --git a/docs/en/observability/apm-ui/images/green-service.png b/docs/en/observability/apm-ui/images/green-service.png new file mode 100644 index 0000000000..bbc00a3543 Binary files /dev/null and b/docs/en/observability/apm-ui/images/green-service.png differ diff --git a/docs/en/observability/apm-ui/images/infra.png b/docs/en/observability/apm-ui/images/infra.png new file mode 100644 index 0000000000..e139012270 Binary files /dev/null and b/docs/en/observability/apm-ui/images/infra.png differ diff --git a/docs/en/observability/apm-ui/images/jvm-metrics-overview.png b/docs/en/observability/apm-ui/images/jvm-metrics-overview.png new file mode 100644 index 0000000000..c6f28f7bdf Binary files /dev/null and b/docs/en/observability/apm-ui/images/jvm-metrics-overview.png differ diff --git a/docs/en/observability/apm-ui/images/jvm-metrics.png b/docs/en/observability/apm-ui/images/jvm-metrics.png new file mode 100644 index 0000000000..70f7965b72 Binary files /dev/null and b/docs/en/observability/apm-ui/images/jvm-metrics.png differ diff --git a/docs/en/observability/apm-ui/images/lambda-cold-start-trace.png b/docs/en/observability/apm-ui/images/lambda-cold-start-trace.png new file mode 100644 index 0000000000..c6f6efd055 Binary files /dev/null and b/docs/en/observability/apm-ui/images/lambda-cold-start-trace.png differ diff --git a/docs/en/observability/apm-ui/images/lambda-correlations.png b/docs/en/observability/apm-ui/images/lambda-correlations.png new file mode 100644 index 0000000000..c1a72ccb2d Binary files /dev/null and b/docs/en/observability/apm-ui/images/lambda-correlations.png differ diff --git a/docs/en/observability/apm-ui/images/lambda-overview.png b/docs/en/observability/apm-ui/images/lambda-overview.png new file mode 100644 index 0000000000..9d0558949f Binary files /dev/null and b/docs/en/observability/apm-ui/images/lambda-overview.png differ diff --git a/docs/en/observability/apm-ui/images/latency.png b/docs/en/observability/apm-ui/images/latency.png new file mode 100644 index 0000000000..1c220c1a4b Binary files /dev/null and b/docs/en/observability/apm-ui/images/latency.png differ diff --git a/docs/en/observability/apm-ui/images/local-filter.png b/docs/en/observability/apm-ui/images/local-filter.png new file mode 100644 index 0000000000..edcaf8b6a6 Binary files /dev/null and b/docs/en/observability/apm-ui/images/local-filter.png differ diff --git a/docs/en/observability/apm-ui/images/logs.png b/docs/en/observability/apm-ui/images/logs.png new file mode 100644 index 0000000000..94d77b4749 Binary files /dev/null and b/docs/en/observability/apm-ui/images/logs.png differ diff --git a/docs/en/observability/apm-ui/images/metadata-icons.png b/docs/en/observability/apm-ui/images/metadata-icons.png new file mode 100644 index 0000000000..402c0ed07c Binary files /dev/null and b/docs/en/observability/apm-ui/images/metadata-icons.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-location.png b/docs/en/observability/apm-ui/images/mobile-location.png new file mode 100644 index 0000000000..35b0d91a2d Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-location.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-most-used.png b/docs/en/observability/apm-ui/images/mobile-most-used.png new file mode 100644 index 0000000000..24b29f95d4 Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-most-used.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-session-error-details.png b/docs/en/observability/apm-ui/images/mobile-session-error-details.png new file mode 100644 index 0000000000..41c0bf5095 Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-session-error-details.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-session-explorer-apm.png b/docs/en/observability/apm-ui/images/mobile-session-explorer-apm.png new file mode 100644 index 0000000000..55fbc85790 Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-session-explorer-apm.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-session-explorer-nav.png b/docs/en/observability/apm-ui/images/mobile-session-explorer-nav.png new file mode 100644 index 0000000000..d208f40912 Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-session-explorer-nav.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-session-filter-discover.png b/docs/en/observability/apm-ui/images/mobile-session-filter-discover.png new file mode 100644 index 0000000000..989284ba2a Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-session-filter-discover.png differ diff --git a/docs/en/observability/apm-ui/images/mobile-tp.png b/docs/en/observability/apm-ui/images/mobile-tp.png new file mode 100644 index 0000000000..81ce267fb8 Binary files /dev/null and b/docs/en/observability/apm-ui/images/mobile-tp.png differ diff --git a/docs/en/observability/apm-ui/images/operations-detail.png b/docs/en/observability/apm-ui/images/operations-detail.png new file mode 100644 index 0000000000..64a1c65508 Binary files /dev/null and b/docs/en/observability/apm-ui/images/operations-detail.png differ diff --git a/docs/en/observability/apm-ui/images/operations.png b/docs/en/observability/apm-ui/images/operations.png new file mode 100644 index 0000000000..119f8bdf99 Binary files /dev/null and b/docs/en/observability/apm-ui/images/operations.png differ diff --git a/docs/en/observability/apm-ui/images/red-service.png b/docs/en/observability/apm-ui/images/red-service.png new file mode 100644 index 0000000000..be7a62b177 Binary files /dev/null and b/docs/en/observability/apm-ui/images/red-service.png differ diff --git a/docs/en/observability/apm-ui/images/service-maps-java.png b/docs/en/observability/apm-ui/images/service-maps-java.png new file mode 100644 index 0000000000..aa8e5dc505 Binary files /dev/null and b/docs/en/observability/apm-ui/images/service-maps-java.png differ diff --git a/docs/en/observability/apm-ui/images/service-maps.png b/docs/en/observability/apm-ui/images/service-maps.png new file mode 100644 index 0000000000..3d8d48bd95 Binary files /dev/null and b/docs/en/observability/apm-ui/images/service-maps.png differ diff --git a/docs/en/observability/apm-ui/images/service-quick-health.png b/docs/en/observability/apm-ui/images/service-quick-health.png new file mode 100644 index 0000000000..aab1332513 Binary files /dev/null and b/docs/en/observability/apm-ui/images/service-quick-health.png differ diff --git a/docs/en/observability/apm-ui/images/spans-dependencies.png b/docs/en/observability/apm-ui/images/spans-dependencies.png new file mode 100644 index 0000000000..558099dd45 Binary files /dev/null and b/docs/en/observability/apm-ui/images/spans-dependencies.png differ diff --git a/docs/en/observability/apm-ui/images/specific-transaction-search.png b/docs/en/observability/apm-ui/images/specific-transaction-search.png new file mode 100644 index 0000000000..4ed548f015 Binary files /dev/null and b/docs/en/observability/apm-ui/images/specific-transaction-search.png differ diff --git a/docs/en/observability/apm-ui/images/specific-transaction.png b/docs/en/observability/apm-ui/images/specific-transaction.png new file mode 100644 index 0000000000..52073bf765 Binary files /dev/null and b/docs/en/observability/apm-ui/images/specific-transaction.png differ diff --git a/docs/en/observability/apm-ui/images/storage-explorer-expanded.png b/docs/en/observability/apm-ui/images/storage-explorer-expanded.png new file mode 100644 index 0000000000..844f07b6f8 Binary files /dev/null and b/docs/en/observability/apm-ui/images/storage-explorer-expanded.png differ diff --git a/docs/en/observability/apm-ui/images/storage-explorer-overview.png b/docs/en/observability/apm-ui/images/storage-explorer-overview.png new file mode 100644 index 0000000000..d3fcccca5f Binary files /dev/null and b/docs/en/observability/apm-ui/images/storage-explorer-overview.png differ diff --git a/docs/en/observability/apm-ui/images/time-series-expected-bounds-comparison.png b/docs/en/observability/apm-ui/images/time-series-expected-bounds-comparison.png new file mode 100644 index 0000000000..6e705064e6 Binary files /dev/null and b/docs/en/observability/apm-ui/images/time-series-expected-bounds-comparison.png differ diff --git a/docs/en/observability/apm-ui/images/trace-explorer.png b/docs/en/observability/apm-ui/images/trace-explorer.png new file mode 100644 index 0000000000..70c13f650e Binary files /dev/null and b/docs/en/observability/apm-ui/images/trace-explorer.png differ diff --git a/docs/en/observability/apm-ui/images/traffic-transactions.png b/docs/en/observability/apm-ui/images/traffic-transactions.png new file mode 100644 index 0000000000..05e66dfaa4 Binary files /dev/null and b/docs/en/observability/apm-ui/images/traffic-transactions.png differ diff --git a/docs/en/observability/apm-ui/images/transaction-icon.png b/docs/en/observability/apm-ui/images/transaction-icon.png new file mode 100644 index 0000000000..3534e6915d Binary files /dev/null and b/docs/en/observability/apm-ui/images/transaction-icon.png differ diff --git a/docs/en/observability/apm-ui/images/yellow-service.png b/docs/en/observability/apm-ui/images/yellow-service.png new file mode 100644 index 0000000000..43afd6250b Binary files /dev/null and b/docs/en/observability/apm-ui/images/yellow-service.png differ diff --git a/docs/en/observability/apm-ui/index.asciidoc b/docs/en/observability/apm-ui/index.asciidoc new file mode 100644 index 0000000000..dfd233c3f6 --- /dev/null +++ b/docs/en/observability/apm-ui/index.asciidoc @@ -0,0 +1,74 @@ +[[apm-ui]] += Navigate the APM UI + +TIP: For task-oriented guides, see the <<apm-how-to-guides>>. + +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: + +* <<apm-services>> +* <<apm-traces>> +* <<apm-dependencies>> +* <<apm-service-maps>> + +Notice something awry? Select a service or trace and dive deeper with: + +* <<apm-service-overview>> +* <<apm-mobile-service-overview>> +* <<apm-transactions>> +* <<apm-spans>> +* <<apm-errors>> +* <<apm-metrics>> +* <<apm-infrastructure>> +* <<apm-logs>> + +Configure and troubleshoot the APM UI: + +* <<apm-app-users>> +* <<apm-settings-in-kibana>> +* <<apm-app-troubleshooting>> + +include::services.asciidoc[leveloffset=-1] + +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-ui/infrastructure.asciidoc b/docs/en/observability/apm-ui/infrastructure.asciidoc new file mode 100644 index 0000000000..41648d2178 --- /dev/null +++ b/docs/en/observability/apm-ui/infrastructure.asciidoc @@ -0,0 +1,14 @@ +[[apm-infrastructure]] +=== Infrastructure + +beta::[] + +The *Infrastructure* tab provides information about the containers, pods, and hosts +that the selected service is linked to. + +[role="screenshot"] +image::./images/infra.png[Example view of the Infrastructure tab in APM UI in Kibana] + +IT ops and software reliability engineers (SREs) can use this tab +to quickly find a service's underlying infrastructure resources when debugging a problem. +Knowing what infrastructure is related to a service allows you to remediate issues by restarting, killing hanging instances, changing configuration, rolling back deployments, scaling up, scaling out, and so on. \ No newline at end of file diff --git a/docs/en/observability/apm-ui/lambda.asciidoc b/docs/en/observability/apm-ui/lambda.asciidoc new file mode 100644 index 0000000000..e0cbf756ce --- /dev/null +++ b/docs/en/observability/apm-ui/lambda.asciidoc @@ -0,0 +1,51 @@ +[[apm-lambda]] +=== 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 +get insight into function execution and runtime behavior, like lambda duration, cold start rate, cold start duration, compute usage, memory usage, and more. + +To set up Lambda monitoring, see the relevant +{apm-guide-ref}/monitoring-aws-lambda.html[quick start guide]. + +[role="screenshot"] +image::./images/lambda-overview.png[lambda overview] + +[float] +[[apm-lambda-cold-start-info]] +==== 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. + +Cold starts are an unavoidable byproduct of the serverless world, but visibility into how they impact your services can help you make better decisions about factors like how much memory to allocate to a function, whether to enable provisioned concurrency, or if it's time to consider removing a large dependency. + +[float] +[[apm-lambda-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. + +Cold start is also displayed in the trace waterfall, where you can drill-down into individual traces and see trace metadata like AWS request ID, trigger type, and trigger request ID. + +[role="screenshot"] +image::./images/lambda-cold-start-trace.png[lambda cold start trace] + +[float] +[[apm-lambda-cold-start-latency]] +===== Latency distribution correlation + +The <<correlations-latency,latency correlations>> feature can be used to visualize the impact of Lambda cold starts on latency--just select the `faas.coldstart` field. + +[role="screenshot"] +image::./images/lambda-correlations.png[lambda correlations example] + +[float] +[[apm-lambda-service-config]] +==== 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. + +In some use cases, it makes more sense to logically group multiple lambda functions under a single +APM service. You can achieve this by setting the `ELASTIC_APM_SERVICE_NAME` environment variable +on related Lambda functions to the same value. diff --git a/docs/en/observability/apm-ui/logs.asciidoc b/docs/en/observability/apm-ui/logs.asciidoc new file mode 100644 index 0000000000..879ba8fa0e --- /dev/null +++ b/docs/en/observability/apm-ui/logs.asciidoc @@ -0,0 +1,18 @@ +[[apm-logs]] +=== Logs + +The *Logs* tab shows contextual logs for the selected service. + +// tag::log-overview[] +Logs provide detailed information about specific events, and are crucial to successfully debugging slow or erroneous transactions. + +If you've correlated your application's logs and traces, you never have to search for relevant data; it's already available to you. Viewing log and trace data together allows you to quickly diagnose and solve problems. + +To learn how to correlate your logs with your instrumented services, +see {observability-guide}/application-logs.html[log correlation] +// end::log-overview[] + +[role="screenshot"] +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` diff --git a/docs/en/observability/apm-ui/machine-learning.asciidoc b/docs/en/observability/apm-ui/machine-learning.asciidoc new file mode 100644 index 0000000000..adfff00d5c --- /dev/null +++ b/docs/en/observability/apm-ui/machine-learning.asciidoc @@ -0,0 +1,72 @@ +[[apm-machine-learning-integration]] +=== Machine learning integration + +++++ +<titleabbrev>Integrate with machine learning</titleabbrev> +++++ + +The Machine learning integration initiates a new job predefined to calculate anomaly scores on APM transaction durations. +With this integration, you can quickly pinpoint anomalous transactions and see the health of +any upstream and downstream services. + +Machine learning jobs are created per environment and are based on a service's average response time. +Because jobs are created at the environment level, +you can add new services to your existing environments without the need for additional machine learning jobs. + +Results from machine learning jobs are shown in multiple places throughout the APM UI: + +* The **Services overview** provides a quick-glance view of the general health of all of your services. ++ +[role="screenshot"] +image::./images/service-quick-health.png[Example view of anomaly scores on response times in the APM UI] + +* The transaction duration chart will show the expected bounds and add an annotation when the anomaly score is 75 or above. ++ +[role="screenshot"] +image::./images/apm-ml-integration.png[Example view of anomaly scores on response times in the APM UI] + +* Service Maps will display a color-coded anomaly indicator based on the detected anomaly score. ++ +[role="screenshot"] +image::./images/apm-service-map-anomaly.png[Example view of anomaly scores on service maps in the APM UI] + +[float] +[[create-ml-integration]] +=== Enable anomaly detection + +To enable machine learning anomaly detection: + +. From the Services overview, Traces overview, or Service Map tab, +select **Anomaly detection**. + +. Click **Create Job**. + +. Machine learning jobs are created at the environment level. +Select all of the service environments that you want to enable anomaly detection in. +Anomalies will surface for all services and transaction types within the selected environments. + +. Click **Create Jobs**. + +That's it! After a few minutes, the job will begin calculating results; +it might take additional time for results to appear on your service maps. +To manage existing jobs, click **Manage jobs**. + +[float] +[[warning-ml-integration]] +=== 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. + +[role="screenshot"] +image::./images/apm-anomaly-alert.png[Example view of anomaly alert in the APM UI] + +[float] +[[unkown-ml-integration]] +=== Unknown service health + +After enabling anomaly detection, service health may display as "Unknown". Here are some reasons why this can occur: + +1. No machine learning job exists. See <<create-ml-integration>> to enable anomaly detection and create a machine learning job. +2. There is no machine learning data for the job. If you just created the machine learning job you'll need to wait a few minutes for data to be available. Alternatively, if the service or its enviroment are new, you'll need to wait for more trace data. +3. No "request" or "page-load" transaction type exists for this service; service health is only available for these transaction types. diff --git a/docs/en/observability/apm-ui/metrics.asciidoc b/docs/en/observability/apm-ui/metrics.asciidoc new file mode 100644 index 0000000000..987581c9d0 --- /dev/null +++ b/docs/en/observability/apm-ui/metrics.asciidoc @@ -0,0 +1,23 @@ +[[apm-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. + +If you're experiencing a problem with your service, you can use this page to attempt to find the underlying cause. +For example, you might be able to correlate a high number of errors with a long transaction duration, high CPU usage, or a memory leak. + +[role="screenshot"] +image::./images/apm-metrics.png[Example view of the Metrics overview in APM UI in Kibana] + +If you're using the Java APM agent, you can view metrics for each JVM. + +[role="screenshot"] +image::./images/jvm-metrics-overview.png[Example view of the Metrics overview for the Java Agent] + +Breaking down metrics by JVM makes it much easier to analyze the provided metrics: +CPU usage, memory usage, heap or non-heap memory, +thread count, garbage collection rate, and garbage collection time spent per minute. + +[role="screenshot"] +image::./images/jvm-metrics.png[Example view of the Metrics overview for the Java Agent] diff --git a/docs/en/observability/apm-ui/mobile-errors.asciidoc b/docs/en/observability/apm-ui/mobile-errors.asciidoc new file mode 100644 index 0000000000..04e48b25b2 --- /dev/null +++ b/docs/en/observability/apm-ui/mobile-errors.asciidoc @@ -0,0 +1,35 @@ +[[mobile-errors-crashes]] +=== Mobile errors and crashes + +TIP: {apm-guide-ref}/data-model-errors.html[Errors] are groups of exceptions with a similar exception or log message. + +The *Errors & Crashes* overview provides a high-level view of errors and crashes that APM mobile agents catch, +or that users manually report with APM agent APIs. Errors and crashes are separated into two tabs for easy differentiation. +Like errors are grouped together to make it easy to quickly see which errors are affecting your services, +and to take actions to rectify them. + + + + + +[role="screenshot"] +image::./images/mobile-errors-overview.png[Mobile Errors overview] + +Selecting an error group ID or error message brings you to the *Error group*. + +[role="screenshot"] +image::./images/mobile-error-group.png[Mobile Error group] + +The error group details page visualizes the number of error occurrences over time and compared to a recent time range. +This allows you to quickly determine if the error rate is changing or remaining constant. +You'll also see the "most affected" chart which can be oriented to 'by device' or 'by app version'. + +Further down, you'll see an Error sample. +The error shown is always the most recent to occur. +The sample includes the exception message, culprit, stack trace where the error occurred (when available), +and additional contextual information to help debug the issue--all of which can be copied with the click of a button. + +In some cases, you might also see a Transaction sample ID. +This feature allows you to make a connection between the errors and transactions, +by linking you to the specific transaction where the error occurred. +This allows you to see the whole trace, including which services the request went through. diff --git a/docs/en/observability/apm-ui/mobile-service.asciidoc b/docs/en/observability/apm-ui/mobile-service.asciidoc new file mode 100644 index 0000000000..b1d7352429 --- /dev/null +++ b/docs/en/observability/apm-ui/mobile-service.asciidoc @@ -0,0 +1,60 @@ +[[apm-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 +high-level visibility into how a mobile service is performing for your users--enabling you +to make data-driven decisions about how to improve your user experience. + +For example, see: + +* Crash Rate (Crashes per session) +* Slowest App load time -- coming soon +* Number of sessions +* Number of HTTP requests +* Map showing the total number of HTTP requests based on country and region +* Most used devices, network connection type, OS version, and app version +* Latency, throughput, and errors over time +* Service dependencies + +All of these metrics & insights can help SREs and developers better understand the health +of their mobile application environment and the impact of backend errors and bottlenecks on end-user experience. + +[discrete] +[[mobile-service-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. + +Note: due to the way crash rate is calculated (crashes per session) it is possible to have greater than 100% rate, due to fact that a session may contain multiple crashes. + +[role="screenshot"] +image::./images/mobile-location.png[mobile service overview centered on location map] + +[discrete] +[[mobile-service-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. + +[role="screenshot"] +image::./images/mobile-most-used.png[mobile service overview showing most used devices, network, OS, and app version] + + +[discrete] +[[mobile-throughput-transactions]] +=== Throughput and transactions + +include::./service-overview.asciidoc[tag=throughput-transactions] + +[discrete] +[[mobile-error-and-dependencies]] +=== Failed transaction rate and dependencies + +include::./service-overview.asciidoc[tag=ftr] + +include::./service-overview.asciidoc[tag=dependencies] + +[role="screenshot"] +image::./images/mobile-tp.png[mobile service overview showing latency, throughput, and errors] \ No newline at end of file diff --git a/docs/en/observability/apm-ui/mobile-session-explorer.asciidoc b/docs/en/observability/apm-ui/mobile-session-explorer.asciidoc new file mode 100644 index 0000000000..dc1a2fb8cb --- /dev/null +++ b/docs/en/observability/apm-ui/mobile-session-explorer.asciidoc @@ -0,0 +1,41 @@ +[[apm-mobile-session-explorer]] +=== 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 + +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. + +The steps to follow are: + +* copy the `session.id` from the relevant document. +* Open the Discover page. +* Select the appropriate data view (use `APM` to search all datastreams) +* set filter to the copied `session.id` + +Here we can see the `session.id` guid in the metadata viewer in the error detail view: +[role="screenshot"] +image::images/mobile-session-error-details.png[Example of session.id in error details] + +Copy this value and open the Discover page: + +[role="screenshot"] +image::images/mobile-session-explorer-nav.png[Example view of navigation to Discover] + + +set the data view. `APM` selected in the example: + +[role="screenshot"] +image::images/mobile-session-explorer-apm.png[Example view of Explorer selecting APM data view] + +filter using the `session.id`: `session.id: "<copied session id guid>"`: + +[role="screenshot"] +image::images/mobile-session-filter-discover.png[Filter Explor using session.id] + +explore all the documents associated with that session id including crashes, lifecycle events, network requests, errors, and other custom events! diff --git a/docs/en/observability/apm-ui/service-maps.asciidoc b/docs/en/observability/apm-ui/service-maps.asciidoc new file mode 100644 index 0000000000..84f1cb7dd4 --- /dev/null +++ b/docs/en/observability/apm-ui/service-maps.asciidoc @@ -0,0 +1,117 @@ +[[apm-service-maps]] +=== 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, +requests per minute, and errors per minute. +If enabled, service maps also integrate with machine learning--for real time health indicators based on anomaly detection scores. +All of these features can help you quickly and visually assess your services' status and health. + +// Conditionally display a screenshot or video depending on what the +// current documentation version is. + +ifeval::["{is-current-version}"=="true"] +++++ +<script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script> +<img + style="width: 100%; margin: auto; display: block;" + class="vidyard-player-embed" + src="https://play.vidyard.com/VH8gKnPE3Z2csACZTCeQrw.jpg" + data-uuid="VH8gKnPE3Z2csACZTCeQrw" + data-v="4" + data-type="inline" +/> +</br> +++++ +endif::[] + +ifeval::["{is-current-version}"=="false"] +[role="screenshot"] +image::./images/service-maps.png[Example view of service maps in the APM UI in Kibana] +endif::[] + +We currently surface two types of service maps: + +* Global: All services instrumented with APM agents and the connections between them are shown. +* Service-specific: Highlight connections for a selected service. + +[float] +[[service-maps-how]] +=== 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. +However, if a service isn't instrumented, +or a `traceparent` header isn't being propagated to it, +distributed tracing will not work, and the connection will not be drawn on the map. + +[float] +[[visualize-your-architecture]] +=== Visualize your architecture + +Select the **Service Map** tab to get started. +By default, all instrumented services and connections are shown. +Whether you're onboarding a new engineer, or just trying to grasp the big picture, +drag things around, zoom in and out, and begin to visualize how your services are connected. + +Customize what the service map displays using either the query bar or the environment selector. +The query bar enables you to use <<apm-advanced-queries,advanced queries>> to customize the service map based on your needs. +The environment selector allows you to narrow displayed results to a specific environment. +This can be useful if you have two or more services, in separate environments, but with the same name. +Use the environment drop-down to only see the data you're interested in, like `dev` or `production`. + +If there's a specific service that interests you, select that service to highlight its connections. +Click **Focus map** to refocus the map on the selected service and lock the connection highlighting. +From here, select **Service Details**, or click the **Transactions** tab to jump to the Transaction overview for the selected service. +You can also use the tabs at the top of the page to easily jump to the **Errors** or **Metrics** overview. + +[role="screenshot"] +image::./images/service-maps-java.png[Example view of service maps in the APM UI in Kibana] + +[float] +[[service-map-anomaly-detection]] +=== 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: + +[horizontal] +image:./images/green-service.png[APM green service]:: Max anomaly score **≤25**. Service is healthy. +image:./images/yellow-service.png[APM yellow service]:: Max anomaly score **26-74**. Anomalous activity detected. Service may be degraded. +image:./images/red-service.png[APM red service]:: Max anomaly score **≥75**. Anomalous activity detected. Service is unhealthy. + +[role="screenshot"] +image::./images/apm-service-map-anomaly.png[Example view of anomaly scores on service maps in the APM UI] + +If an anomaly has been detected, click *View anomalies* to view the anomaly detection metric viewer in the Machine learning app. +This time series analysis will display additional details on the severity and time of the detected anomalies. + +To learn how to create a machine learning job, see <<apm-machine-learning-integration,machine learning integration>>. + +[float] +[[service-maps-legend]] +=== Legend + +Nodes appear on the map in one of two shapes: + +* **Circle**: Instrumented services. Interior icons are based on the language of the APM agent used. +* **Diamond**: Databases, external, and messaging. Interior icons represent the generic type, +with specific icons for known entities, like Elasticsearch. +Type and subtype are based on `span.type`, and `span.subtype`. + +[float] +[[service-maps-supported]] +=== Supported APM agents + +Service Maps are supported for the following APM agent versions: + +[horizontal] +Go agent:: ≥ v1.7.0 +iOS agent:: _Not yet supported_ +Java agent:: ≥ v1.13.0 +.NET agent:: ≥ v1.3.0 +Node.js agent:: ≥ v3.6.0 +PHP agent:: ≥ v1.2.0 +Python agent:: ≥ v5.5.0 +Ruby agent:: ≥ v3.6.0 +Real User Monitoring (RUM) agent:: ≥ v4.7.0 diff --git a/docs/en/observability/apm-ui/service-overview.asciidoc b/docs/en/observability/apm-ui/service-overview.asciidoc new file mode 100644 index 0000000000..2d8602bff4 --- /dev/null +++ b/docs/en/observability/apm-ui/service-overview.asciidoc @@ -0,0 +1,192 @@ +[[apm-service-overview]] +=== Service overview + +Selecting a non-mobile <<apm-services,*service*>> brings you to the *Service overview*. +The *Service overview* contains a wide variety of charts and tables that provide +high-level visibility into how a service is performing across your infrastructure: + +* Service details like service version, runtime version, framework, and APM agent name and version +* Container and orchestration information +* Cloud provider, machine type, service name, region, and availability zone +* Serverless function names and event trigger type +* Latency, throughput, and errors over time +* Service dependencies + +[discrete] +[[service-time-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 +corresponding {anomaly-job}. For example, has latency been slowly increasing +over time, did the service experience a sudden spike, is the throughput similar +to what the {ml} job expects – enabling a comparison can provide the answer. + +[role="screenshot"] +image::./images/time-series-expected-bounds-comparison.png[Time series and expected bounds comparison] + +Select the *Comparison* box to apply a time-based or expected bounds comparison. +The time-based comparison options are based on the selected time filter range: + +[options="header"] +|==== +|Time filter | Time comparison options + +|≤ 24 hours +|One day or one week + +|> 24 hours and ≤ 7 days +|One week + +|> 7 days +|An identical amount of time immediately before the selected time range +|==== + +You can use the expected bounds comparison if {ml-jobs} exist in your selected +environment and you have +{ml-docs}/setup.html#kib-visibility-spaces[access to the {ml-features}]. + +[discrete] +[[service-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. + +[role="screenshot"] +image::./images/latency.png[Service latency] + +[discrete] +[[service-throughput-transactions]] +=== Throughput and transactions + +// tag::throughput-transactions[] +The *Throughput* chart visualizes the average number of transactions per minute for the selected service. + +The *Transactions* table displays a list of _transaction groups_ for the +selected service and includes the latency, traffic, error rate, and the impact for each transaction. +Transactions that share the same name are grouped, and only one entry is displayed for each group. + +By default, transaction groups are sorted by _Impact_ to show the most used and slowest endpoints in your +service. If there is a particular endpoint you are interested in, click *View transactions* to view a +list of similar transactions on the <<apm-transactions, transactions overview>> page. + +[role="screenshot"] +image::./images/traffic-transactions.png[Traffic and transactions] +// end::throughput-transactions[] + +[discrete] +[[service-error-rates]] +=== Failed transaction rate and errors + +// tag::ftr[] +The failed transaction rate represents the percentage of failed transactions from the perspective of the selected service. +It's useful for visualizing unexpected increases, decreases, or irregular patterns in a service's transactions. + +[TIP] +==== +HTTP **transactions** from the HTTP server perspective do not consider a `4xx` status code (client error) as a failure +because the failure was caused by the caller, not the HTTP server. Thus, `event.outcome=success` and there will be no increase in failed transaction rate. + +HTTP **spans** from the client perspective however, are considered failures if the HTTP status code is ≥ 400. +These spans will set `event.outcome=failure` and increase the failed transaction rate. + +If there is no HTTP status, both transactions and spans are considered successful unless an error is reported. +==== +// end::ftr[] + +The *Errors* table provides a high-level view of each error message when it first and last occurred, +along with the total number of occurrences. This makes it very easy to quickly see which errors affect +your services and take actions to rectify them. To do so, click *View errors*. + +[role="screenshot"] +image::./images/error-rate.png[failed transaction rate and errors] + +[discrete] +[[service-span-duration]] +=== 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 +chart indicates that something was happening within the application. This could signal that the APM +agent does not have auto-instrumentation for whatever was happening during that time or that the time was spent in the +application code and not in database or external requests. + +// tag::dependencies[] +The *Dependencies* table displays a list of downstream services or external connections relevant +to the service at the selected time range. The table displays latency, throughput, failed transaction rate, and the impact of +each dependency. By default, dependencies are sorted by _Impact_ to show the most used and the slowest dependency. +If there is a particular dependency you are interested in, click *<<apm-dependencies,View dependencies>>* to learn more about it. + +NOTE: Displaying dependencies for services instrumented with the Real User Monitoring (RUM) agent +requires an agent version ≥ v5.6.3. + +[role="screenshot"] +image::./images/spans-dependencies.png[Span type duration and dependencies] +// end::dependencies[] + +[discrete] +[[service-cold-start]] +=== 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. +A cold start occurs when a serverless function has not been used for a certain period of time. +Analyzing the cold start rate can be useful for deciding how much memory to allocate to a function, +or when to remove a large dependency. + +The cold start rate chart is currently supported for <<apm-lambda-cold-start-info,AWS Lambda>> +functions and Azure functions. + +[discrete] +[[service-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, +failed transaction, CPU usage, and memory usage for each instance. By default, instances are sorted by _Throughput_. + +[role="screenshot"] +image::./images/all-instances.png[All instances] + +[discrete] +[[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. + +[role="screenshot"] +image::./images/metadata-icons.png[Service metadata] + +*Service information* + +* Service version +* Runtime name and version +* Framework name +* APM agent name and version + +*Container information* + +* Operating system +* Containerized - Yes or no. +* Total number of instances +* Orchestration + +*Cloud provider information* + +* Cloud provider +* Cloud service name +* Availability zones +* Machine types +* Project ID +* Region + +*Serverless information* + +* Function name(s) +* Event trigger type + +*Alerts* + +* Recently fired alerts diff --git a/docs/en/observability/apm-ui/services.asciidoc b/docs/en/observability/apm-ui/services.asciidoc new file mode 100644 index 0000000000..16a8fae1e7 --- /dev/null +++ b/docs/en/observability/apm-ui/services.asciidoc @@ -0,0 +1,60 @@ +[[apm-services]] +=== Services + +*Service* inventory provides a quick, high-level overview of the health and general +performance of all instrumented services. + +To help surface potential issues, services are sorted by their health status: +**critical** > **warning** > **healthy** > **unknown**. +Health status is powered by <<apm-machine-learning-integration,machine learning>> +and requires anomaly detection to be enabled. + +In addition to health status, active alerts for each service are prominently displayed in the service inventory table. Selecting an active alert badge brings you to the <<apm-alerts,Alerts>> tab where you can learn more about the active alert and take action. + +[role="screenshot"] +image::./images/apm-services-overview.png[Example view of services table the APM UI in Kibana] + +[float] +[[service-groups]] +==== Service groups + +beta::[] + +Group services together to build meaningful views that remove noise, simplify investigations across services, +and <<apm-alert-view-group,combine related alerts>>. +Service groups are {kib} space-specific and available for any users with appropriate access. + +// This screenshot is reused in the alerts docs +// Ensure it has an active alert showing +[role="screenshot"] +image::./images/apm-service-group.png[Example view of service group in the APM UI in Kibana] + +To enable Service groups, open {kib} and navigate to **Stack Management** > **Advanced Settings** > **Observability**, +and enable the **Service groups feature**. + +To create a service group: + +. Navigate to **Observability** > **APM** > **Services**. +. Switch to **Service groups**. +. Click **Create group**. +. Specify a name, color, and description. +. Click **Select services**. +. Specify a {kibana-ref}/kuery-query.html[{kib} Query Language (KQL)] query to select services for the group. +Services that match the query within the last 24 hours will be assigned to the group. + +[NOTE] +==== +Once a service group has been saved, this list of services within it is static. +If a newly added service matches the KQL query, it will not be automatically added to the service group. +Similarly, if a service stops matching the KQL query, it will not be removed from the group. + +To update the list of services within a group, +edit the service group, click **Refresh** next to the KQL query, and click **Save group**. +==== + +**Examples** + +Not sure where to get started? Here are some sample queries you can build from: + +* Group services by environment--in this example, "production": `service.environment : "production"` +* Group services by name--this example groups those that end in "beat": `service.name : *beat` (matches services named "Auditbeat", "Heartbeat", "Filebeat", etc.) diff --git a/docs/en/observability/apm-ui/settings.asciidoc b/docs/en/observability/apm-ui/settings.asciidoc new file mode 100644 index 0000000000..e678768fcb --- /dev/null +++ b/docs/en/observability/apm-ui/settings.asciidoc @@ -0,0 +1,32 @@ +[[apm-settings-in-kibana]] +== APM UI settings + +++++ +<titleabbrev>Settings</titleabbrev> +++++ + +You do not need to configure any settings to use the APM UI. It is enabled by default. +If you'd like to adjust the default settings, see {kibana-ref}/apm-settings-kb.html[APM Settings]. + +[float] +[[apm-indices-settings]] +=== 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**. +Index settings in the APM UI take precedence over those set in `kibana.yml`. + +APM indices are {kib} Spaces-aware; +Changes to APM index settings will only apply to the currently enabled space. +See <<apm-spaces>> for more information. + +[float] +[[apm-labs]] +=== APM Labs + +**APM Labs** allows you to easily try out new features that are technical preview. + +To enable APM labs, navigate to **APM** > **Settings** > **General settings** and toggle **Enable labs button in APM**. +Select **Save changes** and refresh the page. + +After enabling **APM Labs** select **Labs** in the toolbar to see the technical preview features available to try out. diff --git a/docs/en/observability/apm-ui/spans.asciidoc b/docs/en/observability/apm-ui/spans.asciidoc new file mode 100644 index 0000000000..495cb5c3f9 --- /dev/null +++ b/docs/en/observability/apm-ui/spans.asciidoc @@ -0,0 +1,72 @@ +[[apm-spans]] +=== 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. + +[role="screenshot"] +image::./images/apm-transaction-sample.png[Example of distributed trace colors in the APM UI in Kibana] + +View a span in detail by clicking on it in the timeline waterfall. +For example, when you click on an SQL Select database query, +the information displayed includes the actual SQL that was executed, how long it took, +and the percentage of the trace's total time. +You also get a stack trace, which shows the SQL query in your code. +Finally, APM knows which files are your code and which are just modules or libraries that you've installed. +These library frames will be minimized by default in order to show you the most relevant stack trace. + +TIP: A {apm-guide-ref}/data-model-spans.html[span] is the duration of a single event. +Spans are automatically captured by APM agents, and you can also define custom spans. +Each span has a type and is defined by a different color in the timeline/waterfall visualization. + +[role="screenshot"] +image::./images/apm-span-detail.png[Example view of a span detail in the APM UI in Kibana] + +[float] +[[trace-sample-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. +For example, quickly view: + +* logs and metrics for the selected pod +* logs and metrics for the selected host +* trace logs for the selected `trace.id` +* uptime status of the selected domain +* the <<apm-service-maps,service map>> filtered by the selected trace +* the selected transaction in Discover +* your <<apm-custom-links,custom links>> + +[float] +[[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 +are listed in the order they occur. + +[role="screenshot"] +image::./images/apm-services-trace.png[Example of distributed trace colors in the APM UI in Kibana] + +As application architectures are shifting from monolithic to more distributed, service-based architectures, +distributed tracing has become a crucial feature of modern application performance monitoring. +It allows you to trace requests through your service architecture automatically, and visualize those traces in one single view in the APM UI. +From initial web requests to your front-end service, to queries made to your back-end services, +this makes finding possible bottlenecks throughout your application much easier and faster. + +[role="screenshot"] +image::./images/apm-distributed-tracing.png[Example view of the distributed tracing in APM UI in Kibana] + +Don't forget; by definition, a distributed trace includes more than one transaction. +When viewing distributed traces in the timeline waterfall, +you'll see this icon: image:./images/transaction-icon.png[APM icon], +which indicates the next transaction in the trace. +For easier problem isolation, transactions can be collapsed in the waterfall by clicking +the icon to the left of the transactions. +Transactions can also be expanded and viewed in detail by clicking on them. + +After exploring these traces, +you can return to the full trace by clicking *View full trace*. + +TIP: Distributed tracing is supported by all APM agents, and there's no additional configuration needed. diff --git a/docs/en/observability/apm-ui/storage-explorer.asciidoc b/docs/en/observability/apm-ui/storage-explorer.asciidoc new file mode 100644 index 0000000000..c43af9f37f --- /dev/null +++ b/docs/en/observability/apm-ui/storage-explorer.asciidoc @@ -0,0 +1,91 @@ +[[apm-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 +large amounts of data--then change the sample rate of a service to lower the amount of data ingested. +Or, expand the time filter to visualize data trends over time so that you can better forecast +and prepare for future storage needs. + +[role="screenshot"] +image::./images/storage-explorer-overview.png[APM Storage Explorer] + +[float] +==== 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. +Use the **Index lifecycle phase** dropdown to visualize and analyze your storage by phase. + +Customizing the default APM index lifecycle policies can save money by specifying things like: + +* The point at which an index can be moved to less performant hardware. +* The point at which availability is not as critical and the number of replicas can be reduced. +* When the index can be safely deleted. + +See {apm-guide-ref}/ilm-how-to.html[Index lifecycle management] to learn more about customizing +the default APM index lifecycle policies. + +[float] +==== 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 + +The service statistics table provides detailed information on each service: + +* A list of **service environments**. +* The **sampling rate**. This value is calculated by dividing the number of sampled transactions by total throughput. +It might differ from the configured sampling rate for two reasons: with head-based sampling, +the initial service makes the sampling decision, and with tail-based sampling, +granular policies allow you to set multiple sample rates. +* The estimated **size on disk**. This storage size includes both primary and replica shards and is +calculated by prorating the total size of your indices by the service's document count divided by +the total number of documents. +* Number of **transactions**, **spans**, **errors**, and **metrics** — doc count and size on disk. + +[role="screenshot"] +image::./images/storage-explorer-expanded.png[APM Storage Explorer service breakdown] + +As you explore your service statistics, you might want to take action to reduce the number of +documents and therefore storage size of a particular service. + +[float] +===== 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 +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 +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. +Or, you can set the **metrics interval** to zero seconds to deactivate metrics entirely. +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 +To reduce the number of errors a service generate, +work with your developers to change how exceptions are handled in your code. + +[float] +==== Privileges + +Storage Explorer requires expanded privileges to view. +See <<apm-app-storage-explorer-user-create>> for more information. + +[float] +==== Limitations + +Multi-cluster deployments are not supported. diff --git a/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/content.asciidoc b/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/content.asciidoc new file mode 100644 index 0000000000..6b9c996035 --- /dev/null +++ b/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/content.asciidoc @@ -0,0 +1,45 @@ +// tag::classic-indices[] +[options="header"] +|==== +|Type |Privilege |Purpose + +|Index +|`read` on `apm-*` +|Read-only access to `apm-*` data + +|Index +|`view_index_metadata` on `apm-*` +|Read-only access to `apm-*` index metadata +|==== +// end::classic-indices[] + +// tag::data-streams[] +[options="header"] +|==== +|Type |Privilege |Purpose + +|Index +|`read` on `logs-apm*` +|Read-only access to `logs-apm*` data + +|Index +|`view_index_metadata` on `logs-apm*` +|Read-only access to `logs-apm*` index metadata + +|Index +|`read` on `metrics-apm*` +|Read-only access to `metrics-apm*` data + +|Index +|`view_index_metadata` on `metrics-apm*` +|Read-only access to `metrics-apm*` index metadata + +|Index +|`read` on `traces-apm*` +|Read-only access to `traces-apm*` data + +|Index +|`view_index_metadata` on `traces-apm*` +|Read-only access to `traces-apm*` index metadata +|==== +// end::data-streams[] diff --git a/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/widget.asciidoc b/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/widget.asciidoc new file mode 100644 index 0000000000..bdffa20980 --- /dev/null +++ b/docs/en/observability/apm-ui/tab-widgets/apm-app-reader/widget.asciidoc @@ -0,0 +1,40 @@ +++++ +<div class="tabs" data-tab-group="apm-app-reader"> + <div role="tablist" aria-label="APM UI reader"> + <button role="tab" + aria-selected="true" + aria-controls="data-streams-tab" + id="data-streams"> + Data streams + </button> + <button role="tab" + aria-selected="false" + aria-controls="classic-indices-tab" + id="classic-indices" + tabindex="-1"> + Classic APM indices + </button> + </div> + <div tabindex="0" + role="tabpanel" + id="data-streams-tab" + aria-labelledby="data-streams"> +++++ + +include::content.asciidoc[tag=data-streams] + +++++ + </div> + <div tabindex="0" + role="tabpanel" + id="classic-indices-tab" + aria-labelledby="classic-indices" + hidden=""> +++++ + +include::content.asciidoc[tag=classic-indices] + +++++ + </div> +</div> +++++ \ No newline at end of file diff --git a/docs/en/observability/apm-ui/tab-widgets/central-config-users/content.asciidoc b/docs/en/observability/apm-ui/tab-widgets/central-config-users/content.asciidoc new file mode 100644 index 0000000000..0945050d9a --- /dev/null +++ b/docs/en/observability/apm-ui/tab-widgets/central-config-users/content.asciidoc @@ -0,0 +1,53 @@ +// tag::classic-indices[] +[options="header"] +|==== +|Type |Privilege |Purpose + +|Index +|`read` on `apm-*` +|Read-only access to `apm-*` data + +|Index +|`view_index_metadata` on `apm-*` +|Read-only access to `apm-*` index metadata +|==== +// end::classic-indices[] + +// tag::data-streams[] +[options="header"] +|==== +|Type |Privilege |Purpose + +|Index +|`read` on `apm-agent-configuration` +|Read-only access to `apm-agent-configuration` data + +|Index +|`view_index_metadata` on `apm-agent-configuration` +|Read-only access to `apm-agent-configuration` index metadata + +|Index +|`read` on `logs-apm*` +|Read-only access to `logs-apm*` data + +|Index +|`view_index_metadata` on `logs-apm*` +|Read-only access to `logs-apm*` index metadata + +|Index +|`read` on `metrics-apm*` +|Read-only access to `metrics-apm*` data + +|Index +|`view_index_metadata` on `metrics-apm*` +|Read-only access to `metrics-apm*` index metadata + +|Index +|`read` on `traces-apm*` +|Read-only access to `traces-apm*` data + +|Index +|`view_index_metadata` on `traces-apm*` +|Read-only access to `traces-apm*` index metadata +|==== +// end::data-streams[] diff --git a/docs/en/observability/apm-ui/tab-widgets/central-config-users/widget.asciidoc b/docs/en/observability/apm-ui/tab-widgets/central-config-users/widget.asciidoc new file mode 100644 index 0000000000..586a3515a7 --- /dev/null +++ b/docs/en/observability/apm-ui/tab-widgets/central-config-users/widget.asciidoc @@ -0,0 +1,40 @@ +++++ +<div class="tabs" data-tab-group="central-config-manager"> + <div role="tablist" aria-label="Central config manager"> + <button role="tab" + aria-selected="true" + aria-controls="data-streams-tab" + id="data-streams"> + Data streams + </button> + <button role="tab" + aria-selected="false" + aria-controls="classic-indices-tab" + id="classic-indices" + tabindex="-1"> + Classic APM indices + </button> + </div> + <div tabindex="0" + role="tabpanel" + id="data-streams-tab" + aria-labelledby="data-streams"> +++++ + +include::content.asciidoc[tag=data-streams] + +++++ + </div> + <div tabindex="0" + role="tabpanel" + id="classic-indices-tab" + aria-labelledby="classic-indices" + hidden=""> +++++ + +include::content.asciidoc[tag=classic-indices] + +++++ + </div> +</div> +++++ \ No newline at end of file diff --git a/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/content.asciidoc b/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/content.asciidoc new file mode 100644 index 0000000000..8661be8d3b --- /dev/null +++ b/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/content.asciidoc @@ -0,0 +1,37 @@ +// tag::classic-indices[] +[options="header"] +|==== +|Type |Privilege |Purpose + +|Cluster +|`monitor` +|Monitor the disk space used by APM indices + +|Index +|`monitor` on `apm-*` +|Monitor access to `apm-*` for storage explorer +|==== +// end::classic-indices[] + +// tag::data-streams[] +[options="header"] +|==== +|Type |Privilege |Purpose + +|Cluster +|`monitor` +|Monitor the disk space used by APM data streams + +|Index +|`monitor` on `logs-apm*` +|Monitor access to `logs-apm*` for storage explorer + +|Index +|`monitor` on `metrics-apm*` +|Monitor access to `metrics-apm*` for storage explorer + +|Index +|`monitor` on `traces-apm*` +|Monitor access to `traces-apm*` for storage explorer +|==== +// end::data-streams[] diff --git a/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/widget.asciidoc b/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/widget.asciidoc new file mode 100644 index 0000000000..e10fce9e8e --- /dev/null +++ b/docs/en/observability/apm-ui/tab-widgets/storage-explorer-user/widget.asciidoc @@ -0,0 +1,40 @@ +++++ +<div class="tabs" data-tab-group="apm-app-storage-explorer-reader"> + <div role="tablist" aria-label="APM UI storage explorer-reader"> + <button role="tab" + aria-selected="true" + aria-controls="data-streams-tab" + id="data-streams"> + Data streams + </button> + <button role="tab" + aria-selected="false" + aria-controls="classic-indices-tab" + id="classic-indices" + tabindex="-1"> + Classic APM indices + </button> + </div> + <div tabindex="0" + role="tabpanel" + id="data-streams-tab" + aria-labelledby="data-streams"> +++++ + +include::content.asciidoc[tag=data-streams] + +++++ + </div> + <div tabindex="0" + role="tabpanel" + id="classic-indices-tab" + aria-labelledby="classic-indices" + hidden=""> +++++ + +include::content.asciidoc[tag=classic-indices] + +++++ + </div> +</div> +++++ \ No newline at end of file diff --git a/docs/en/observability/apm-ui/traces.asciidoc b/docs/en/observability/apm-ui/traces.asciidoc new file mode 100644 index 0000000000..4a082198b5 --- /dev/null +++ b/docs/en/observability/apm-ui/traces.asciidoc @@ -0,0 +1,40 @@ +[[apm-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. +In addition to the Traces overview, you can view your application traces in the <<apm-spans,trace sample timeline waterfall>>. + +*Traces* displays your application's entry (root) transactions. +Transactions with the same name are grouped together and only shown once in this table. +If you're using <<distributed-tracing,distributed tracing>>, +this view is key to finding the critical paths within your application. + +By default, transactions are sorted by _Impact_. +Impact helps show the most used and slowest endpoints in your service -- in other words, +it's the collective amount of pain a specific endpoint is causing your users. +If there's a particular endpoint you're worried about, select it to view its +<<transaction-details,transaction details>>. + +You can also use queries to filter and search the transactions shown on this page. +Note that only properties available on root transactions are searchable. +For example, you can't search for `label.tier: 'high'`, as that field is only available on non-root transactions. + +[role="screenshot"] +image::./images/apm-traces.png[Example view of the Traces overview in APM UI in Kibana] + +[float] +[[trace-explorer]] +==== Trace explorer + +preview::[] + +**Trace explorer** is an experimental top-level search tool that allows you to query your traces using {kibana-ref}/kuery-query.html[{kib} Query Language (KQL)] or {ref}/eql.html[Event Query Language (EQL)]. + +Curate your own custom queries, or use the <<apm-service-maps,**Service Map**>> to find and select edges to automatically generate queries based on your selection: + +[role="screenshot"] +image::./images/trace-explorer.png[Trace explorer] + +// TODO: FIX THIS +// Enable **Trace explorer** in <<apm-labs,APM Labs>> or in <<observability-apm-trace-explorer-tab,{kib} advanced settings>>. diff --git a/docs/en/observability/apm-ui/transactions.asciidoc b/docs/en/observability/apm-ui/transactions.asciidoc new file mode 100644 index 0000000000..9a4a7c436b --- /dev/null +++ b/docs/en/observability/apm-ui/transactions.asciidoc @@ -0,0 +1,179 @@ +[[apm-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. + +[role="screenshot"] +image::./images/apm-transactions-overview.png[Example view of transactions table in the APM UI in Kibana] + +The *Latency*, *Throughput*, *Failed transaction rate*, *Time spent by span type*, and *Cold start rate* +charts display information on all transactions associated with the selected service: + +*Latency*:: +Response times for the service. Options include average, 95th, and 99th percentile. +If there's a weird spike that you'd like to investigate, +you can simply zoom in on the graph - this will adjust the specific time range, +and all of the data on the page will update accordingly. + +*Throughput*:: +Visualize response codes: `2xx`, `3xx`, `4xx`, etc. +Useful for determining if more responses than usual are being served with a particular response code. +Like in the latency graph, you can zoom in on anomalies to further investigate them. + +[[transaction-error-rate]] +*Failed transaction rate*:: +The failed transaction rate represents the percentage of failed transactions from the perspective of the selected service. +It's useful for visualizing unexpected increases, decreases, or irregular patterns in a service's transactions. ++ +[TIP] +==== +HTTP **transactions** from the HTTP server perspective do not consider a `4xx` status code (client error) as a failure +because the failure was caused by the caller, not the HTTP server. Thus, `event.outcome=success` and there will be no increase in failed transaction rate. + +HTTP **spans** from the client perspective however, are considered failures if the HTTP status code is ≥ 400. +These spans will set `event.outcome=failure` and increase the failed transaction rate. + +If there is no HTTP status, both transactions and spans are considered successful unless an error is reported. +==== + +*Time spent by span type*:: +Visualize where your application is spending most of its time. +For example, is your app spending time in external calls, database processing, or application code execution? ++ +The time a transaction took to complete is also recorded and displayed on the chart under the "app" label. +"app" indicates that something was happening within the application, but we're not sure exactly what. +This could be a sign that the APM agent does not have auto-instrumentation for whatever was happening during that time. ++ +It's important to note that if you have asynchronous spans, the sum of all span times may exceed the duration of the transaction. + +*Cold start rate*:: +Only applicable to serverless transactions, this chart displays the percentage of requests that trigger a cold start of a serverless function. +See <<apm-lambda-cold-start-info>> for more information. + +[discrete] +[[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, +and only displays one entry for each group. + +[role="screenshot"] +image::./images/apm-transactions-table.png[Example view of the transactions table in the APM UI in Kibana] + +By default, transaction groups are sorted by _Impact_. +Impact helps show the most used and slowest endpoints in your service - in other words, +it's the collective amount of pain a specific endpoint is causing your users. +If there's a particular endpoint you're worried about, you can click on it to view the <<transaction-details, transaction details>>. + +[IMPORTANT] +==== +If you only see one route in the Transactions table, or if you have transactions named "unknown route", +it could be a symptom that the APM agent either wasn't installed correctly or doesn't support your framework. + +For further details, including troubleshooting and custom implementation instructions, +refer to the documentation for each {apm-agents-ref}[APM Agent] you've implemented. +==== + +[discrete] +[[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: + +[role="screenshot"] +image::./images/apm-geo-ui.png[average page load duration distribution] + +Additional RUM goodies, like core vitals, and visitor breakdown by browser, location, and device, +are available in the Observability User Experience tab. +// To do +// Add link to the Observability UE docs when complete + +[discrete] +[[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 +the selected transaction group. + +[role="screenshot"] +image::./images/apm-transactions-overview.png[Example view of response time distribution] + +[discrete] +[[transaction-duration-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 +and indicates most of our requests were served quickly -- awesome! +The requests on the right are taking longer than average; we probably need to focus on them. + +[role="screenshot"] +image::./images/apm-transaction-duration-dist.png[Example view of latency distribution graph] + +Click and drag to select a latency duration _bucket_ to display up to 500 trace samples. + +[discrete] +[[transaction-trace-sample]] +==== Trace samples + +Trace samples are based on the _bucket_ selection in the *Latency distribution* chart; +update the samples by selecting a new _bucket_. +The number of requests per bucket is displayed when hovering over the graph, +and the selected bucket is highlighted to stand out. + +Each bucket presents up to ten trace samples in a *timeline*, trace sample *metadata*, +and any related *logs*. + +*Trace sample timeline* + +Each sample has a trace timeline waterfall that shows how a typical request in that bucket executed. +This waterfall is useful for understanding the parent/child hierarchy of transactions and spans, +and ultimately determining _why_ a request was slow. +For large waterfalls, expand problematic transactions and collapse well-performing ones +for easier problem isolation and troubleshooting. + +[role="screenshot"] +image::./images/apm-transaction-sample.png[Example view of transactions sample] + +NOTE: More information on timeline waterfalls is available in <<apm-spans, spans>>. + +*Trace sample metadata* + +Learn more about a trace sample in the *Metadata* tab: + +* Labels - Custom labels added by APM agents +* HTTP request/response information +* Host information +* Container information +* Service - The service/application runtime, APM agent, name, etc.. +* Process - The process id that served up the request. +* APM agent information +* URL +* User - Requires additional configuration, but allows you to see which user experienced the current transaction. +* FaaS information, like cold start, AWS request ID, trigger type, and trigger request ID + +TIP: All of this data is stored in documents in Elasticsearch. +This means you can select "Actions - View transaction in Discover" to see the actual Elasticsearch document under the discover tab. + +*Trace sample logs* + +The *Logs* tab displays logs related to the sampled trace. + +include::./logs.asciidoc[tag=log-overview] + +[role="screenshot"] +image::./images/apm-logs-tab.png[APM logs tab] + +[discrete] +[[transaction-latency-correlations]] +==== Correlations + +Correlations surface attributes of your data that are potentially correlated with high-latency or erroneous transactions. +To learn more, see <<apm-correlations>>. + +[role="screenshot"] +image::./images/correlations-hover.png[APM lattency correlations] diff --git a/docs/en/observability/apm-ui/troubleshooting.asciidoc b/docs/en/observability/apm-ui/troubleshooting.asciidoc new file mode 100644 index 0000000000..2dced7c1c2 --- /dev/null +++ b/docs/en/observability/apm-ui/troubleshooting.asciidoc @@ -0,0 +1,188 @@ +[[apm-app-troubleshooting]] +== Troubleshoot + +++++ +<titleabbrev>Troubleshoot</titleabbrev> +++++ + +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 + +* <<no-apm-data-found>> +* <<troubleshooting-too-many-transactions>> +* <<troubleshooting-unknown-route>> +* <<troubleshooting-fields-unsearchable>> +* <<service-map-rum-connections>> + +[float] +[[no-apm-data-found]] +=== No APM data found + +This section can help with any of the following: + +* Data isn't displaying in the APM UI +* Data isn't displaying in the APM UI after an upgrade +* You see a message like "No Services Found", +* You see errors like "Fielddata is disabled on text fields by default..." + +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**. + +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] +[[troubleshooting-too-many-transactions]] +=== 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. +In some cases though, like when using an APM agent's API to create custom transactions, +it is up to the user to define a pattern for transaction naming. +When transactions are named incorrectly, each unique URL can be associated with a unique transaction group—causing +an explosion in the number of transaction groups per service, and leading to inaccuracies in the APM UI. + +To fix a large number of unique transaction names, +you need to change how you are using the APM agent API to name your transactions. +To do this, ensure you are **not** naming based on parameters that can change. +For example, user ids, product ids, order numbers, query parameters, etc., +should be stripped away, and commonality should be found between your unique URLs. + +Let's look at an example from the RUM agent documentation. Here are a few URLs you might find on Elastic.co: + +[source,yml] +---- +// Blog Posts +https://www.elastic.co/blog/reflections-on-three-years-in-the-elastic-public-sector +https://www.elastic.co/blog/say-heya-to-the-elastic-search-awards +https://www.elastic.co/blog/and-the-winner-of-the-elasticon-2018-training-subscription-drawing-is + +// Documentation +https://www.elastic.co/guide/en/elastic-stack/current/index.html +https://www.elastic.co/guide/en/apm/get-started/current/index.html +https://www.elastic.co/guide/en/infrastructure/guide/current/index.html +---- + +These URLs, like most, include unique names. +If we named transactions based on each unique URL, we'd end up with the problem described above—a +very large number of different transaction names. +Instead, we should strip away the unique information and group our transactions based on common information. +In this case, that means naming all blog transactions, `/blog`, and all documentation transactions, `/guide`. + +If you feel like you'd be losing valuable information by following this naming convention, don't fret! +You can always add additional metadata to your transactions using {apm-guide-ref}/data-model-metadata.html#data-model-labels[labels] (indexed) or +{apm-guide-ref}/data-model-metadata.html#data-model-custom[custom context] (non-indexed). + +After ensuring you've correctly named your transactions, +you might still see errors in the APM UI related to transaction group limit reached: + +`The number of transaction groups has been reached. Current APM server capacity for handling unique transaction groups has been reached. There are at least X transactions missing in this list. Please decrease the number of transaction groups in your service or increase the memory allocated to APM server.` + +You will see this warning if an agent is creating too many transaction groups. This could indicate incorrect instrumentation which will have to be fixed in your application. Alternatively you can increase the memory of the APM server. + +`Number of transaction groups exceed the allowed maximum(1,000) that are displayed. The maximum number of transaction groups displayed in Kibana has been reached. Try narrowing down results by using the query bar..` + +You will see this warning if your results have more than `1000` unique transaction groups. Alternatively you can use the query bar to reduce the number of unique transaction groups in your results. + +**More information** + +While this can happen with any APM agent, it typically occurs with the RUM agent. +For more information on how to correctly set `transaction.name` in the RUM agent, +see {apm-rum-ref}/custom-transaction-name.html[custom initial page load transaction names]. + +The RUM agent can also set the `transaction.name` when observing for transaction events. +See {apm-rum-ref}/agent-api.html#observe[`apm.observe()`] for more information. + +If your problem is occurring in a different APM agent, the tips above still apply. +See the relevant {apm-agents-ref}[Agent API documentation] to adjust how you're naming your transactions. + +[float] +[[troubleshooting-unknown-route]] +=== Unknown route + +The <<apm-transactions,transaction overview>> will only display helpful information +when the transactions in your services are named correctly. +If you're seeing "GET unknown route" or "unknown route" in the APM UI, +it could be a sign that something isn't working as it should. + +Elastic APM agents come with built-in support for popular frameworks out-of-the-box. +This means, among other things, that the APM agent will try to automatically name HTTP requests. +As an example, the Node.js agent uses the route that handled the request, while the Java agent uses the Servlet name. + +"Unknown route" indicates that the APM agent can't determine what to name the request, +perhaps because the technology you're using isn't supported, the agent has been installed incorrectly, +or because something is happening to the request that the agent doesn't understand. + +To resolve this, you'll need to head over to the relevant {apm-agents-ref}[APM agent documentation]. +Specifically, view the agent's supported technologies page. +You can also use the agent's public API to manually set a name for the transaction. + +[float] +[[troubleshooting-fields-unsearchable]] +=== 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. +These templates, by default, enable and disable indexing on certain fields. + +As an example, some APM agents store cookie values in `http.request.cookies`. +Since `http.request` has disabled dynamic indexing, and `http.request.cookies` is not declared in a custom mapping, +the values in `http.request.cookies` are not indexed and thus not searchable. + +*Ensure an APM data view exists* +As a first step, you should ensure the correct data view exists. +In {kib}, go to *Stack Management* > *Data views*. +You should see the APM data view--the default is +`traces-apm*,apm-*,logs-apm*,apm-*,metrics-apm*,apm-*`. +If you don't, the data view doesn't exist. +To fix this, navigate to the APM UI in {kib} and select *Add data*. +In the APM tutorial, click *Load Kibana objects* to create the APM data view. + +If creating an APM data view doesn't solve the problem, +see <<no-apm-data-found>> for further troubleshooting. + +*Ensure a field is searchable* +There are two things you can do to if you'd like to ensure a field is searchable: + +1. Index your additional data as {apm-guide-ref}/data-model-metadata.html[labels] instead. +These are dynamic by default, which means they will be indexed and become searchable and aggregatable. + +2. Create a custom mapping for the field. +// link will be added in a later PR. +// docs will be added in https://github.com/elastic/apm-server/pull/6940 + +[float] +[[service-map-rum-connections]] +=== 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 +{apm-rum-ref}/distributed-tracing-guide.html[`distributedTracingOrigins`]. + + +This setting is necessary, for example, for cross-origin requests. +If you have a basic web application that provides data via an API on `localhost:4000`, +and serves HTML from `localhost:4001`, you'd need to set `distributedTracingOrigins: ['https://localhost:4000']` +to ensure the origin is monitored as a part of distributed tracing. +In other words, `distributedTracingOrigins` is consulted prior to the APM agent adding the +distributed tracing `traceparent` header to each request. diff --git a/docs/en/observability/apm.asciidoc b/docs/en/observability/apm.asciidoc index 9b8d686183..7c9c8f9b7a 100644 --- a/docs/en/observability/apm.asciidoc +++ b/docs/en/observability/apm.asciidoc @@ -30,7 +30,7 @@ database queries, calls to caches, external HTTP requests, and more. This makes it easy to pinpoint and fix performance problems quickly. [role="screenshot"] -image::images/apm-app-landing.png[{apm-app} in {kib}] +image::images/apm-app-landing.png[APM UI in {kib}] Elastic APM also automatically collects unhandled errors and exceptions. Errors are grouped based primarily on the stack trace, @@ -52,6 +52,8 @@ 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[] @@ -68,6 +70,8 @@ include::{observability-docs-root}/docs/en/observability/apm/monitor-apm-server. 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/upgrading.asciidoc[] diff --git a/docs/en/observability/apm/access-api-keys.asciidoc b/docs/en/observability/apm/access-api-keys.asciidoc index d8d4b28a7a..b120857c23 100644 --- a/docs/en/observability/apm/access-api-keys.asciidoc +++ b/docs/en/observability/apm/access-api-keys.asciidoc @@ -1,4 +1,3 @@ -[role="xpack"] [[apm-beats-api-keys]] === Grant access using API keys diff --git a/docs/en/observability/apm/api-config.asciidoc b/docs/en/observability/apm/api-config.asciidoc index 370f7edbc1..f98d464432 100644 --- a/docs/en/observability/apm/api-config.asciidoc +++ b/docs/en/observability/apm/api-config.asciidoc @@ -2,7 +2,7 @@ === 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 {kibana-ref}/agent-configuration.html[{apm-agent} configuration in {kib}]. +More information on this feature is available in <<apm-agent-configuration,{apm-agent} configuration in {kib}>>. [float] [[apm-api-config-endpoint]] diff --git a/docs/en/observability/apm/api-keys.asciidoc b/docs/en/observability/apm/api-keys.asciidoc index 03e63933bb..937f2c1179 100644 --- a/docs/en/observability/apm/api-keys.asciidoc +++ b/docs/en/observability/apm/api-keys.asciidoc @@ -11,7 +11,7 @@ as there is no way to prevent them from being publicly exposed. You can assign one or more unique privileges to each API key: * *Agent configuration* (`config_agent:read`): Required for agents to read -{kibana-ref}/agent-configuration.html[Agent configuration remotely]. +<<apm-agent-configuration,Agent configuration remotely>>. * *Ingest* (`event:write`): Required for ingesting agent events. To secure the communication between APM Agents and the APM Server with API keys, @@ -38,7 +38,7 @@ 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. -In addition, when creating an API key from the {apm-app}, +In addition, when creating an API key from the APM UI, you'll need the appropriate {kib} Space and Feature privileges. The example below uses the {kib} {kibana-ref}/role-management-api.html[role management API] @@ -72,10 +72,10 @@ Assign the newly created `apm_agent_key_role` role to any user that wishes to cr [[apm-create-an-api-key]] [float] -=== Create an API key in the {apm-app} +=== Create an API key in the APM UI -The {apm-app} 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-app} will show up here. +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. Using a superuser account, or a user with the role created in the previous step, open {kib} and navigate to **{observability}** > **APM** > **Settings** > **Agent keys**. @@ -89,7 +89,7 @@ Click **Create APM Agent key** and copy the Base64 encoded API key. 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-app} API key] +image::images/apm-ui-api-key.png[APM UI API key] [[apm-agent-api-key]] [float] diff --git a/docs/en/observability/apm/api.asciidoc b/docs/en/observability/apm/api.asciidoc index ebf93adbaf..8d81091ca1 100644 --- a/docs/en/observability/apm/api.asciidoc +++ b/docs/en/observability/apm/api.asciidoc @@ -1,5 +1,5 @@ [[apm-api]] -== API +== APM Server API The APM Server exposes endpoints for: diff --git a/docs/en/observability/apm/apm-data-security.asciidoc b/docs/en/observability/apm/apm-data-security.asciidoc index 515da174dd..4ff5d4facc 100644 --- a/docs/en/observability/apm/apm-data-security.asciidoc +++ b/docs/en/observability/apm/apm-data-security.asciidoc @@ -94,7 +94,7 @@ The default list of sanitized fields attempts to target common field names for d 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 {kibana-ref}/agent-configuration.html[Central configuration], +This setting supports <<apm-agent-configuration,Central configuration>>, 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`] @@ -106,7 +106,7 @@ which means the list of sanitized fields can be updated without needing to redep * 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 {kibana-ref}/agent-configuration.html[Central configuration]: +This setting also supports <<apm-agent-configuration,Central configuration>>: * 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`] @@ -124,7 +124,7 @@ 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 {kibana-ref}/agent-configuration.html[Central configuration], +This setting supports <<apm-agent-configuration,Central configuration>>, 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`] diff --git a/docs/en/observability/apm/apm-distributed-tracing.asciidoc b/docs/en/observability/apm/apm-distributed-tracing.asciidoc index 71111252c1..42c04a4e79 100644 --- a/docs/en/observability/apm/apm-distributed-tracing.asciidoc +++ b/docs/en/observability/apm/apm-distributed-tracing.asciidoc @@ -85,7 +85,7 @@ For backward-compatibility purposes, new versions of Elastic agents still suppor [[apm-visualize-distributed-tracing]] === Visualize distributed tracing -The {apm-app}'s timeline visualization provides a visual deep-dive into each of your application's traces: +The APM UI's timeline visualization provides a visual deep-dive into each of your application's traces: [role="screenshot"] image::./images/apm-distributed-tracing.png[Distributed tracing in the APM UI] diff --git a/docs/en/observability/apm/common-problems.asciidoc b/docs/en/observability/apm/common-problems.asciidoc index cd1d61b5d1..3df7179c2b 100644 --- a/docs/en/observability/apm/common-problems.asciidoc +++ b/docs/en/observability/apm/common-problems.asciidoc @@ -20,10 +20,10 @@ include::{observability-docs-root}/docs/en/observability/apm/tab-widgets/no-data [[apm-data-indexed-no-apm]] [float] -=== Data is indexed but doesn't appear in the APM app +=== Data is indexed but doesn't appear in the APM UI -The {apm-app} relies on index mappings to query and display data. -If your APM data isn't showing up in the {apm-app}, but is elsewhere in {kib}, like the Discover app, +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. diff --git a/docs/en/observability/apm/configure/agent-config.asciidoc b/docs/en/observability/apm/configure/agent-config.asciidoc index bcca73c107..50b6c7eb6e 100644 --- a/docs/en/observability/apm/configure/agent-config.asciidoc +++ b/docs/en/observability/apm/configure/agent-config.asciidoc @@ -11,10 +11,10 @@ image:./binary-yes-fm-yes.svg[supported deployment methods] APM agent configuration is supported by all APM Server deployment methods. **** -APM agent configuration allows you to fine-tune your APM agents from within the APM app. +APM agent configuration allows you to fine-tune your APM agents from within the APM UI. Changes are automatically propagated to your APM agents, so there's no need to redeploy your applications. -To learn more about this feature, see {kibana-ref}/agent-configuration.html[APM agent configuration]. +To learn more about this feature, see <<apm-agent-configuration,APM agent configuration>>. Here's a sample configuration: diff --git a/docs/en/observability/apm/configure/instrumentation.asciidoc b/docs/en/observability/apm/configure/instrumentation.asciidoc index b22cf07694..7b6f356c30 100644 --- a/docs/en/observability/apm/configure/instrumentation.asciidoc +++ b/docs/en/observability/apm/configure/instrumentation.asciidoc @@ -42,7 +42,7 @@ Defaults to `false`. === `environment` Set the environment in which APM Server is running, for example, `staging`, `production`, `dev`, etc. -Environments can be filtered in the {kibana-ref}/xpack-apm.html[{apm-app}]. +Environments can be filtered in the <<apm-ui,{kib} APM UI>>. [float] === `hosts` diff --git a/docs/en/observability/apm/cross-cluster-search.asciidoc b/docs/en/observability/apm/cross-cluster-search.asciidoc index 939ab9a1cc..282767474e 100644 --- a/docs/en/observability/apm/cross-cluster-search.asciidoc +++ b/docs/en/observability/apm/cross-cluster-search.asciidoc @@ -25,9 +25,9 @@ See {ref}/ccr-getting-started.html[managing remote clusters] for detailed inform Alternatively, you can {ref}/modules-remote-clusters.html#configuring-remote-clusters[configure remote clusters] in {es}'s `elasticsearch.yml` file. -*Step 2. Edit the default {apm-app} {data-sources}.* +*Step 2. Edit the default APM UI {data-sources}.* -{apm-app} {data-sources} determine which clusters and indices to display data from. +APM UI {data-sources} determine which clusters and indices to display data from. {data-sources-cap} follow this convention: `<cluster-name>:<index-pattern>`. To display data from all remote clusters and the local cluster, @@ -40,7 +40,7 @@ You can also specify certain clusters to display data from, for example, There are two ways to edit the default {data-source}: -* In the {apm-app} -- Navigate to *APM* > *Settings* > *Indices*, and change all `xpack.apm.indices.*` values to +* In the APM UI -- Navigate to *APM* > *Settings* > *Indices*, and change all `xpack.apm.indices.*` values to include remote clusters. * In `kibana.yml` -- Update the {kibana-ref}/apm-settings-kb.html[`xpack.apm.indices.*`] configuration values to include remote clusters. diff --git a/docs/en/observability/apm/custom-index-template.asciidoc b/docs/en/observability/apm/custom-index-template.asciidoc index 2c8b89a33e..bc8a00dcbe 100644 --- a/docs/en/observability/apm/custom-index-template.asciidoc +++ b/docs/en/observability/apm/custom-index-template.asciidoc @@ -23,7 +23,7 @@ Select any of the APM index templates to view their relevant component templates === Edit the {es} index template WARNING: Custom index mappings may conflict with the mappings defined by the APM integration -and may break the APM integration and {apm-app} in {kib}. +and may break the APM integration and APM UI in {kib}. Do not change or customize any default mappings. When you install the APM integration, {fleet} creates a default `@custom` component template for each data stream. diff --git a/docs/en/observability/apm/data-model.asciidoc b/docs/en/observability/apm/data-model.asciidoc index 03493aa366..6e7fa4ef33 100644 --- a/docs/en/observability/apm/data-model.asciidoc +++ b/docs/en/observability/apm/data-model.asciidoc @@ -46,7 +46,7 @@ and non-keyword fields, like `span.start.us`, to 10,000 characters. 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-app} will display the number of spans dropped. +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: @@ -68,7 +68,7 @@ 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-app} will calculate the difference and display a message. +the APM UI will calculate the difference and display a message. [float] ==== Data streams @@ -128,7 +128,7 @@ In addition, agents provide options for users to capture custom <<apm-data-model Metadata can be indexed - <<apm-data-model-labels,`labels`>>, or not-indexed - <<apm-data-model-custom,`custom`>>. Transactions are grouped by their `type` and `name` in the APM UI's -{kibana-ref}/transactions.html[Transaction overview]. +<<apm-transactions,Transaction overview>>. 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`. @@ -223,7 +223,7 @@ include::{apm-server-root}/docs/data/elasticsearch/generated/errors.json[] **Metrics** measure the state of a system by gathering information on a regular interval. There are two types of APM metrics: * **System metrics**: Basic infrastructure and application metrics. -* **Calculated metrics**: Aggregated trace event metrics used to power visualizations in the {apm-app}. +* **Calculated metrics**: Aggregated trace event metrics used to power visualizations in the APM UI. [float] ==== System metrics @@ -235,7 +235,7 @@ like {apm-java-ref-v}/metrics.html[JVM metrics] in the Java Agent, and {apm-go-ref-v}/metrics.html[Go runtime] metrics in the Go Agent. Infrastructure and application metrics are important sources of information when debugging production systems, -which is why we've made it easy to filter metrics for specific hosts or containers in the {kib} {kibana-ref}/metrics.html[metrics overview]. +which is why we've made it easy to filter metrics for specific hosts or containers in the {kib} <<apm-metrics,metrics overview>>. TIP: Most agents limit keyword fields to 1024 characters, non-keyword fields (e.g. `system.memory.total`) to 10,000 characters. @@ -273,7 +273,7 @@ include::{apm-server-root}/docs/data/elasticsearch/metricset.json[] [float] ==== Calculated metrics -APM agents and APM Server calculate metrics from trace events to power visualizations in the {apm-app}. +APM agents and APM Server calculate metrics from trace events to power visualizations in the APM UI. Calculated metrics are an implementation detail and while we aim for stability for these data models, the dimensions and concrete limits for aggregations are subject to change within minor version updates. @@ -283,7 +283,7 @@ These metrics are described below. [float] ===== Breakdown metrics -To power the {apm-app-ref}/transactions.html[Time spent by span type] graph, +To power the <<apm-transactions,Time spent by span type>> graph, agents collect summarized metrics about the timings of spans and transactions, broken down by span type. @@ -323,7 +323,7 @@ include::{apm-server-root}/docs/data/elasticsearch/span_breakdown.json[] [float] ===== Transaction metrics -To power {kibana-ref}/xpack-apm.html[{apm-app}] visualizations, +To power <<apm-ui,{kib} APM UI>> visualizations, APM Server aggregates transaction events into latency distribution metrics. *`transaction.duration.summary`* and *`transaction.duration.histogram`*:: @@ -394,7 +394,7 @@ include::{apm-server-root}/docs/data/elasticsearch/transaction_metric.json[] [float] ===== Service-transaction metrics -To power {kibana-ref}/xpack-apm.html[{apm-app}] visualizations, +To power <<apm-ui,{kib} APM UI>> visualizations, APM Server aggregates transaction events into service-transaction metrics. Service-transaction metrics are similar to transaction metrics, but they usually have a much lower cardinality as they have significantly fewer dimensions. @@ -440,7 +440,7 @@ include::{apm-server-root}/docs/data/elasticsearch/service_transaction_metric.js [float] ===== Service-destination metrics -To power {kibana-ref}/xpack-apm.html[{apm-app}] visualizations, +To power <<apm-ui,{kib} APM UI>> visualizations, APM Server aggregates span events into service-destination metrics. *`span.destination.service.response_time.count`* and *`span.destination.service.response_time.sum.us`*:: @@ -448,7 +448,7 @@ APM Server aggregates span events into service-destination metrics. -- These metrics measure the count and total duration of requests from one service to another service. These are used to calculate the throughput and latency of requests to backend services such as databases in -{kibana-ref}/service-maps.html[Service maps]. +<<apm-service-maps,Service maps>>. These metric documents can be identified by searching for `metricset.name: service_destination`. @@ -488,7 +488,7 @@ include::{apm-server-root}/docs/data/elasticsearch/service_destination_metric.js [float] ===== Service-summary metrics -To power {kibana-ref}/xpack-apm.html[{apm-app}] visualizations, +To power <<apm-ui,{kib} APM UI>> visualizations, APM Server aggregates transaction, error, log, and metric events into service-summary metrics. These metric documents can be identified by searching for `metricset.name: service_summary`. diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index 39ba018973..d8d0d22863 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -320,8 +320,8 @@ PUT _security/role/apm_api_key <1> [[apm-privileges-agent-central-config-server]] ==== APM Server agent central configuration management -APM Server acts as a proxy between your APM agents and the {apm-app}. -The {apm-app} communicates any changed settings to APM Server so that your agents only need to poll the Server +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 to determine which central configuration settings have changed. To grant an APM Server user with the required privileges for managing central configuration in {es} without {kib}, @@ -346,12 +346,12 @@ which requires the following privileges: |Type | Privilege | Purpose | Spaces -|`Read` on {apm-app} -|Allow APM Server to manage central configurations via the {apm-app} +|`Read` on APM UI +|Allow APM Server to manage central configurations via the APM UI |==== -TIP: Looking for privileges and roles needed to use central configuration from the {apm-app} or {apm-app} API? -See {kibana-ref}/apm-app-central-config-user.html[{apm-app} central configuration user]. +TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API? +See <<apm-app-central-config-user,APM UI central configuration user>>. [[apm-privileges-rum-source-map]] === Grant privileges and roles needed for reading source maps @@ -381,7 +381,7 @@ The above privileges should be sufficient for RUM source mapping to work properl as long as APM Server communicates with {es} successfully. If it fails, it may fallback to read source maps via {kib} if configured, which requires additional {kib} privileges. -See {kibana-ref}/rum-sourcemap-api.html[RUM source map API] for more details. +See <<apm-rum-sourcemap-api,RUM source map API>> for more details. //// *********************************** *********************************** diff --git a/docs/en/observability/apm/features.asciidoc b/docs/en/observability/apm/features.asciidoc index 3a2ec61778..6800ce61b6 100644 --- a/docs/en/observability/apm/features.asciidoc +++ b/docs/en/observability/apm/features.asciidoc @@ -5,30 +5,33 @@ <titleabbrev>Features</titleabbrev> ++++ +* <<apm-k8s-attacher>> +* <<apm-cross-cluster-search>> * <<apm-data-security>> * <<apm-distributed-tracing>> -* <<apm-rum>> -* <<apm-sampling>> +* <<apm-jaeger-integration>> * <<apm-log-correlation>> -* <<apm-cross-cluster-search>> -* <<apm-span-compression>> * <<apm-monitoring-aws-lambda>> -* <<apm-k8s-attacher>> +* <<apm-rum>> +* <<apm-span-compression>> +* <<apm-sampling>> + +include::./apm-k8s-attacher.asciidoc[leveloffset=+2] + +include::./cross-cluster-search.asciidoc[] include::./apm-data-security.asciidoc[] include::./apm-distributed-tracing.asciidoc[] -include::./apm-rum.asciidoc[] - -include::./sampling.asciidoc[] +include::./jaeger-integration.asciidoc[] include::./log-correlation.asciidoc[] -include::./cross-cluster-search.asciidoc[] +include::./aws-lambda-extension.asciidoc[leveloffset=+2] -include::./span-compression.asciidoc[] +include::./apm-rum.asciidoc[] -include::./aws-lambda-extension.asciidoc[leveloffset=+2] +include::./span-compression.asciidoc[] -include::./apm-k8s-attacher.asciidoc[leveloffset=+2] +include::./sampling.asciidoc[] diff --git a/docs/en/observability/apm/getting-started-apm-server.asciidoc b/docs/en/observability/apm/getting-started-apm-server.asciidoc index 60051fdad8..2c447e6b91 100644 --- a/docs/en/observability/apm/getting-started-apm-server.asciidoc +++ b/docs/en/observability/apm/getting-started-apm-server.asciidoc @@ -465,7 +465,7 @@ If you haven't already, you can now install APM Agents in your services! * {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 {kibana-ref}/xpack-apm.html[{apm-app}]. +you can start visualizing your data in the <<apm-ui,{kib} APM UI>>. If you're migrating from Jaeger, see <<apm-jaeger-integration>>. @@ -539,4 +539,4 @@ 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-app} with data] +image::./images/kibana-apm-sample-data.png[APM UI with data] diff --git a/docs/en/observability/apm/how-to.asciidoc b/docs/en/observability/apm/how-to.asciidoc index 9c16df1952..266c611ffd 100644 --- a/docs/en/observability/apm/how-to.asciidoc +++ b/docs/en/observability/apm/how-to.asciidoc @@ -1,17 +1,47 @@ [[apm-how-to-guides]] -== How-to guides +== Perform common tasks in the APM UI -Learn how to perform common APM configuration and management tasks. +Learn how to perform common tasks in the APM UI: +* <<apm-agent-configuration>> +* <<apm-spaces>> +* <<apm-alerts>> * <<apm-source-map-how-to>> -* <<apm-jaeger-integration>> -* <<apm-ingest-pipelines>> -* <<apm-custom-index-template>> +* <<apm-custom-links>> +* <<apm-filters>> +* <<apm-correlations>> +* <<apm-agent-explorer>> +* <<apm-machine-learning-integration>> +* <<apm-mobile-session-explorer>> +* <<apm-lambda>> +* <<apm-advanced-queries>> +* <<apm-storage-explorer>> +* <<apm-transactions-annotations>> + +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::./jaeger-integration.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::./ingest-pipelines.asciidoc[] +include::../apm-ui/storage-explorer.asciidoc[] -include::./custom-index-template.asciidoc[] +include::../apm-ui/deployment-annotations.asciidoc[] diff --git a/docs/en/observability/apm/jaeger-integration.asciidoc b/docs/en/observability/apm/jaeger-integration.asciidoc index 5e025d1a34..b83545e2fa 100644 --- a/docs/en/observability/apm/jaeger-integration.asciidoc +++ b/docs/en/observability/apm/jaeger-integration.asciidoc @@ -69,13 +69,13 @@ There are two different ways to configure the sampling rate of your Jaeger agent Central sampling, with {apm-agent} central configuration, allows Jaeger clients to poll APM Server for the sampling rate. This means sample rates can be configured on the fly, on a per-service and per-environment basis. -See {kibana-ref}/agent-configuration.html[Central configuration] to learn more. +See <<apm-agent-configuration,Central configuration>> to learn more. [float] [[apm-configure-sampling-local-jaeger]] ===== Local sampling in each Jaeger client -If you don't have access to the {apm-app}, +If you don't have access to the APM UI, you'll need to change the Jaeger client's `sampler.type` and `sampler.param`. This enables you to set the sampling configuration locally in each Jaeger client. See the official https://www.jaegertracing.io/docs/1.27/sampling/[Jaeger sampling documentation] @@ -85,7 +85,7 @@ for more information. [[apm-configure-start-jaeger]] ==== Start sending data -That's it! Data sent from Jaeger clients to the APM Server can now be viewed in the {apm-app}. +That's it! Data sent from Jaeger clients to the APM Server can now be viewed in the APM UI. [float] [[apm-caveats-jaeger]] @@ -104,7 +104,7 @@ it is not possible to mix and match the use of Elastic's APM agents and Jaeger's * Jaeger clients only sends trace data. APM agents support a larger number of features, like multiple types of metrics, and application breakdown charts. -When using Jaeger, features like this will not be available in the {apm-app}. +When using Jaeger, features like this will not be available in the APM UI. * Elastic APM's <<apm-data-model>> is different than Jaegers. For Jaeger trace data to work with Elastic's data model, we rely on spans being tagged with the appropriate https://github.com/opentracing/specification/blob/master/semantic_conventions.md[`span.kind`]. diff --git a/docs/en/observability/apm/manage-storage.asciidoc b/docs/en/observability/apm/manage-storage.asciidoc index 2b7019c9bf..f2817b1732 100644 --- a/docs/en/observability/apm/manage-storage.asciidoc +++ b/docs/en/observability/apm/manage-storage.asciidoc @@ -2,14 +2,16 @@ == Manage storage {agent} uses <<apm-data-streams,data streams>> to store time series data across multiple indices. +<<apm-custom-index-template,Index templates>> are used to configure the backing indices of data streams as they are created. Each data stream ships with a customizable <<apm-ilm-how-to,index lifecycle policy>> that automates data retention as your indices grow and age. +Use <<apm-ingest-pipelines,ingest pipelines>> to process and enrich APM documents before indexing them. The <<apm-storage-guide,storage and sizing guide>> attempts to define a "typical" storage reference for Elastic APM, and there are additional settings you can tweak to <<apm-reduce-apm-storage,reduce storage>>, or to <<apm-tune-elasticsearch,tune data ingestion in {es}>>. In addition, the APM UI makes it easy to visualize your APM data usage with -{kibana-ref}/storage-explorer.html[storage explorer]. +<<apm-storage-explorer,storage explorer>>. 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. @@ -18,6 +20,10 @@ 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 diff --git a/docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc b/docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc index d4c70f65c2..dc2d3dc156 100644 --- a/docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc +++ b/docs/en/observability/apm/monitoring/monitoring-internal-collection.asciidoc @@ -1,4 +1,3 @@ -[role="xpack"] [[apm-monitoring-internal-collection]] == Use internal collection to send monitoring data ++++ diff --git a/docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc b/docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc index 19b1bcb942..60a666dc6a 100644 --- a/docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc +++ b/docs/en/observability/apm/monitoring/monitoring-metricbeat.asciidoc @@ -1,4 +1,3 @@ -[role="xpack"] [[apm-monitoring-metricbeat-collection]] == Use {metricbeat} to send monitoring data [subs="attributes"] diff --git a/docs/en/observability/apm/release-notes.asciidoc b/docs/en/observability/apm/release-notes.asciidoc index bff627fd98..5287b1deb0 100644 --- a/docs/en/observability/apm/release-notes.asciidoc +++ b/docs/en/observability/apm/release-notes.asciidoc @@ -13,7 +13,7 @@ include::{apm-server-root}/CHANGELOG.asciidoc[tag=list] Looking for a previous version? See the {apm-guide-7x}/release-notes.html[7.x release notes]. -**APM app** +**APM UI** See the {kibana-ref}/release-notes.html[Kibana release notes]. diff --git a/docs/en/observability/apm/sampling.asciidoc b/docs/en/observability/apm/sampling.asciidoc index f1e3c49b77..23eb7d2416 100644 --- a/docs/en/observability/apm/sampling.asciidoc +++ b/docs/en/observability/apm/sampling.asciidoc @@ -105,7 +105,7 @@ A sampled trace retains all data associated with it. A non-sampled trace drops all <<apm-data-model-spans,span>> and <<apm-data-model-transactions,transaction>> data^1^. Regardless of the sampling decision, all traces retain <<apm-data-model-errors,error>> data. -Some visualizations in the {apm-app}, like latency, are powered by aggregated transaction and span <<apm-data-model-metrics,metrics>>. +Some visualizations in the APM UI, like latency, are powered by aggregated transaction and span <<apm-data-model-metrics,metrics>>. Metrics are based on sampled traces and weighted by the inverse sampling rate. For example, if you sample at 5%, each trace is counted as 20. As a result, as the variance of latency increases, or the sampling rate decreases, your level of error will increase. @@ -138,13 +138,13 @@ There are three ways to adjust the head-based sampling rate of your APM agents: ===== Dynamic configuration The transaction sample rate can be changed dynamically (no redeployment necessary) on a per-service and per-environment -basis with {kibana-ref}/agent-configuration.html[{apm-agent} Configuration] in {kib}. +basis with <<apm-agent-configuration,{apm-agent} Configuration>> in {kib}. ===== {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 {kibana-ref}/agent-config-api.html[Agent configuration API reference]. +An example is provided in the <<apm-agent-config-api,Agent configuration API reference>>. ===== {apm-agent} configuration diff --git a/docs/en/observability/apm/source-map-how-to.asciidoc b/docs/en/observability/apm/source-map-how-to.asciidoc index 7470bd565c..12acf196f9 100644 --- a/docs/en/observability/apm/source-map-how-to.asciidoc +++ b/docs/en/observability/apm/source-map-how-to.asciidoc @@ -10,11 +10,11 @@ and not something you only do when you see unhelpful errors. That's because uploading source maps after errors happen won't make old errors magically readable — errors must occur again for source mapping to occur. -Here's an example of an exception stack trace in the {apm-app} when using minified code. +Here's an example of an exception stack trace in the APM UI when using minified code. As you can see, it's not very helpful. [role="screenshot"] -image::images/source-map-before.png[{apm-app} without source mapping] +image::images/source-map-before.png[APM UI without source mapping] With a source map, minified files are mapped back to the original source code, allowing you to maintain the speed advantage of minified code, @@ -22,9 +22,9 @@ without losing the ability to quickly and easily debug your application. Here's the same example as before, but with a source map uploaded and applied: [role="screenshot"] -image::images/source-map-after.png[{apm-app} with source mapping] +image::images/source-map-after.png[APM UI with source mapping] -Follow the steps below to enable source mapping your error stack traces in the {apm-app}: +Follow the steps below to enable source mapping your error stack traces in the APM UI: * <<apm-source-map-rum-initialize>> * <<apm-source-map-rum-generate>> @@ -99,7 +99,7 @@ module.exports = { TIP: When uploading a source map, ensure that RUM support is enabled in the APM integration. -{kib} exposes a {kibana-ref}/rum-sourcemap-api.html[source map endpoint] for uploading source maps. +{kib} exposes a <<apm-rum-sourcemap-api,source map endpoint>> for uploading source maps. Source maps can be uploaded as a string, or as a file upload. Let's look at two different ways to upload a source map: curl and a custom application. @@ -132,7 +132,7 @@ curl -X POST "http://localhost:5601/api/apm/sourcemaps" \ -F 'sourcemap=@./dist/app.min.js.map' ---- <1> This example uses the version from `package.json` -<2> The API key used here needs to have appropriate {kibana-ref}/rum-sourcemap-api.html[privileges] +<2> The API key used here needs to have appropriate <<apm-rum-sourcemap-api,privileges>> [float] [[apm-source-map-custom-app]] diff --git a/docs/en/observability/apm/troubleshoot-apm.asciidoc b/docs/en/observability/apm/troubleshoot-apm.asciidoc index ee36b88fbc..48af1af1c1 100644 --- a/docs/en/observability/apm/troubleshoot-apm.asciidoc +++ b/docs/en/observability/apm/troubleshoot-apm.asciidoc @@ -16,10 +16,10 @@ For additional help with other APM components, see the links below. [[apm-troubleshooting-docs]] === Troubleshooting documentation -{agent}, the {apm-app}, and each {apm-agent} has its own troubleshooting guide: +{agent}, the APM UI, and each {apm-agent} has its own troubleshooting guide: * {fleet-guide}/troubleshooting-intro.html[*{fleet} and {agent}* troubleshooting] -* {kibana-ref}/troubleshooting.html[*{apm-app}* troubleshooting] +* <<apm-app-troubleshooting,*APM UI* 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] diff --git a/docs/en/observability/apm/upgrading-to-integration.asciidoc b/docs/en/observability/apm/upgrading-to-integration.asciidoc index 2461ff570e..e03931ae38 100644 --- a/docs/en/observability/apm/upgrading-to-integration.asciidoc +++ b/docs/en/observability/apm/upgrading-to-integration.asciidoc @@ -139,7 +139,7 @@ no reconfiguration is required in your APM agents. [[apm-integration-upgrade-5]] ==== Stop the APM Server -Once data from upgraded APM agents is visible in the {apm-app}, +Once data from upgraded APM agents is visible in the APM UI, it's safe to stop the APM Server process. Congratulations -- you now have the latest and greatest in Elastic APM! @@ -186,7 +186,7 @@ image::./images/agent-settings-migration.png[{agent} settings migration] {ecloud} will now create a {fleet} Server instance to contain the new APM integration, and then will shut down the old APM server instance. -Within minutes your data should begin appearing in the {apm-app} again. +Within minutes your data should begin appearing in the APM UI again. [discrete] [[apm-integration-upgrade-ess-3]] diff --git a/docs/en/observability/create-alerts.asciidoc b/docs/en/observability/create-alerts.asciidoc index f9b6852392..8b22a26b31 100644 --- a/docs/en/observability/create-alerts.asciidoc +++ b/docs/en/observability/create-alerts.asciidoc @@ -61,7 +61,7 @@ tie into other third-party systems. Connectors allow actions to talk to these se Learn how to create specific types of rules: -* {kibana-ref}/apm-alerts.html[APM rules] +* <<apm-alerts,APM rules>> * <<custom-threshold-alert,Custom threshold rule>> * <<logs-threshold-alert,Log threshold rule>> * <<infrastructure-threshold-alert,Infrastructure threshold rule>> diff --git a/docs/en/observability/monitor-infra/view-infrastructure-metrics.asciidoc b/docs/en/observability/monitor-infra/view-infrastructure-metrics.asciidoc index 7342db2da0..e8d284678e 100644 --- a/docs/en/observability/monitor-infra/view-infrastructure-metrics.asciidoc +++ b/docs/en/observability/monitor-infra/view-infrastructure-metrics.asciidoc @@ -1,7 +1,7 @@ [[view-infrastructure-metrics]] = View infrastructure metrics by resource type -The *Inventory* page provides a metrics-driven view of your entire infrastructure grouped by +The *Inventory* page provides a metrics-driven view of your entire infrastructure grouped by the resources you are monitoring. All monitored resources emitting a core set of infrastructure metrics are displayed to give you a quick view of the overall health of your infrastructure. @@ -108,5 +108,5 @@ Depending on the features you have installed and configured, you can view logs, For example, in the high-level view, when you click a Kubernetes Pod resource, you can choose: * *Kubernetes Pod logs* to <<monitor-logs,view corresponding logs>> in the {logs-app}. -* *Kubernetes Pod APM traces* to {kibana-ref}/traces.html[view corresponding APM traces] in the {apm-app}. +* *Kubernetes Pod APM traces* to <<apm-traces,view corresponding APM traces>> in the APM UI. * *Kubernetes Pod in Uptime* to <<monitor-uptime-synthetics,view related uptime information>> in the {uptime-app}. diff --git a/docs/en/observability/monitor-java-app.asciidoc b/docs/en/observability/monitor-java-app.asciidoc index 17e9c08df1..62e36349c7 100644 --- a/docs/en/observability/monitor-java-app.asciidoc +++ b/docs/en/observability/monitor-java-app.asciidoc @@ -1538,7 +1538,7 @@ similar. The two most important terms are *Spans* and A transaction encapsulates a series of spans, which contain information about the execution of a piece of code. Let’s take a look at -this screenshot from the {kib} {apm-app}. +this screenshot from the {kib} APM UI. [role="screenshot"] image:./images/monitor-java-app-apm-transactions.png[A transaction with spans] @@ -1727,7 +1727,7 @@ java -jar build/libs/javalin-app-all.jar If you want to run this in your IDE, you can either set the environment variables manually or search for a plugin that supports `.env` files. + -Wait a few minutes and let’s finally take a look at the {apm-app}. +Wait a few minutes and let’s finally take a look at the APM UI. + [role="screenshot"] image:./images/monitor-java-app-apm-ui-javalin-app.png[Javalin App APM UI] diff --git a/docs/en/observability/monitor-k8s/monitor-k8s-application-performance.asciidoc b/docs/en/observability/monitor-k8s/monitor-k8s-application-performance.asciidoc index ebfc5bc91e..2be9deaa51 100644 --- a/docs/en/observability/monitor-k8s/monitor-k8s-application-performance.asciidoc +++ b/docs/en/observability/monitor-k8s/monitor-k8s-application-performance.asciidoc @@ -212,12 +212,12 @@ kubectl apply -f demo.yml To view your application's trace data, open {kib} and go to *{observability} → Services*. -The {apm-app} allows you to monitor your software services and applications in real-time: +The APM UI 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 agent-specific metrics like JVM and Go runtime metrics. [role="screenshot"] -image::images/apm-app-landing.png[{apm-app} Kubernetes] +image::images/apm-app-landing.png[APM UI Kubernetes] 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. @@ -225,4 +225,4 @@ Best of all, because Kubernetes environment variables have been mapped to APM me you can filter your trace data by Kubernetes `namespace`, `node.name`, `pod.name`, and `pod.uid`. [role="screenshot"] -image::images/apm-app-kubernetes-filter.png[{apm-app} Kubernetes] +image::images/apm-app-kubernetes-filter.png[APM UI Kubernetes] diff --git a/docs/en/observability/observability-introduction.asciidoc b/docs/en/observability/observability-introduction.asciidoc index 12f175d02c..9dcae27069 100644 --- a/docs/en/observability/observability-introduction.asciidoc +++ b/docs/en/observability/observability-introduction.asciidoc @@ -1,5 +1,4 @@ [[observability-introduction]] -[role="xpack"] = What is Elastic {observability}? {observability} provides granular insights and context into the behavior of applications running in your environments. @@ -26,7 +25,7 @@ agent instrumenting those services. [role="screenshot"] image::images/apm.png[Summary of Services on the {observability} overview page] -You can then drill down into the {apm-app} by clicking *Show service inventory* to quickly find the APM traces for underlying services. +You can then drill down into the APM UI by clicking *Show service inventory* to quickly find the APM traces for underlying services. For more information, see <<apm,Application performance monitoring (APM)>>. @@ -98,7 +97,7 @@ For more information, see <<universal-profiling,Universal Profiling>>. Stay aware of potential issues in your environments with {kib}’s alerting and actions feature that integrates with the {logs-app}, {infrastructure-app}, and -{apm-app}. It provides a set of built-in actions and specific threshold rules +APM UI. It provides a set of built-in actions and specific threshold rules and enables central management of all rules from {kib} Management. On the {observability} **Overview** page, the *Alerts* table provides a snapshot of alerts occurring within the specified time frame. The table includes the alert status, when it was last updated, the reason for the alert, and more. diff --git a/docs/en/observability/tail-logs.asciidoc b/docs/en/observability/tail-logs.asciidoc index ebf31691f6..aa93184d60 100644 --- a/docs/en/observability/tail-logs.asciidoc +++ b/docs/en/observability/tail-logs.asciidoc @@ -63,4 +63,4 @@ To see other actions related to a log event, click *Actions* in the *Log event d Depending on the event and the features you have configured, you can: * Select *View status in Uptime* to <<view-monitor-status,view related uptime information>> in the {uptime-app}. -* Select *View in APM* to {kibana-ref}/traces.html[view corresponding APM traces] in the {apm-app}. +* Select *View in APM* to <<apm-traces,view corresponding APM traces>> in the APM UI. diff --git a/docs/en/observability/traces-get-started.asciidoc b/docs/en/observability/traces-get-started.asciidoc index 8207df6691..7240a082fd 100644 --- a/docs/en/observability/traces-get-started.asciidoc +++ b/docs/en/observability/traces-get-started.asciidoc @@ -77,7 +77,7 @@ For a list of indices users need access to, refer to {observability-guide}/apm-data-streams.html[APM data streams] [role="screenshot"] -image::images/kibana-apm-sample-data.png[{apm-app} with data] +image::images/kibana-apm-sample-data.png[APM UI with data] Not seeing any data? Review our list of {observability-guide}/apm-common-problems.html[common problems] for helpful tips. diff --git a/docs/en/observability/uptime-view-monitor-status.asciidoc b/docs/en/observability/uptime-view-monitor-status.asciidoc index 4185a06859..ae64b2e32e 100644 --- a/docs/en/observability/uptime-view-monitor-status.asciidoc +++ b/docs/en/observability/uptime-view-monitor-status.asciidoc @@ -64,11 +64,11 @@ image::images/monitors-list.png[Monitors list] == Integrate with other Observability apps The Monitor list also contains a menu of available integrations. Expand the table -row for a specific monitor on the list, and then click *Investigate*. +row for a specific monitor on the list, and then click *Investigate*. Depending on the features you have installed and configured, you can view logs, metrics, or APM data relating to that monitor. You can choose: * Show host, pod, or container logs in the <<monitor-logs,{logs-app}>>. -* Show APM data in the {kibana-ref}/traces.html[{apm-app}]. +* Show APM data in the <<apm-traces,APM UI>>. * Show host, pod, or container metrics in the <<analyze-metrics,{infrastructure-app}>>. diff --git a/docs/en/shared/configure-apm-agents/content.asciidoc b/docs/en/shared/configure-apm-agents/content.asciidoc index 468b78396e..cd8fb0d95b 100644 --- a/docs/en/shared/configure-apm-agents/content.asciidoc +++ b/docs/en/shared/configure-apm-agents/content.asciidoc @@ -3,7 +3,7 @@ Central configuration allows you to fine-tune your agent configuration from with Changes are automatically propagated to your APM agents, and there’s no need to redeploy. A select number of configuration options are supported. -See {apm-app-ref}/agent-configuration.html[Agent configuration in {kib}] +See <<apm-agent-configuration,Agent configuration in {kib}>> for more information and a configuration reference. // end::central-config[]