diff --git a/docs/apm-response-codes.asciidoc b/docs/apm-response-codes.asciidoc new file mode 100644 index 00000000000..f6d92f30b8f --- /dev/null +++ b/docs/apm-response-codes.asciidoc @@ -0,0 +1,43 @@ +[[common-response-codes]] +=== APM Server response codes + +[[bad-request]] +[float] +==== HTTP 400: Data decoding error / Data validation error + +The most likely cause for this error is using incompatible versions of {apm-agent} and APM Server. +See the <> to verify compatibility. + +[[event-too-large]] +[float] +==== HTTP 400: Event too large + +APM agents communicate with the APM server by sending events in an HTTP request. Each event is sent as its own line in the HTTP request body. If events are too large, you should consider increasing the <> +setting in the APM integration, and adjusting relevant settings in the agent. + +[[unauthorized]] +[float] +==== HTTP 401: Invalid token + +Either the <> in the request header doesn't match the secret token configured in the APM integration, +or the <> is invalid. + +[[forbidden]] +[float] +==== HTTP 403: Forbidden request + +Either you are sending requests to a <> endpoint without RUM enabled, or a request +is coming from an origin not specified in the APM integration settings. +See the <> setting for more information. + +[[request-timed-out]] +[float] +==== HTTP 503: Request timed out waiting to be processed + +This happens when APM Server exceeds the maximum number of requests that it can process concurrently. +To alleviate this problem, you can try to: reduce the sample rate and/or reduce the collected stack trace information. +See <> for more information. + +Another option is to increase processing power. +This can be done by either migrating your {agent} to a more powerful machine +or adding more APM Server instances. \ No newline at end of file diff --git a/docs/apm-server-down.asciidoc b/docs/apm-server-down.asciidoc new file mode 100644 index 00000000000..89c89999a7d --- /dev/null +++ b/docs/apm-server-down.asciidoc @@ -0,0 +1,29 @@ +[[server-es-down]] +=== What happens when APM Server or {es} is down? + +*If {es} is down* + +APM Server does not have an internal queue to buffer requests, +but instead leverages an HTTP request timeout to act as back-pressure. +If {es} goes down, the APM Server will eventually deny incoming requests. +Both the APM Server and {apm-agent}(s) will issue logs accordingly. + +*If APM Server is down* + +Some agents have internal queues or buffers that will temporarily store data if the APM Server goes down. +As a general rule of thumb, queues fill up quickly. Assume data will be lost if APM Server goes down. +Adjusting these queues/buffers can increase the agent's overhead, so use caution when updating default values. + +* **Go agent** - Circular buffer with configurable size: +{apm-go-ref}/configuration.html#config-api-buffer-size[`ELASTIC_APM_BUFFER_SIZE`]. +// * **iOS agent** - ?? +* **Java agent** - Internal buffer with configurable size: +{apm-java-ref}/config-reporter.html#config-max-queue-size[`max_queue_size`]. +* **Node.js agent** - No internal queue. Data is lost. +* **PHP agent** - No internal queue. Data is lost. +* **Python agent** - Internal {apm-py-ref}/tuning-and-overhead.html#tuning-queue[Transaction queue] +with configurable size and time between flushes. +* **Ruby agent** - Internal queue with configurable size: +{apm-ruby-ref}/configuration.html#config-api-buffer-size[`api_buffer_size`]. +* **RUM agent** - No internal queue. Data is lost. +* **.NET agent** - No internal queue. Data is lost. \ No newline at end of file diff --git a/docs/common-problems.asciidoc b/docs/common-problems.asciidoc index 01616dbda6a..a17f212095b 100644 --- a/docs/common-problems.asciidoc +++ b/docs/common-problems.asciidoc @@ -1,15 +1,13 @@ [[common-problems]] === Common problems -This section describes common problems for users running {agent} and the APM integration. -If you're using the standalone (legacy) APM Server binary, see -<> instead. +This section describes common problems you might encounter when using a Fleet-managed APM Server. * <> * <> * <> * <> -* <> +* <> [float] [[no-data-indexed]] @@ -17,83 +15,58 @@ If you're using the standalone (legacy) APM Server binary, see If no data shows up in {es}, first make sure that your APM components are properly connected. -**Is {agent} healthy?** - -In {kib} open **{fleet}** and find the host that is running the APM integration; -confirm that its status is **Healthy**. -If it isn't, check the {agent} logs to diagnose potential causes. -See {fleet-guide}/monitor-elastic-agent.html[Monitor {agent}s] to learn more. - -**Is APM Server happy?** - -In {kib}, open **{fleet}** and select the host that is running the APM integration. -Open the **Logs** tab and select the `elastic_agent.apm_server` dataset. -Look for any APM Server errors that could help diagnose the problem. - -**Can the {apm-agent} connect to APM Server** - -To determine if the {apm-agent} can connect to the APM Server, send requests to the instrumented service and look for lines -containing `[request]` in the APM Server logs. - -If no requests are logged, confirm that: - -. SSL isn't <>. -. The host is correct. For example, if you're using Docker, ensure a bind to the right interface (for example, set -`apm-server.host = 0.0.0.0:8200` to match any IP) and set the `SERVER_URL` setting in the {apm-agent} accordingly. - -If you see requests coming through the APM Server but they are not accepted (a response code other than `202`), -see <> to narrow down the possible causes. - -**Instrumentation gaps** - -APM agents provide auto-instrumentation for many popular frameworks and libraries. -If the {apm-agent} is not auto-instrumenting something that you were expecting, data won't be sent to the {stack}. -Reference the relevant {apm-agents-ref}/index.html[{apm-agent} documentation] for details on what is automatically instrumented. +include::./tab-widgets/no-data-indexed-widget.asciidoc[] +[[data-indexed-no-apm-legacy]] [float] -[[common-response-codes]] -=== APM Server response codes +=== Data is indexed but doesn't appear in the APM app -[[bad-request]] -[float] -==== HTTP 400: Data decoding error / Data validation error +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, +you may have a missing index mapping. -The most likely cause for this error is using incompatible versions of {apm-agent} and APM Server. -See the <> to verify compatibility. +You can determine if a field was mapped correctly with the `_mapping` API. +For example, run the following command in the {kib} {kibana-ref}/console-kibana.html[console]. +This will display the field data type of the `service.name` field. -[[event-too-large]] -[float] -==== HTTP 400: Event too large - -APM agents communicate with the APM server by sending events in an HTTP request. Each event is sent as its own line in the HTTP request body. If events are too large, you should consider increasing the <> -setting in the APM integration, and adjusting relevant settings in the agent. +[source,curl] +---- +GET *apm*/_mapping/field/service.name +---- -[[unauthorized]] -[float] -==== HTTP 401: Invalid token +If the `mapping.name.type` is `"text"`, your APM indices were not set up correctly. -Either the <> in the request header doesn't match the secret token configured in the APM integration, -or the <> is invalid. +[source,yml] +---- +".ds-metrics-apm.transaction.1m-default-2023.04.12-000038": { + "mappings": { + "service.name": { + "full_name": "service.name", + "mapping": { + "name": { + "type": "text" <1> + } + } + } + } +} +---- +<1> The `service.name` `mapping.name.type` would be `"keyword"` if this field had been set up correctly. -[[forbidden]] -[float] -==== HTTP 403: Forbidden request +To fix this problem, install the APM integration by following these steps: -Either you are sending requests to a <> endpoint without RUM enabled, or a request -is coming from an origin not specified in the APM integration settings. -See the <> setting for more information. +-- +include::./legacy/getting-started-apm-server.asciidoc[tag=install-apm-integration] +-- -[[request-timed-out]] -[float] -==== HTTP 503: Request timed out waiting to be processed +This will reinstall the APM index templates and trigger a data stream index rollover. -This happens when APM Server exceeds the maximum number of requests that it can process concurrently. -To alleviate this problem, you can try to: reduce the sample rate and/or reduce the collected stack trace information. -See <> for more information. +You can verify the correct index templates were installed by running the following command in the {kib} console: -Another option is to increase processing power. -This can be done by either migrating your {agent} to a more powerful machine -or adding more APM Server instances. +[source,curl] +---- +GET /_index_template/traces-apm +---- [float] [[common-ssl-problems]] @@ -191,31 +164,26 @@ APM agent --> Load Balancer --> APM Server The APM Server timeout can be configured by updating the <>. -[[server-es-down]] +[[field-limit-exceeded-legacy]] [float] -=== What happens when APM Server or {es} is down? - -APM Server does not have an internal queue to buffer requests, -but instead leverages an HTTP request timeout to act as back-pressure. -If {es} goes down, the APM Server will eventually deny incoming requests. -Both the APM Server and {apm-agent}(s) will issue logs accordingly. - -If either {es} or the APM Server goes down, -some APM agents have internal queues or buffers that will temporarily store data. -As a general rule of thumb, queues fill up quickly. Assume data will be lost if APM Server or {es} goes down. - -Adjusting {apm-agent} queues/buffers can increase the agent's overhead, so use caution when updating default values. - -* **Go agent** - Circular buffer with configurable size: -{apm-go-ref}/configuration.html#config-api-buffer-size[`ELASTIC_APM_BUFFER_SIZE`]. -// * **iOS agent** - -* **Java agent** - Internal buffer with configurable size: -{apm-java-ref}/config-reporter.html#config-max-queue-size[`max_queue_size`]. -* **Node.js agent** - No internal queue. Data is lost. -* **PHP agent** - No internal queue. Data is lost. -* **Python agent** - Internal {apm-py-ref}/tuning-and-overhead.html#tuning-queue[Transaction queue] -with configurable size and time between flushes. -* **Ruby agent** - Internal queue with configurable size: -{apm-ruby-ref}/configuration.html#config-api-buffer-size[`api_buffer_size`]. -* **RUM agent** - No internal queue. Data is lost. -* **.NET agent** - No internal queue. Data is lost. +=== Field limit exceeded + +When adding too many distinct tag keys on a transaction or span, +you risk creating a link:{ref}/mapping.html#mapping-limit-settings[mapping explosion]. + +For example, you should avoid that user-specified data, +like URL parameters, is used as a tag key. +Likewise, using the current timestamp or a user ID as a tag key is not a good idea. +However, tag *values* with a high cardinality are not a problem. +Just try to keep the number of distinct tag keys at a minimum. + +The symptom of a mapping explosion is that transactions and spans are not indexed anymore after a certain time. Usually, on the next day, +the spans and transactions will be indexed again because a new index is created each day. +But as soon as the field limit is reached, indexing stops again. + +In the agent logs, you won't see a sign of failures as the APM server asynchronously sends the data it received from the agents to {es}. However, the APM server and {es} log a warning like this: + +[source,logs] +---- +{\"type\":\"illegal_argument_exception\",\"reason\":\"Limit of total fields [1000] in [INDEX_NAME] has been exceeded\"} +---- diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index 435e50a6a66..842d898759d 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -134,8 +134,6 @@ include::./legacy/getting-started-apm-server.asciidoc[] :beat-specific-security: {docdir}/legacy/security.asciidoc include::{libbeat-dir}/shared-securing-beat.asciidoc[leveloffset=+1] -include::./legacy/troubleshooting.asciidoc[leveloffset=+1] - // include::./legacy/breaking-changes.asciidoc[leveloffset=+1] include::./legacy/redirects.asciidoc[] diff --git a/docs/legacy/common-problems.asciidoc b/docs/legacy/common-problems.asciidoc deleted file mode 100644 index 2f82e37920b..00000000000 --- a/docs/legacy/common-problems.asciidoc +++ /dev/null @@ -1,353 +0,0 @@ -[[common-problems-legacy]] -== Common problems - - -This section describes common problems you might encounter with APM Server. - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -[[no-data-indexed-legacy]] -[float] -=== No data is indexed - -If no data shows up in {es}, first check that the APM components are properly connected. - -To ensure that APM Server configuration is valid and it can connect to the configured output, {es} by default, -run the following commands: - -["source","sh"] ------------------------------------------------------------- -apm-server test config -apm-server test output ------------------------------------------------------------- - -To see if the agent can connect to the APM Server, send requests to the instrumented service and look for lines -containing `[request]` in the APM Server logs. - -If no requests are logged, it might be that SSL is <> or that the host is wrong. -Particularly, if you are using Docker, ensure to bind to the right interface (for example, set -`apm-server.host = 0.0.0.0:8200` to match any IP) and set the `SERVER_URL` setting in the agent accordingly. - -If you see requests coming through the APM Server but they are not accepted (response code other than `202`), consider -the response code to narrow down the possible causes (see sections below). - -Another reason for data not showing up is that the agent is not auto-instrumenting something you were expecting, check -the {apm-agents-ref}/index.html[agent documentation] for details on what is automatically instrumented. - -APM Server currently relies on {es} to create indices that do not exist. -As a result, {es} must be configured to allow {ref}/docs-index_.html#index-creation[automatic index creation] for APM indices. - -[[data-indexed-no-apm-legacy]] -[float] -=== 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, -you may have a missing index mapping. - -You can determine if a field was mapped correctly with the `_mapping` API. -For example, run the following command in the {kib} {kibana-ref}/console-kibana.html[console]. -This will display the field data type of the `service.name` field. - -[source,curl] ----- -GET apm-*/_mapping/field/service.name ----- - -If the `mapping.name.type` is `"text"`, your APM indices were not set up correctly. - -[source,yml] ----- -"mappings" : { - "service.name" : { - "full_name" : "service.name", - "mapping" : { - "name" : { - "type" : "text", <1> - "fields" : { - "keyword" : { - "type" : "keyword", - "ignore_above" : 256 - } - } - } - } - } -} ----- -<1> The `service.name` `mapping.name.type` would be `"keyword"` if this field had been set up correctly. - -To fix this problem, you must delete and recreate your APM indices as index templates cannot be applied retroactively. - -. Stop your APM Server(s) so they are not writing any new documents. - -. Delete your existing `apm-*` indices. -In the {kib} console, run: -+ -[source,curl] ----- -DELETE apm-* ----- -+ -Alternatively, you can use the {ref}/index-mgmt.html[Index Management] page in {kib}. -Select all `apm-*` index templates and navigate to **Manage Indices** > **Delete Indices**. - -. Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage APM index templates. -Install the APM integration by following these steps: -+ --- -include::./getting-started-apm-server.asciidoc[tag=install-apm-integration] --- - -. Start APM Server. - -. Verify the correct index templates were installed. In the {kib} console, run: -+ -[source,curl] ----- -GET _template/apm-* ----- -+ -Alternatively, you can use the {ref}/index-mgmt.html[**Index Management**] page in {kib}. -On the **Index Templates** tab, search for `apm` under **Legacy Index Templates**. - - -[[bad-request-legacy]] -[float] -=== HTTP 400: Data decoding error / Data validation error - -The most likely cause for this error is using incompatible versions of {apm-agent} and APM Server. -See the {apm-overview-ref-v}/agent-server-compatibility.html[agent/server compatibility matrix] for more information. - -[[event-too-large-legacy]] -[float] -=== HTTP 400: Event too large - -APM agents communicate with the APM server by sending events in an HTTP request. Each event is sent as its own line in the HTTP request body. If events are too large, you should consider increasing the <> -setting in the APM Server, and adjusting relevant settings in the agent. - -[[unauthorized-legacy]] -[float] -=== HTTP 401: Invalid token - -The <> in the request header doesn't match the configured in the APM Server. - -[[forbidden-legacy]] -[float] -=== HTTP 403: Forbidden request - -Either you are sending requests to a <> endpoint without RUM enabled, or a request -is coming from an origin not specified in `apm-server.rum.allow_origins`. See the <>. - -[[request-timed-out-legacy]] -[float] -=== HTTP 503: Request timed out waiting to be processed - -This happens when APM Server exceeds the maximum number of requests that it can process concurrently. - -To alleviate this problem, you can try to: - -* <> -* <> -* <> -* <> - -[float] -[[ssl-client-fails-legacy]] -=== SSL client fails to connect - -The target host running might be unreachable or the certificate may not be valid. To resolve your issue: - -* Make sure that the APM Server process on the target host is running and you can connect to it. -First, try to ping the target host to verify that you can reach it from the host running {beatname_uc}. -Then use either `nc` or `telnet` to make sure that the port is available. For example: -+ -[source,shell] ----------------------------------------------------------------------- -ping -telnet 5044 ----------------------------------------------------------------------- - -* Verify that the certificate is valid and that the hostname and IP match. - -* Use OpenSSL to test connectivity to the target server and diagnose problems. -See the https://www.openssl.org/docs/manmaster/apps/s_client.html[OpenSSL documentation] for more info. - -[float] -==== Common SSL-Related Errors and Resolutions - -Here are some common errors and ways to fix them: - -* <> -* <> -* <> -* <> - -[float] -[[cannot-validate-certificate-legacy]] -===== x509: cannot validate certificate for because it doesn't contain any IP SANs - -This happens because your certificate is only valid for the hostname present in the Subject field. - -To resolve this problem, try one of these solutions: - -* Create a DNS entry for the hostname, mapping it to the server's IP. -* Create an entry in `/etc/hosts` for the hostname. Or, on Windows, add an entry to -`C:\Windows\System32\drivers\etc\hosts`. -* Re-create the server certificate and add a Subject Alternative Name (SAN) for the IP address of the server. This makes the -server's certificate valid for both the hostname and the IP address. - -[float] -[[getsockopt-no-route-to-host-legacy]] -===== getsockopt: no route to host - -This is not an SSL problem. It's a networking problem. Make sure the two hosts can communicate. - -[float] -[[getsockopt-connection-refused-legacy]] -===== getsockopt: connection refused - -This is not an SSL problem. Make sure that {ls} is running and that there is no firewall blocking the traffic. - -[float] -[[target-machine-refused-connection-legacy]] -===== No connection could be made because the target machine actively refused it - -A firewall is refusing the connection. Check if a firewall is blocking the traffic on the client, the network, or the -destination host. - -[[field-limit-exceeded-legacy]] -[float] -=== Field limit exceeded - -When adding too many distinct tag keys on a transaction or span, -you risk creating a link:{ref}/mapping.html#mapping-limit-settings[mapping explosion]. - -For example, -you should avoid that user-specified data, -like URL parameters, -is used as a tag key. -Likewise, -using the current timestamp or a user ID as a tag key is not a good idea. -However, -tag *values* with a high cardinality are not a problem. -Just try to keep the number of distinct tag keys at a minimum. - -The symptom of a mapping explosion is that transactions and spans are not indexed anymore after a certain time. -Usually, -on the next day, -the spans and transactions will be indexed again because a new index is created each day. -But as soon as the field limit is reached, -indexing stops again. - -In the agent logs, -you won't see a sign of failures as the APM server asynchronously sends the data it received from the agents to {es}. -However, -the APM server and {es} log a warning like this: - -[source,logs] ----- -{\"type\":\"illegal_argument_exception\",\"reason\":\"Limit of total fields [1000] in index [apm-7.0.0-transaction-2017.05.30] has been exceeded\"} ----- - -[[io-timeout-legacy]] -[float] -=== I/O Timeout - -I/O Timeouts can occur when your timeout settings across the stack are not configured correctly, -especially when using a load balancer. - -You may see an error like the one below in the agent logs, and/or a similar error on the APM Server side: - -[source,logs] ----------------------------------------------------------------------- -[ElasticAPM] APM Server responded with an error: -"read tcp 123.34.22.313:8200->123.34.22.40:41602: i/o timeout" ----------------------------------------------------------------------- - -To fix this, ensure timeouts are incrementing from the {apm-agents-ref}[{apm-agent}], -through your load balancer, to the <>. - -By default, the agent timeouts are set at 10 seconds, and the server timeout is set at 30 seconds. -Your load balancer should be set somewhere between these numbers. - -For example: - -[source,txt] ----------------------------------------------------------------------- -APM agent --> Load Balancer --> APM Server - 10s 15s 30s ----------------------------------------------------------------------- - -[[server-es-down-legacy]] -[float] -=== What happens when APM Server or {es} is down? - -*If {es} is down* - -APM Server does not have an internal queue to buffer requests, -but instead leverages an HTTP request timeout to act as back-pressure. -If {es} goes down, the APM Server will eventually deny incoming requests. -Both the APM Server and {apm-agent}(s) will issue logs accordingly. - -*If APM Server is down* - -Some agents have internal queues or buffers that will temporarily store data if the APM Server goes down. -As a general rule of thumb, queues fill up quickly. Assume data will be lost if APM Server goes down. -Adjusting these queues/buffers can increase the agent's overhead, so use caution when updating default values. - -* **Go agent** - Circular buffer with configurable size: -{apm-go-ref}/configuration.html#config-api-buffer-size[`ELASTIC_APM_BUFFER_SIZE`]. -// * **iOS agent** - ?? -* **Java agent** - Internal buffer with configurable size: -{apm-java-ref}/config-reporter.html#config-max-queue-size[`max_queue_size`]. -* **Node.js agent** - No internal queue. Data is lost. -* **PHP agent** - No internal queue. Data is lost. -* **Python agent** - Internal {apm-py-ref}/tuning-and-overhead.html#tuning-queue[Transaction queue] -with configurable size and time between flushes. -* **Ruby agent** - Internal queue with configurable size: -{apm-ruby-ref}/configuration.html#config-api-buffer-size[`api_buffer_size`]. -* **RUM agent** - No internal queue. Data is lost. -* **.NET agent** - No internal queue. Data is lost. - -[[central-config-troubleshooting-legacy]] -[float] -=== `/api/apm/settings/agent-configuration/search` errors - -If you're instrumenting and starting a lot of services at the same time -or using a very large number of service or environment names, -you may see the following APM Server logs related to {apm-agent} central configuration: - -* `.../api/apm/settings/agent-configuration/search: context canceled` -* `.../api/apm/settings/agent-configuration/search: net/http: TLS handshake timeout` - -There are two possible causes: - -1. {kib} is overwhelmed by the number of requests coming from APM Server. -2. {es} can't reply quickly enough to {kib}. - -For cause #1, try one or more of the following: - -* Increase the <> setting. -* Increase the <>. -* Increase {kib}'s resources so that it is able to manage more requests. -* If you're not using APM central configuration, disable it with <>. -Central configuration can also be disabled at the {apm-agent} level. - -For cause #2, investigate why {es} is not responding in a timely manner. -{kib}'s queries to {es} are simple, so it may just be that {es} is unhealthy. -If that's not the problem, you may need to use {ref}/index-modules-slowlog.html[Search Slow Log] to investigate your {es} logs. - -To avoid this problem entirely, -we recommend <>. diff --git a/docs/legacy/copied-from-beats/docs/debugging.asciidoc b/docs/legacy/copied-from-beats/docs/debugging.asciidoc index 08cdc3f7152..65d18bcec77 100644 --- a/docs/legacy/copied-from-beats/docs/debugging.asciidoc +++ b/docs/legacy/copied-from-beats/docs/debugging.asciidoc @@ -9,6 +9,16 @@ //// include::../../libbeat/docs/debugging.asciidoc[] ////////////////////////////////////////////////////////////////////////// +[[enable-apm-server-debugging]] +=== Enable APM Server binary debugging + +++++ +APM Server binary debugging +++++ + +NOTE: Fleet-managed users should see {fleet-guide}/monitor-elastic-agent.html[View {agent} logs] +to learn how to view logs and change the logging level of {agent}. + By default, {beatname_uc} sends all its output to syslog. When you run {beatname_uc} in the foreground, you can use the `-e` command line flag to redirect the output to standard error instead. For example: @@ -41,4 +51,4 @@ use `*`, like this: ["source","sh",subs="attributes"] ------------------------------------------------------------ {beatname_lc} -e -d "*" ------------------------------------------------------------- +------------------------------------------------------------ \ No newline at end of file diff --git a/docs/legacy/copied-from-beats/docs/getting-help.asciidoc b/docs/legacy/copied-from-beats/docs/getting-help.asciidoc deleted file mode 100644 index 2404de19a02..00000000000 --- a/docs/legacy/copied-from-beats/docs/getting-help.asciidoc +++ /dev/null @@ -1,24 +0,0 @@ -////////////////////////////////////////////////////////////////////////// -//// This content is shared by all Elastic Beats. Make sure you keep the -//// descriptions here generic enough to work for all Beats that include -//// this file. When using cross references, make sure that the cross -//// references resolve correctly for any files that include this one. -//// Use the appropriate variables defined in the index.asciidoc file to -//// resolve Beat names: beatname_uc and beatname_lc. -//// Use the following include to pull this content into a doc file: -//// include::../../libbeat/docs/getting-help.asciidoc[] -////////////////////////////////////////////////////////////////////////// - -Start by searching the https://discuss.elastic.co/c/{discuss_forum}[{beatname_uc} discussion forum] for your issue. If you can't find a resolution, open a new issue or add a comment to an existing one. Make sure you provide the following information, and we'll help -you troubleshoot the problem: - -* {beatname_uc} version -* Operating System -* Configuration -* Any supporting information, such as debugging output, that will help us diagnose your -problem. See <> for more details. - -If you're sure you found a bug, you can open a ticket on -https://github.com/elastic/{github_repo_name}/issues?state=open[GitHub]. Note, however, -that we close GitHub issues containing questions or requests for help if they -don't indicate the presence of a bug. diff --git a/docs/legacy/redirects.asciidoc b/docs/legacy/redirects.asciidoc index 514014b11d5..896deadfd34 100644 --- a/docs/legacy/redirects.asciidoc +++ b/docs/legacy/redirects.asciidoc @@ -314,3 +314,9 @@ Please see <>. This page has moved. Please see {observability-guide}/whats-new.html[What's new in {observability} {minor-version}]. + +[role="exclude",id="troubleshooting"] +=== Troubleshooting + +This page has moved. +Please see <>. \ No newline at end of file diff --git a/docs/legacy/troubleshooting.asciidoc b/docs/legacy/troubleshooting.asciidoc deleted file mode 100644 index 071958ebf0b..00000000000 --- a/docs/legacy/troubleshooting.asciidoc +++ /dev/null @@ -1,42 +0,0 @@ -[[troubleshooting]] -= Troubleshoot - -If you have issues installing or running APM Server, -read the following tips: - -* <> -* <> -* <> - -Other sections in the documentation may also be helpful: - -* <> -* <> -* <> -* {apm-overview-ref-v}/agent-server-compatibility.html[Agent/Server compatibility matrix] - -If your issue is potentially related to other components of the APM ecosystem, -don't forget to check the relevant troubleshooting guides: - -* {kibana-ref}/troubleshooting.html[{apm-app} troubleshooting] -* {apm-dotnet-ref-v}/troubleshooting.html[.NET agent troubleshooting] -* {apm-go-ref-v}/troubleshooting.html[Go agent troubleshooting] -* {apm-ios-ref-v}/troubleshooting.html[iOS agent troubleshooting] -* {apm-java-ref-v}/trouble-shooting.html[Java agent troubleshooting] -* {apm-node-ref-v}/troubleshooting.html[Node.js agent troubleshooting] -* {apm-php-ref-v}/troubleshooting.html[PHP agent troubleshooting] -* {apm-py-ref-v}/troubleshooting.html[Python agent troubleshooting] -* {apm-ruby-ref-v}/debugging.html[Ruby agent troubleshooting] -* {apm-rum-ref-v}/troubleshooting.html[RUM troubleshooting] - -include::common-problems.asciidoc[] - -[[enable-apm-server-debugging]] -== Debug - -include::{libbeat-dir}/debugging.asciidoc[] - -[[getting-help]] -== Get help - -include::{libbeat-dir}/getting-help.asciidoc[] \ No newline at end of file diff --git a/docs/tab-widgets/no-data-indexed-widget.asciidoc b/docs/tab-widgets/no-data-indexed-widget.asciidoc new file mode 100644 index 00000000000..19b6b228dac --- /dev/null +++ b/docs/tab-widgets/no-data-indexed-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::no-data-indexed.asciidoc[tag=fleet-managed] + +++++ +
+ +
+++++ \ No newline at end of file diff --git a/docs/tab-widgets/no-data-indexed.asciidoc b/docs/tab-widgets/no-data-indexed.asciidoc new file mode 100644 index 00000000000..57a841a6483 --- /dev/null +++ b/docs/tab-widgets/no-data-indexed.asciidoc @@ -0,0 +1,63 @@ +// tag::fleet-managed[] +**Is {agent} healthy?** + +In {kib} open **{fleet}** and find the host that is running the APM integration; +confirm that its status is **Healthy**. +If it isn't, check the {agent} logs to diagnose potential causes. +See {fleet-guide}/monitor-elastic-agent.html[Monitor {agent}s] to learn more. + +**Is APM Server happy?** + +In {kib}, open **{fleet}** and select the host that is running the APM integration. +Open the **Logs** tab and select the `elastic_agent.apm_server` dataset. +Look for any APM Server errors that could help diagnose the problem. + +**Can the {apm-agent} connect to APM Server** + +To determine if the {apm-agent} can connect to the APM Server, send requests to the instrumented service and look for lines +containing `[request]` in the APM Server logs. + +If no requests are logged, confirm that: + +. SSL isn't <>. +. The host is correct. For example, if you're using Docker, ensure a bind to the right interface (for example, set +`apm-server.host = 0.0.0.0:8200` to match any IP) and set the `SERVER_URL` setting in the {apm-agent} accordingly. + +If you see requests coming through the APM Server but they are not accepted (a response code other than `202`), +see <> to narrow down the possible causes. + +**Instrumentation gaps** + +APM agents provide auto-instrumentation for many popular frameworks and libraries. +If the {apm-agent} is not auto-instrumenting something that you were expecting, data won't be sent to the {stack}. +Reference the relevant {apm-agents-ref}/index.html[{apm-agent} documentation] for details on what is automatically instrumented. +// end::fleet-managed[] + +// tag::binary[] +If no data shows up in {es}, first check that the APM components are properly connected. + +To ensure that APM Server configuration is valid and it can connect to the configured output, {es} by default, +run the following commands: + +["source","sh"] +------------------------------------------------------------ +apm-server test config +apm-server test output +------------------------------------------------------------ + +To see if the agent can connect to the APM Server, send requests to the instrumented service and look for lines +containing `[request]` in the APM Server logs. + +If no requests are logged, it might be that SSL is <> or that the host is wrong. +Particularly, if you are using Docker, ensure to bind to the right interface (for example, set +`apm-server.host = 0.0.0.0:8200` to match any IP) and set the `SERVER_URL` setting in the agent accordingly. + +If you see requests coming through the APM Server but they are not accepted (response code other than `202`), consider +the response code to narrow down the possible causes (see sections below). + +Another reason for data not showing up is that the agent is not auto-instrumenting something you were expecting, check +the {apm-agents-ref}/index.html[agent documentation] for details on what is automatically instrumented. + +APM Server currently relies on {es} to create indices that do not exist. +As a result, {es} must be configured to allow {ref}/docs-index_.html#index-creation[automatic index creation] for APM indices. +// end::binary[] diff --git a/docs/troubleshoot-apm.asciidoc b/docs/troubleshoot-apm.asciidoc index ae32f63f1da..01869e762b4 100644 --- a/docs/troubleshoot-apm.asciidoc +++ b/docs/troubleshoot-apm.asciidoc @@ -1,9 +1,16 @@ [[troubleshoot-apm]] -== Troubleshooting +== Troubleshoot -This section provides solutions to <> -and <> guidance. -For additional help, see the links below. +This section provides solutions to common questions and problems, +and processing and performance guidance. + +* <> +* <> +* <> +* <> +* <> + +For additional help with other APM components, see the links below. [float] [[troubleshooting-docs]] @@ -40,4 +47,10 @@ visit our https://discuss.elastic.co/c/apm[discussion forum]. include::common-problems.asciidoc[] -include::processing-performance.asciidoc[] \ No newline at end of file +include::apm-server-down.asciidoc[] + +include::apm-response-codes.asciidoc[] + +include::processing-performance.asciidoc[] + +include::./legacy/copied-from-beats/docs/debugging.asciidoc[] \ No newline at end of file