From e146203129573c4eaf814e306fb48740b239b7b9 Mon Sep 17 00:00:00 2001 From: mdbirnstiehl Date: Mon, 21 Aug 2023 16:35:51 -0500 Subject: [PATCH 1/5] add onboarding troubleshooting --- .../logs-troubleshooting.asciidoc | 109 +++++++++++++++++- 1 file changed, 108 insertions(+), 1 deletion(-) diff --git a/docs/en/observability/logs-troubleshooting.asciidoc b/docs/en/observability/logs-troubleshooting.asciidoc index 3a2b564934..55b68aa844 100644 --- a/docs/en/observability/logs-troubleshooting.asciidoc +++ b/docs/en/observability/logs-troubleshooting.asciidoc @@ -1,4 +1,111 @@ [[logs-troubleshooting]] = Troubleshoot your logs -_coming soon_ \ No newline at end of file +This section provides solutions to errors you might encounter while onboarding your logs in {kib}. + +[discrete] +[[logs-troubleshooting-insufficient-priv]] +== User does not have permissions to create API key + +If you don't have the required privileges to create an API key, you'll see the following error message: + +---- +User does not have permissions to create API key. + +Required cluster privileges are [`monitor`, `manage_own_api_key`] and +required index privileges are [`auto_configure`, `create_doc`] for +indices [`logs-*-*`, `metrics-*-*`], please add all required privileges +to the role of the authenticated user. +---- + +*Solution:* + +You need an administrator to give you the necessary permissions listed in the error messages and then to restart the onboarding flow. + +[discrete] +[[logs-troubleshooting-API-key-failed]] +== Failed to create API key + +If you don't have the privileges to create `savedObjects` in {kib}, you'll see the following error message: + +---- +Failed to create API key + +Something went wrong: Unable to create observability-onboarding-state +---- + +*Solution:* + +You need an administrator to give you privileges to create `savedObjects` in {kib} to generate the required `observabilityOnboarding` flow state. +Once you have necessary privileges, restart the onboarding flow. + +[discrete] +[[logs-troubleshooting-kib-not-accessible]] +== {kib} not accessible from host + +If {kib} is not accessible from the host, you'll see the following error message after pasting the *Install the {agent}* instructions your host: + +---- +New integrated terminal + +To set your external terminal as the default, change your preferences. +---- + +*Solution:* +The host needs access to {Kib}. If that's not possible, you can manually download and configure the {agent}. See the <> documentation for more information. + +[discrete] +[[logs-troubleshooting-download-agent]] +== Download {agent} failed + +If the host was able to download the installation script but cannot connect to the public artifactory repository, you'll see the following error message: + +---- +Download Elastic Agent + +Failed to download Elastic Agent, see script for error. +---- + +*Solutions:* + +* **Agent version and OS architecture is not available* ++ +The combination of {agent} version and OS architecture is not available. If this is the case you'll see the following error message on your host: ++ +---- +New integrated terminal + +To set your external terminal as the default, change your preferences. +---- ++ +To fix this, modify the {agent} version in the installation instructions to a known version of the {agent}. + +* You're an Elastic Cloud Enterprise user without access to the Elastic downloads page. +* The {agent} was fully downloaded previously. In this case, delete previous downloads and restart the onboarding. + +[discrete] +[[logs-troubleshooting-install-agent]] +== Install {agent} failed + +If an {agent} already exists on your host, you'll see the following error message: + +---- +Install Elastic Agent + +Failed to install Elastic Agent, see script for error. +---- + +*Solution:* +You can uninstall the current {agent} using the `elastic-agent uninstall` command, and run the script again. + +WARNING: Uninstalling the current {agent} removes the entire current setup including the existing configuration. + +[discrete] +[[logs-troubleshooting-wait-for-logs]] +== Waiting for Logs to be shipped... step never completes + +If the *Waiting for Logs to be shipped...* step never completes, logs are not being shipped to {es}, and there is most likely an issue with your {agent} configuration. + +*Solution:* + +See the {fleet-guide}/debug-standalone-agents.html#inspect-standalone-agent-logs[Debug standalone {agent}s] documentation for information on checking {agent} logs to look for errors. \ No newline at end of file From cb418edde4ab9add8d3198ec97937bccd1dd4d54 Mon Sep 17 00:00:00 2001 From: mdbirnstiehl Date: Tue, 22 Aug 2023 09:00:26 -0500 Subject: [PATCH 2/5] fix formatting --- docs/en/observability/logs-troubleshooting.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/observability/logs-troubleshooting.asciidoc b/docs/en/observability/logs-troubleshooting.asciidoc index 55b68aa844..f50b4b3b88 100644 --- a/docs/en/observability/logs-troubleshooting.asciidoc +++ b/docs/en/observability/logs-troubleshooting.asciidoc @@ -68,7 +68,7 @@ Failed to download Elastic Agent, see script for error. *Solutions:* -* **Agent version and OS architecture is not available* +* *Agent version and OS architecture is not available* + The combination of {agent} version and OS architecture is not available. If this is the case you'll see the following error message on your host: + From 16318b7dd7983da4641fb701b242b52eaf118c55 Mon Sep 17 00:00:00 2001 From: mdbirnstiehl Date: Tue, 29 Aug 2023 14:22:45 -0500 Subject: [PATCH 3/5] review updates --- .../logs-troubleshooting.asciidoc | 43 ++++++++++++++----- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/en/observability/logs-troubleshooting.asciidoc b/docs/en/observability/logs-troubleshooting.asciidoc index f50b4b3b88..775d00cc7f 100644 --- a/docs/en/observability/logs-troubleshooting.asciidoc +++ b/docs/en/observability/logs-troubleshooting.asciidoc @@ -1,7 +1,7 @@ [[logs-troubleshooting]] = Troubleshoot your logs -This section provides solutions to errors you might encounter while onboarding your logs in {kib}. +This section provides solutions to errors you might encounter while onboarding your logs. [discrete] [[logs-troubleshooting-insufficient-priv]] @@ -9,6 +9,7 @@ This section provides solutions to errors you might encounter while onboarding y If you don't have the required privileges to create an API key, you'll see the following error message: +[source, plaintext] ---- User does not have permissions to create API key. @@ -18,9 +19,14 @@ indices [`logs-*-*`, `metrics-*-*`], please add all required privileges to the role of the authenticated user. ---- -*Solution:* +[discrete] +[[logs-troubleshooting-insufficient-priv-solution]] +=== Solution + +You need to either: -You need an administrator to give you the necessary permissions listed in the error messages and then to restart the onboarding flow. +* Get the necessary privileges listed in the error messages from an administrator, and restart the onboarding flow. +* Get an API key from an administrator and manually add the API to the {agent} configuration. See <> for more on manually updating the configuration and adding the API. [discrete] [[logs-troubleshooting-API-key-failed]] @@ -28,13 +34,16 @@ You need an administrator to give you the necessary permissions listed in the er If you don't have the privileges to create `savedObjects` in {kib}, you'll see the following error message: +[source, plaintext] ---- Failed to create API key Something went wrong: Unable to create observability-onboarding-state ---- -*Solution:* +[discrete] +[[logs-troubleshooting-API-key-failed-solution]] +=== Solution You need an administrator to give you privileges to create `savedObjects` in {kib} to generate the required `observabilityOnboarding` flow state. Once you have necessary privileges, restart the onboarding flow. @@ -43,15 +52,19 @@ Once you have necessary privileges, restart the onboarding flow. [[logs-troubleshooting-kib-not-accessible]] == {kib} not accessible from host -If {kib} is not accessible from the host, you'll see the following error message after pasting the *Install the {agent}* instructions your host: +If {kib} is not accessible from the host, you'll see the following error message after pasting the *Install the {agent}* instructions into your host: +[source, plaintext] ---- New integrated terminal To set your external terminal as the default, change your preferences. ---- -*Solution:* +[discrete] +[[logs-troubleshooting-kib-not-accessible-solution]] +=== Solution + The host needs access to {Kib}. If that's not possible, you can manually download and configure the {agent}. See the <> documentation for more information. [discrete] @@ -60,18 +73,22 @@ The host needs access to {Kib}. If that's not possible, you can manually downloa If the host was able to download the installation script but cannot connect to the public artifactory repository, you'll see the following error message: +[source, plaintext] ---- Download Elastic Agent Failed to download Elastic Agent, see script for error. ---- -*Solutions:* +[discrete] +[[logs-troubleshooting-download-agent-solution]] +=== Solutions -* *Agent version and OS architecture is not available* +* Agent version and OS architecture is not available: + The combination of {agent} version and OS architecture is not available. If this is the case you'll see the following error message on your host: + +[source, plaintext] ---- New integrated terminal @@ -79,7 +96,6 @@ To set your external terminal as the default, change your preferences. ---- + To fix this, modify the {agent} version in the installation instructions to a known version of the {agent}. - * You're an Elastic Cloud Enterprise user without access to the Elastic downloads page. * The {agent} was fully downloaded previously. In this case, delete previous downloads and restart the onboarding. @@ -89,13 +105,16 @@ To fix this, modify the {agent} version in the installation instructions to a kn If an {agent} already exists on your host, you'll see the following error message: +[source, plaintext] ---- Install Elastic Agent Failed to install Elastic Agent, see script for error. ---- -*Solution:* +[discrete] +[[logs-troubleshooting-install-agent-solution]] +=== Solution You can uninstall the current {agent} using the `elastic-agent uninstall` command, and run the script again. WARNING: Uninstalling the current {agent} removes the entire current setup including the existing configuration. @@ -106,6 +125,8 @@ WARNING: Uninstalling the current {agent} removes the entire current setup inclu If the *Waiting for Logs to be shipped...* step never completes, logs are not being shipped to {es}, and there is most likely an issue with your {agent} configuration. -*Solution:* +[discrete] +[[logs-troubleshooting-wait-for-logs-solution]] +=== Solution See the {fleet-guide}/debug-standalone-agents.html#inspect-standalone-agent-logs[Debug standalone {agent}s] documentation for information on checking {agent} logs to look for errors. \ No newline at end of file From 60ae3900e16ec4cbb4679ef15f1e6a23f31312db Mon Sep 17 00:00:00 2001 From: mdbirnstiehl Date: Wed, 30 Aug 2023 19:10:29 -0500 Subject: [PATCH 4/5] review updates --- docs/en/observability/logs-troubleshooting.asciidoc | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/en/observability/logs-troubleshooting.asciidoc b/docs/en/observability/logs-troubleshooting.asciidoc index 775d00cc7f..7bf820f101 100644 --- a/docs/en/observability/logs-troubleshooting.asciidoc +++ b/docs/en/observability/logs-troubleshooting.asciidoc @@ -56,9 +56,7 @@ If {kib} is not accessible from the host, you'll see the following error message [source, plaintext] ---- -New integrated terminal - -To set your external terminal as the default, change your preferences. +Failed to connect to {host} port {port} after 0 ms: Connection refused ---- [discrete] @@ -71,7 +69,7 @@ The host needs access to {Kib}. If that's not possible, you can manually downloa [[logs-troubleshooting-download-agent]] == Download {agent} failed -If the host was able to download the installation script but cannot connect to the public artifactory repository, you'll see the following error message: +If the host was able to download the installation script but cannot connect to the public artifact repository, you'll see the following error message: [source, plaintext] ---- @@ -86,13 +84,11 @@ Failed to download Elastic Agent, see script for error. * Agent version and OS architecture is not available: + -The combination of {agent} version and OS architecture is not available. If this is the case you'll see the following error message on your host: +The combination of {agent} version and operating system architecture is not available. If this is the case you'll see the following error message on your host: + [source, plaintext] ---- -New integrated terminal - -To set your external terminal as the default, change your preferences. +The requested URL returned error: 404 ---- + To fix this, modify the {agent} version in the installation instructions to a known version of the {agent}. From 190e8e705af85edbaff72339caffdae34fde53a3 Mon Sep 17 00:00:00 2001 From: mdbirnstiehl Date: Fri, 1 Sep 2023 15:37:38 -0500 Subject: [PATCH 5/5] review updates --- .../logs-troubleshooting.asciidoc | 31 +++++++++++-------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/en/observability/logs-troubleshooting.asciidoc b/docs/en/observability/logs-troubleshooting.asciidoc index 7bf820f101..25f30c8705 100644 --- a/docs/en/observability/logs-troubleshooting.asciidoc +++ b/docs/en/observability/logs-troubleshooting.asciidoc @@ -1,7 +1,7 @@ [[logs-troubleshooting]] = Troubleshoot your logs -This section provides solutions to errors you might encounter while onboarding your logs. +This section provides possible solutions for errors you might encounter while onboarding your logs. [discrete] [[logs-troubleshooting-insufficient-priv]] @@ -25,8 +25,8 @@ to the role of the authenticated user. You need to either: -* Get the necessary privileges listed in the error messages from an administrator, and restart the onboarding flow. -* Get an API key from an administrator and manually add the API to the {agent} configuration. See <> for more on manually updating the configuration and adding the API. +* Have an administrator give you the `monitor` and `manage_own_api_key` cluster privileges and the `auto_configure` and `create_doc` indices privileges. Once you have these privileges, restart the onboarding flow. +* Get an API key from an administrator and manually add the API to the {agent} configuration. See <> for more on manually updating the configuration and adding the API key. [discrete] [[logs-troubleshooting-API-key-failed]] @@ -45,14 +45,14 @@ Something went wrong: Unable to create observability-onboarding-state [[logs-troubleshooting-API-key-failed-solution]] === Solution -You need an administrator to give you privileges to create `savedObjects` in {kib} to generate the required `observabilityOnboarding` flow state. -Once you have necessary privileges, restart the onboarding flow. +You need an administrator to give you the `Saved Objects Management` {kib} privilege to generate the required `observability-onboarding-state` flow state. +Once you have the necessary privileges, restart the onboarding flow. [discrete] [[logs-troubleshooting-kib-not-accessible]] == {kib} not accessible from host -If {kib} is not accessible from the host, you'll see the following error message after pasting the *Install the {agent}* instructions into your host: +If {kib} is not accessible from the host, you'll see the following error message after pasting the *Install the {agent}* instructions into the host: [source, plaintext] ---- @@ -82,18 +82,23 @@ Failed to download Elastic Agent, see script for error. [[logs-troubleshooting-download-agent-solution]] === Solutions -* Agent version and OS architecture is not available: -+ -The combination of {agent} version and operating system architecture is not available. If this is the case you'll see the following error message on your host: +* If the combination of the {agent} version and operating system architecture is not available, you'll see the following error message: + [source, plaintext] ---- The requested URL returned error: 404 ---- + -To fix this, modify the {agent} version in the installation instructions to a known version of the {agent}. +To fix this, update the {agent} version in the installation instructions to a known version of the {agent}. +* If the {agent} was fully downloaded previously, you'll see the following error message: ++ +[source, plaintext] +---- +Error: cannot perform installation as Elastic Agent is already running from this directory +---- ++ +To fix this, delete previous downloads and restart the onboarding. * You're an Elastic Cloud Enterprise user without access to the Elastic downloads page. -* The {agent} was fully downloaded previously. In this case, delete previous downloads and restart the onboarding. [discrete] [[logs-troubleshooting-install-agent]] @@ -113,7 +118,7 @@ Failed to install Elastic Agent, see script for error. === Solution You can uninstall the current {agent} using the `elastic-agent uninstall` command, and run the script again. -WARNING: Uninstalling the current {agent} removes the entire current setup including the existing configuration. +WARNING: Uninstalling the current {agent} removes the entire current setup, including the existing configuration. [discrete] [[logs-troubleshooting-wait-for-logs]] @@ -125,4 +130,4 @@ If the *Waiting for Logs to be shipped...* step never completes, logs are not be [[logs-troubleshooting-wait-for-logs-solution]] === Solution -See the {fleet-guide}/debug-standalone-agents.html#inspect-standalone-agent-logs[Debug standalone {agent}s] documentation for information on checking {agent} logs to look for errors. \ No newline at end of file +Inspect the {agent} logs for errors. See the {fleet-guide}/debug-standalone-agents.html#inspect-standalone-agent-logs[Debug standalone {agent}s] documentation for more on finding errors in {agent} logs. \ No newline at end of file