Open stefnestor opened 1 year ago
Pinging @elastic/kibana-security (Team:Security)
Pinging @elastic/kibana-core (Team:Core)
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.
@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:
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
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.
Possibly higher quality tickets -- we would have some customers that would go through the troubleshooting process before opening tickets
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.
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.
👋 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