[WIP] Admin UI docs #2534

Amruta-Ranade · 2018-02-15T19:55:44Z

Closes #2260, #2033, #2466

cockroach-teamcity · 2018-02-15T19:55:48Z

This change is

cockroach-teamcity · 2018-02-15T19:57:46Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/39c8bf8bfee0ef18a023f2aedd48f9c6411a5353/

cockroach-teamcity · 2018-02-20T17:44:34Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/4855b87ccaf77516d07e5f97eb25e08f8942b97f/

cockroach-teamcity · 2018-03-01T20:42:44Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/afa2d9f52a2df4702c9e0dfa3431a692e8d48dfb/

cockroach-teamcity · 2018-03-02T02:34:08Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/7c038425b0a5498f317b13103a837dc6fcdde8fb/

Amruta-Ranade · 2018-03-02T02:38:50Z

@vilterp @couchand @josueeee
I have added the draft doc for the Node Map. It's not yet polished, but wanted to check if I am on the right track. Let me know what you think.

(PS: You can ignore the housekeeping and cleanup tasks for other Admin UI docs. For now, a review of the Node Map doc is what I need).

vilterp

Gave it a skim; looks good overall! Left a couple of nits.

vilterp · 2018-03-02T19:33:33Z

v2.0/admin-ui-node-map.md

+
+|  Node | Region | Datacenter |
+|  ------ | ------ | ------ |
+|  N1 | us-east | us-east-1 |


nit: maybe just 1 or n1

vilterp · 2018-03-02T19:34:28Z

v2.0/admin-ui-node-map.md

+--host=localhost \
+--port=26257 \
+--http-port=8080 \
+--join=localhost:26257,localhost:26258,localhost:26259


nit: only need to specify one other address in join flag. Also, the first node doesn't have anyone to join, so maybe leave it off.

I kept this consistent with other docs.

vilterp · 2018-03-02T19:35:13Z

v2.0/admin-ui-node-map.md

+
+<img src="{{ 'images/admin-ui-node-map-components.png' | relative_url }}" alt="CockroachDB Admin UI Summary Panel" style="border:1px solid #eee;max-width:90%" />
+
+## Location Co-ordinates for Reference


nit: I think coordinates is one word, without a dash

vilterp · 2018-03-02T19:38:17Z

v2.0/admin-ui-node-map.md

+|  Asia Pacific (Singapore) | ap-southeast-1 | asia-southeast1 | Southeast Asia | 1.352083 | 103.819836 |
+|  Asia Pacific (Sydney) | ap-southeast-2 | australia-southeast1 |  | -33.86882 | 151.209296 |
+|  Asia Pacific (Mumbai) | ap-south-1 | asia-south1 | West India | 19.075984 | 72.877656 |
+|  South America (São Paulo) | sa-east-1 | southamerica-east1 | Brazil South | -23.55052 | -46.633309 |


maybe include these in SQL insert statement form, i.e.

INSERT INTO system.locations VALUES ('region', 'us-east-1', 37.478397, -76.453077), ('region', 'us-east-2', 40.417287, -82.907123), ...

So people can just paste the entire table into the SQL shell if they want?

@vilterp I tried doing it, but it made the table hideous. Now I am thinking of taking out the AWS, Azure, GCE codes and just having list of geographical regions and coordinates. Thoughts?

cockroach-teamcity · 2018-03-05T20:39:59Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/b0d861e4a02ec04eb20f8c8c5349d82807b4b34c/

cockroach-teamcity · 2018-03-05T20:42:34Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/9c0ac224856ac1449c870b4fae28f55dee7db4b8/

couchand · 2018-03-06T18:12:32Z

v2.0/admin-ui-access-and-navigate.md

+
+Area | Description
+--------|----
+[Cluster Visualization]() | View and monitor the metrics and geographical configuration of your cluster.


If this entry is still relevant does it need a link?

couchand · 2018-03-06T18:16:09Z

_includes/sidebar-data-v2.0.json

            "urls": [
-              "/${VERSION}/admin-ui-overview-dashboard.html"
+              "/${VERSION}/admin-ui-metrics-dashboard.html"
            ]
          },
          {


commenting here since I can't comment on the images themselves:

node-map-components:

it might be useful to have a locality example as well to highlight the (subtle) differences

I believe the capacity value on the right is the total capacity, not available capacity.

I would quibble with "real-time", since these figures are really short-term averages... perhaps "current"?

node-map

it looks like this is a mockup, not a screenshot, which is mostly fine except that there are some inconsistencies.

couchand · 2018-03-06T18:22:46Z

v2.0/admin-ui-access-and-navigate.md

-ID | The ID of the node.
-Address | The address of the node. You can click on the address to view further details about the node.
-Down Since | How long the node has been down.
+The main panel display changes for each page: 


this reads oddly

umm..it has a minor grammatical error. But other than that, I don't see why this reads oddly? :|

I guess it's the doubling of "panel" and "display" that's throwing me off, plus the fact that "display" could be a noun or a verb? I'm not sure exactly what I meant originally.

couchand · 2018-03-06T18:28:59Z

v2.0/admin-ui-access-and-navigate.md

-#### Decommissioned Nodes
+Page | Main Panel Component
+-----------|------------
+Cluster Overview | <ul><li>[Cluster Overview panel](admin-ui-access-and-navigate.html#cluster-overview-panel)</li><li>Either the [Node List](admin-ui-access-and-navigate.html#nodes-list) (for OSS users) or [Cluster Visualization]() (for enterprise users)</li></ul>


perhaps "for core users" rather than "for OSS users", to harmonize with the way we refer to it elsewhere?

couchand · 2018-03-06T18:31:19Z

v2.0/admin-ui-time-series.md

@@ -0,0 +1,64 @@
+---
+title: Admin UI Time Series Graphs


For my part, I would prefer if we used the word "Chart" everywhere, rather than "Graph" (see cockroachdb/cockroach#23419)

@couchand We are renaming all graphs to charts?

I don't think we actually used the term "graph" in any user-facing capacity until the "custom graph" page was created. Please correct me if I missed it somewhere.

As discussed, punting till after 2.0

couchand · 2018-03-06T19:12:43Z

v2.0/admin-ui-node-map.md

+
+<img src="{{ 'images/admin-ui-node-map-components.png' | relative_url }}" alt="CockroachDB Admin UI Summary Panel" style="border:1px solid #eee;max-width:90%" />
+
+## Location Coordinates for Reference


This seems like it's just making more work for future us to keep it up, but I guess it's helpful...

couchand · 2018-03-06T19:13:50Z

v2.0/admin-ui-node-map.md

+
+#### Step 6. View the Node Map
+
+[Navigate to the **Overview page**](admin-ui-cluster-overview.html) and switch to the **Node Map** view from the drop-down box.


If they've followed everything correctly to this point, the node map should be the default.

@couchand Umm..not sure about that.

Yes, I think it's an unresolved question in the implementation, but that is the goal: if a user has an enterprise license, and all their nodes have localities and locations, the map should be the default view.

couchand · 2018-03-06T19:14:59Z

v2.0/admin-ui-node-map.md

+
+1. Click on map component marked as **region=us-east** on the Node Map. The datacenter view is displayed.
+2. Click on the datacenter component marked as **datacenter=us-east-1**. The individual node components are displayed.
+3. To navigate back to the cluster view, either click on **Cluster** in the bread-crumb trail at the top of the Node Map, or click **Up to Cluster** in the lower left-hand side of the Node Map.


If they're two levels deep, the up button will say "Up to region=us-east".

Yes..but if they follow our tutorial, they will have the levels described here.

The "up" button only goes up one level. If they are down two levels (one from step 1, and a second on step 2), the button will only go up one level, to region=us-east.

couchand · 2018-03-06T19:19:33Z

v2.0/admin-ui-time-series.md

+
+<img src="{{ 'images/admin_ui_hovering.gif' | relative_url }}" alt="CockroachDB Admin UI" style="border:1px solid #eee;max-width:100%" />
+
+{{site.data.alerts.callout_info}}By default, CockroachDB stores timeseries metrics for the last 30 days, but you can reduce the interval for timeseries storage. Alternately, if you are exclusively using a third-party tool such as <a href="monitor-cockroachdb-with-prometheus.html">Prometheus</a> for timeseries monitoring, you can disable timeseries storage entirely. For more details, see this <a href="operational-faqs.html#can-i-reduce-or-disable-the-storage-of-timeseries-data-new-in-v2-0">FAQ</a>.


it might be clear already, but it might be useful to be explicit here that doing disabling storage will make time series charts not work (including the sparklines on the clusterviz)

I don't think we need to spell that out.

couchand · 2018-03-06T19:20:12Z

v2.0/admin-ui-time-series.md

+You can change the time range by clicking on the time window.
+<img src="{{ 'images/admin_ui_time_range.gif' | relative_url }}" alt="CockroachDB Admin UI" style="border:1px solid #eee;max-width:100%" />
+
+{{site.data.alerts.callout_info}}The Admin UI shows time in UTC, even if you set a different time zone for your cluster. {{site.data.alerts.end}}


oh that's unfortunate

Amruta-Ranade · 2018-03-08T16:08:51Z

_includes/sidebar-data-v2.0.json

            "urls": [
-              "/${VERSION}/admin-ui-overview-dashboard.html"
+              "/${VERSION}/admin-ui-metrics-dashboard.html"
            ]
          },
          {


@couchand Yes, I think you were on vacation when we discussed this. I am going to wait till the last week before the release to update all screenshots, so we have more time to make the visual tweaks if needed. So all screenshots as of now are placeholders.

Amruta-Ranade · 2018-03-08T16:32:23Z

v2.0/admin-ui-access-and-navigate.md

+
+Area | Description
+--------|----
+[Cluster Visualization]() | View and monitor the metrics and geographical configuration of your cluster.


Amruta-Ranade · 2018-03-08T16:33:34Z

v2.0/admin-ui-access-and-navigate.md

-ID | The ID of the node.
-Address | The address of the node. You can click on the address to view further details about the node.
-Down Since | How long the node has been down.
+The main panel display changes for each page: 


umm..it has a minor grammatical error. But other than that, I don't see why this reads oddly? :|

Amruta-Ranade · 2018-03-08T16:35:57Z

v2.0/admin-ui-access-and-navigate.md

+Cluster Overview | <ul><li>[Cluster Overview panel](admin-ui-access-and-navigate.html#cluster-overview-panel)</li><li>Either the [Node List](admin-ui-access-and-navigate.html#nodes-list) (for OSS users) or [Cluster Visualization]() (for enterprise users)</li></ul>
+Cluster Metrics | <ul><li>[Time Series graphs](admin-ui-access-and-navigate.html#time-series-graphs)</li><li>[Events List](admin-ui-time-series.html#events-panel)</li></ul>
+Databases | Information about the Tables or Grants in your databases. 
+Jobs | Information about all currently active schema changes and backup/restore jobs.


Amruta-Ranade · 2018-03-08T16:45:30Z

v2.0/admin-ui-cluster-overview.md

+
+Metric | Description
+--------|----
+Capacity Usage | <ul><li>The storage capacity used as a percentage of total storage capacity allocated across all nodes.<br><br>**Note:** If you are running multiple nodes on a single machine (not recommended), this value may be incorrect. This is because when multiple nodes are running on a single machine, the machine's hard disk is treated as separate stores for each node, while in reality, only one hard disk is used for all nodes. The Capacity Used is then displayed as the hard disk capacity used multiplied by the number of nodes on the machine.</li><li>The current capacity usage.</li></ul>


Amruta-Ranade · 2018-03-08T17:05:31Z

v2.0/admin-ui-metrics-dashboard.md

 toc: false
 ---

-On [accessing the CockroachDB Admin UI](admin-ui-access-and-navigate.html#access-the-admin-ui), the **Overview** is shown by default. This dashboard lets you monitor important SQL performance, replication, and storage metrics.
+On [accessing the CockroachDB Admin UI](admin-ui-access-and-navigate.html#access-the-admin-ui), the **Metrics Overview** is shown by default. This dashboard lets you monitor important SQL performance, replication, and storage metrics.


Excellent catch! Fixed all instances.

Amruta-Ranade · 2018-03-08T17:11:17Z

v2.0/admin-ui-cluster-overview.md

+
+#### Dead Nodes
+
+Nodes are considered dead once they have not responded for a certain amount of time (5 minutes by default). At this point, the automated repair process starts, wherein CockroachDB automatically rebalances replicas from the dead node, using the unaffected replicas as sources. See [Stop a Node](stop-a-node.html#how-it-works) for more information.


Excellent point. Added the link.

Amruta-Ranade · 2018-03-08T17:12:14Z

v2.0/admin-ui-node-map.md

+
+The **Node Map** view helps you:
+
+- Confirm that the database is balanced and you are utilizing the resource effectively. This helps you provision hardware and plan ahead for scale.


Tweaked it.

Amruta-Ranade · 2018-03-08T17:12:31Z

v2.0/admin-ui-node-map.md

+The **Node Map** view helps you:
+
+- Confirm that the database is balanced and you are utilizing the resource effectively. This helps you provision hardware and plan ahead for scale.
+- Ensure that storage capacity is balanced across the disks available to the extent that they match the zone configs.


@couchand But indirectly, they can, right?

Amruta-Ranade · 2018-03-08T17:13:21Z

v2.0/admin-ui-node-map.md

+- Monitor disk utilization to know if you need to add more storage capacity.
+- Identify dead nodes in the cluster.
+- Be informed about unavailable or under-replicated ranges.
+- Confirm that configuration changes were persisted to the cluster.


@couchand Which part? Should I just drop the "Confirm that configuration changes were persisted to the cluster" part?

cockroach-teamcity · 2018-03-08T17:25:41Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/9f3d7f24bac68fb0e59c9ba84f67d306a1b60ed4/

cockroach-teamcity · 2018-03-08T17:57:47Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/baa15296a3935d1f4a83cf96259e70d92e3cf2bb/

cockroach-teamcity · 2018-03-08T18:34:08Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/c56019c4dd17de257a0abd85e4be6b575614bb86/

cockroach-teamcity · 2018-03-08T19:21:13Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/50893285dcb2e74c603d34103597b83f715a4c31/

vilterp

noticed a couple occurrences of the wrong flag

vilterp · 2018-03-15T14:58:06Z

v2.0/admin-ui-node-map.md

+
+## Configure and Navigate the Node Map
+
+To configure the **Node Map**, you need to start the cluster with the correct `--localities` flags and assign the latitudes and longitudes for each region.


the flag is --locality, not --localities

Good catch.

vilterp · 2018-03-15T14:58:30Z

v2.0/admin-ui-node-map.md

+
+If not, [upgrade to CockroachDB v2.0](upgrade-cockroach-version.html).
+
+#### Step 2. Start the nodes with the correct `--localities` flags


vilterp · 2018-03-15T14:58:39Z

v2.0/admin-ui-node-map.md

+
+The Localities debug page displays the following: 
+
+- Localities configuration that you set up while starting the nodes with the `--localities` options. 


same (also probably better to always say "flag" rather than "option")

cockroach-teamcity · 2018-03-20T16:45:23Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ca2a2555ac8378bac98623eed253817f8e3c954e/

cockroach-teamcity · 2018-03-21T23:48:38Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/0c416271788eec4ca7b6c6a58123e4d048ff976c/

cockroach-teamcity · 2018-03-22T00:02:46Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/3ed48bc457c72d61d8965ae2ab27351ff03afc58/

cockroach-teamcity · 2018-03-22T00:07:07Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/3ed48bc457c72d61d8965ae2ab27351ff03afc58/

Amruta-Ranade · 2018-03-22T00:15:58Z

@jseldess The Admin UI docs are ready for your review.

Note to self: After Jesse's review, fix broken links in other docs.

Amruta-Ranade · 2018-03-22T20:14:15Z

@jseldess I am going to rework this PR based on today's discussion, and probably break it out into smaller (manageable) pieces. This PR has become overstuffed over the quarter. Will add you as reviewer once I reorganize things.

jseldess · 2018-03-22T20:49:30Z

Sounds good, @Amruta-Ranade. Thanks!

vilterp · 2018-03-22T23:03:23Z

v2.0/admin-ui-node-map.md

+The Localities debug page displays the following: 
+
+- Localities configuration that you set up while starting the nodes with the `--locality` flags. 
+- Nodes corrsponding to each locality.


typo: "corresponding"

cockroach-teamcity · 2018-03-23T00:06:20Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/f92a72b859868077776d4ca6d9132086eee8087f/

Amruta-Ranade added the in progress label Feb 15, 2018

Amruta-Ranade requested review from vilterp, couchand and josueeee March 2, 2018 18:27

vilterp reviewed Mar 2, 2018

View reviewed changes

couchand reviewed Mar 6, 2018

View reviewed changes

Amruta-Ranade commented Mar 8, 2018

View reviewed changes

vilterp suggested changes Mar 15, 2018

View reviewed changes

Amruta-Ranade added 8 commits March 21, 2018 19:58

Initial cleanup + documented cluster overview panel

7b2984f

Restructured content

f6e6dd8

Work in Progress

1361022

Node Map Doc

77ad4ce

Fixed nits + Redesigned localities reference table

85446f7

Fixed nit

d05016f

Incorporated Andrew's and Josue's comments

38b765c

Added troubleshooting for localities with same names

2cfeec3

Amruta-Ranade added 2 commits March 21, 2018 19:59

Minor fixes

1bf5ccf

Worked on Andrew's and Pete's comments

3ed48bc

Amruta-Ranade force-pushed the admin_ui_docs branch from 0c41627 to 3ed48bc Compare March 22, 2018 00:00

Amruta-Ranade requested review from jseldess and removed request for jseldess March 22, 2018 00:26

vilterp reviewed Mar 22, 2018

View reviewed changes

Fixed nit.

f92a72b

jseldess closed this Apr 4, 2018

jseldess deleted the admin_ui_docs branch April 4, 2018 15:00

jseldess removed the in progress label Apr 4, 2018


		<img src="{{ 'images/admin-ui-node-map-components.png' \| relative_url }}" alt="CockroachDB Admin UI Summary Panel" style="border:1px solid #eee;max-width:90%" />

		## Location Co-ordinates for Reference


		<img src="{{ 'images/admin-ui-node-map-components.png' \| relative_url }}" alt="CockroachDB Admin UI Summary Panel" style="border:1px solid #eee;max-width:90%" />

		## Location Coordinates for Reference


		#### Step 6. View the Node Map

		[Navigate to the Overview page](admin-ui-cluster-overview.html) and switch to the Node Map view from the drop-down box.


		<img src="{{ 'images/admin_ui_hovering.gif' \| relative_url }}" alt="CockroachDB Admin UI" style="border:1px solid #eee;max-width:100%" />

		{{site.data.alerts.callout_info}}By default, CockroachDB stores timeseries metrics for the last 30 days, but you can reduce the interval for timeseries storage. Alternately, if you are exclusively using a third-party tool such as <a href="monitor-cockroachdb-with-prometheus.html">Prometheus</a> for timeseries monitoring, you can disable timeseries storage entirely. For more details, see this <a href="operational-faqs.html#can-i-reduce-or-disable-the-storage-of-timeseries-data-new-in-v2-0">FAQ</a>.


		#### Dead Nodes

		Nodes are considered dead once they have not responded for a certain amount of time (5 minutes by default). At this point, the automated repair process starts, wherein CockroachDB automatically rebalances replicas from the dead node, using the unaffected replicas as sources. See [Stop a Node](stop-a-node.html#how-it-works) for more information.


		The Node Map view helps you:

		- Confirm that the database is balanced and you are utilizing the resource effectively. This helps you provision hardware and plan ahead for scale.


		## Configure and Navigate the Node Map

		To configure the Node Map, you need to start the cluster with the correct `--localities` flags and assign the latitudes and longitudes for each region.


		If not, [upgrade to CockroachDB v2.0](upgrade-cockroach-version.html).

		#### Step 2. Start the nodes with the correct `--localities` flags


		The Localities debug page displays the following:

		- Localities configuration that you set up while starting the nodes with the `--localities` options.

[WIP] Admin UI docs #2534

[WIP] Admin UI docs #2534

Conversation

Amruta-Ranade commented Feb 15, 2018 • edited Loading

cockroach-teamcity commented Feb 15, 2018

cockroach-teamcity commented Feb 15, 2018

cockroach-teamcity commented Feb 20, 2018

cockroach-teamcity commented Mar 1, 2018

cockroach-teamcity commented Mar 2, 2018

Amruta-Ranade commented Mar 2, 2018

vilterp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cockroach-teamcity commented Mar 5, 2018

cockroach-teamcity commented Mar 5, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cockroach-teamcity commented Mar 8, 2018

cockroach-teamcity commented Mar 8, 2018

cockroach-teamcity commented Mar 8, 2018

cockroach-teamcity commented Mar 8, 2018

vilterp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cockroach-teamcity commented Mar 20, 2018

cockroach-teamcity commented Mar 21, 2018

cockroach-teamcity commented Mar 22, 2018

cockroach-teamcity commented Mar 22, 2018

Amruta-Ranade commented Mar 22, 2018

Amruta-Ranade commented Mar 22, 2018

jseldess commented Mar 22, 2018

Choose a reason for hiding this comment

cockroach-teamcity commented Mar 23, 2018

Amruta-Ranade commented Feb 15, 2018 •

edited

Loading