Skip to content

Docs around monitoring are very confusing

Created by: dadlerj

In the process of searching for docs on what metrics are available to Docker image users, I ran into a lot of confusing links...

My search was https://docs.sourcegraph.com/search?q=monitoring&v=

I first visited: https://docs.sourcegraph.com/admin/monitoring

  • This folder has no overview of monitoring, which surprised me... Where do I get started?

I followed the link on that page to get to: https://docs.sourcegraph.com/admin/monitoring/metrics_reference

  • This page dives straight into detail about specific metrics/Grafana dashboards
  • No link back to any central intro/overview of monitoring
  • I searched the page for the metric I was interested in, and didn't find it. I scrolled to the bottom and found that more details are coming soon.

I hit back in my browser twice to get to the search results. There, I discovered that there's an entirely separate file from the /monitoring folder above at https://docs.sourcegraph.com/admin/monitoring_and_tracing

  • This page is what I was looking for! An overview!

I saw a link near the top that said: "descriptions of the Grafana dashboards provided by Sourcegraph" — that sounds like what I need, so I clicked on it and arrived at another separate file at https://docs.sourcegraph.com/admin/monitoring_dashboards

  • Helpful, but not exactly what I wanted... Was hoping more for a "use case" guide (e.g. if an instance sees a lot of timeouts, find a dashboard that shows how search is performing in aggregate) rather than a service-by-service list.

Finally, just out of curiosity, I went back to see which of these pages appeared in the various site indexes. I found different results for the docs sidebar (which only has the monitoring_and_tracing page) and the /admin index (which has that page, a link to the troubleshooting section on that page, and a link to the metrics reference page that I visited first:

image

In my mind, it would be worthwhile to relocate all of these into a single sub-directory under /admin (perhaps the existing /admin/monitoring one?), to split out some of the sections on that monitoring_and_tracing page to separate pages, and to update the two site indexes!