Add logs onboarding troubleshooting (#3157) (#3207)

(cherry picked from commit 9552649)

Co-authored-by: Mike Birnstiehl <[email protected]>

docs/en/observability/logs-troubleshooting.asciidoc

@@ -1,4 +1,133 @@
 [[logs-troubleshooting]]
 = Troubleshoot your logs
 
-_coming soon_
+This section provides possible solutions for errors you might encounter while onboarding your logs.
+
+[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:
+
+[source, plaintext]
+----
+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.
+----
+
+[discrete]
+[[logs-troubleshooting-insufficient-priv-solution]]
+=== Solution
+
+You need to either:
+
+* 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 <<logs-stream-agent-config, Configure the {agent}>> for more on manually updating the configuration and adding the API key.
+
+[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:
+
+[source, plaintext]
+----
+Failed to create API key
+
+Something went wrong: Unable to create observability-onboarding-state
+----
+
+[discrete]
+[[logs-troubleshooting-API-key-failed-solution]]
+=== Solution
+
+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 the host:
+
+[source, plaintext]
+----
+Failed to connect to {host} port {port} after 0 ms: Connection refused
+----
+
+[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 <<logs-stream, Stream a log file>> 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 artifact repository, you'll see the following error message:
+
+[source, plaintext]
+----
+Download Elastic Agent
+
+Failed to download Elastic Agent, see script for error.
+----
+
+[discrete]
+[[logs-troubleshooting-download-agent-solution]]
+=== Solutions
+
+* 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, 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.
+
+[discrete]
+[[logs-troubleshooting-install-agent]]
+== Install {agent} failed
+
+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.
+----
+
+[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. 
+
+[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. 
+
+[discrete]
+[[logs-troubleshooting-wait-for-logs-solution]]
+=== Solution
+
+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.