Document /debug and other debugging tools

[a-robinson]

Some users have requested information about how to use the various debugging tools available within CockroachDB to look into problems with their queries or with the system's health. A core dev or two that have a lot of debugging experience should write up some documentation or at least a blog post with examples in the time leading up to 1.0 after feature freeze.

@cockroachdb/core

[tamird]

Related to #1190.

[jseldess]

@petermattis's training material should serve as the basis here.

[jseldess]

With @kuanluo, decided that we should add a quick overview of the /debug page somewhere in docs, following up later with deeper explanations and examples.

@a-robinson, what other developer-facing debug tools should we eventually document?

[a-robinson]

The /debug pages is the biggest one. cockroach debug zip would be nice (although it looks like #1469 will cover that). The troubleshooting docs that @sploiselle wrote up are great. The internal doc that Peter wrote up is probably the most comprehensive resource we have of developer-facing debug tools.

[jseldess]

@dianasaur323, @Amruta-Ranade mentioned that we're going to polish and expose our /debug pages for 2.0. Is that right? If so, we should discuss how to document these. In my opinion, debug docs are probably higher value than some other admin ui docs (updating graphs, etc.). Should I set up a meeting to discuss?

[dianasaur323]

Sure, there are just 3 pages I think are worth documenting, so we can do those.

[jseldess]

Since this issue is broader than just debug pages, I created a separate issue to document the 4 pages we're exposing in 2.0: #2373

[jseldess]

At this point, this is mostly about debug pages, so closing this in favor of #3399.