search

elastic / kibana

Your window into the Elastic Stack
https://www.elastic.co/products/kibana
Other
19.82k stars 8.21k forks source link

[FR] Link code for error "Kibana server is not ready yet" to point to related doc #158518

Open stefnestor opened 1 year ago

stefnestor commented 1 year ago

👋 Howdy, team! Similar to how Elastic Cloud & Elasticsearch are moving more towards having errors link directly into related docs ( https://github.com/elastic/docs/pull/2631 , REDACTED , REDACTED ), would y'all consider updating this code which surfaces common start-up error Kibana server is not ready yet. to link to its related Kibana doc (which we're WIP to outline more troubleshooting info on under https://github.com/elastic/kibana/pull/158379).

CC: @KOTungseth to keep me correct that I believe this doc location isn't going to change anytime soon

elasticmachine commented 1 year ago

Pinging @elastic/kibana-security (Team:Security)

elasticmachine commented 1 year ago

Pinging @elastic/kibana-core (Team:Core)

sophiec20 commented 2 months ago

I would like a share an alternate perspective on this request. I do not think direct URLs in logging is the right way to think about improving supportability for our admin-users.

We already have links to docs in Kibana UI.. and we have additional checks and processes to ensure that these links are valid and pointing to relevant content. This is not a trivial task to set up and maintain. It is worth doing for the UI, because it is interactive, used frequently, and allows us to adapt and change and improve content.

Adding URLs into log files has less benefit imho. The hyperlinks are not clickable. It's rarely used (rare compared to use of UI). It would be very difficult to guarantee on-going accuracy of URLs if the docs system changes. And it means its hard to change our docs system and reorganise content.

An admin-user, who looks at logfiles, would be very used to searching for info about the message - either in a well-known search engine or an elastic knowledge base. It should be more easy to find info about key error messages in our docs and KBs.

Regarding this specific message - In this case, if we think about the problem of how to let customers know why Kibana server is not yet ready, I believe we also should be improving logging at INFO/WARN levels and if appropriate introducing extra tests in code which could narrow down the possibly problems - for example, to indicate issues connecting to elasticsearch or with index health, or to suggest checking the elasticsearch logs (e.g. for high watermark).

Happy to discuss further (at the supportability sync) especially if there is more supporting info on the most common error messages - so we can think about how to improve supportability for these as well.

Gunnerva commented 2 months ago

@sophiec20

Thank you for the thoughts and concerns from the dev perspective -- I think it would be nice to further discuss at our next sync. From support's perspective it would be nice to have these type of links for a few of the more common issues, we don't want to burden Dev with adding URLs to every possible error message.

Putting out the thoughts on why Support would like to see links to Troubleshooting docs for common errors:

  1. Elasticsearch is starting to add it.
    Example from Elasticsearch logs: [{instance-0000000012}{2b84d_OATIiU2HxF9xTNqQ}{S995_lK3Qx-TbYxXY-VPAQ}{instance-0000000012}{10.81.186.14}{10.81.186.14:19780}{mr}{8.12.0}{7000099-8500008}] from last-known cluster state; node term 31004, last-accepted version 3369289 in term 30176; for troubleshooting guidance, see https://www.elastic.co/guide/en/elasticsearch/reference/8.12/discovery-troubleshooting.html

  2. Possibly decrease tickets. Customers are always asked to provide logs, so in seeing the URL in the logs, they might do some troubleshooting prior to opening a ticket.

  3. Possibly higher quality tickets -- we would have some customers that would go through the troubleshooting process before opening tickets

  4. Better SDHs. Our support team would work though public troubleshooting docs and KBs prior to opening the SDH. Any URL called out via the logs -- would be reviewed prior to opening a SDH.

  5. Could we also update the Kibana server is not ready yet. to be something like Kibana server is not ready yet. Please check the logs for more information.

I realize we need to make sure this feature/change makes sense in the serverless world and also loop in the doc team.