Enable Node Map doc #2775

Amruta-Ranade · 2018-03-24T17:35:32Z

As discussed, breaking up the Node Map doc PR:
Phase 1: Added content for enabling the Node Map.

@vilterp @couchand You have reviewed the content before, but I have reworked it based on Thursday's meeting. You might want to take a look at the revised content.

cockroach-teamcity · 2018-03-24T17:35:37Z

This change is

cockroach-teamcity · 2018-03-24T17:39:10Z

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

cockroach-teamcity · 2018-03-24T17:41:45Z

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

cockroach-teamcity · 2018-03-24T20:47:33Z

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

jseldess

@Amruta-Ranade, I haven't had the chance to review the whole page yet, but I have some preliminary comments for you.

jseldess · 2018-03-25T15:01:25Z

v2.0/enable-node-map.md

+### Step 5. View the Node Map
+
+[Navigate to the **Overview page**](admin-ui-overview.html) to view the **Node Map**.


Since we use Navigate in the next step, let's use something else here, e.g,:

Open the Overview page...

jseldess · 2018-03-25T15:04:52Z

v2.0/enable-node-map.md

+<div id="toc"></div>
+
+To enable the **Node Map**, you need to start the cluster with the correct `--locality` flags and assign the latitudes and longitudes for each locality.


This content, right below the TOC and without its own section heading, is very likely to get lost/skipped. I'd suggest revising the intro to the page to incorporate this content:

The **Node Map** visualizes the geographical configuration of a multi-regional cluster by plotting the node localities on a world map. The **Node Map** also provides real-time cluster metrics, with the ability to drill down to individual nodes to monitor and troubleshoot the cluster health and performance. This page walks your through the process of setting up and enabling the **Node Map**. {{site.data.alerts.callout_info}}The <b>Node Map</b> is an <a href="enterprise-licensing.html">enterprise-only</a> feature. However, you can <a href="https://www.cockroachlabs.com/pricing/request-a-license/">request a trial license</a> to try it out. {{site.data.alerts.end}}

Reworked it a bit (not sure if it's enough).

jseldess · 2018-03-25T15:05:01Z

v2.0/enable-node-map.md

+{{site.data.alerts.callout_info}}The <b>Node Map</b> won't be displayed until <i>all</i> nodes are started with the correct <code>--locality</code> flags and all localities are assigned the corresponding latitudes and longitudes. {{site.data.alerts.end}}
+
+## Example


It feel strange to frame this whole procedure as an example. Let's remove this and mention the scenario before showing the cockroach start commands in the next step. That would mean making all of the steps h2 headings.

jseldess · 2018-03-25T15:06:48Z

v2.0/enable-node-map.md

+If not, [upgrade to CockroachDB v2.0](upgrade-cockroach-version.html).
+
+### Step 2. Start (or Restart) the Nodes with the Correct `--locality` Flags


Based on our conversation, what are the recommendations we want to make about the locality level to set? That's not really indicated anywhere.

We had decided to add it as a troubleshooting item. I have added the guidance to the troubleshooting section as per our conversation.

cockroach-teamcity · 2018-03-25T21:04:29Z

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

Amruta-Ranade · 2018-03-27T19:53:14Z

v2.0/enable-node-map.md

+To get the latitudes and longitudes of common AWS/Azure/GC regions, see [Locations Coordinates for Reference](#location-coordinates-for-reference).
+
+### Step 5. View the Node Map


Node Map available by default not implemented. Need to specify they need to navigate to it after configuring.

cockroach-teamcity · 2018-03-28T17:55:15Z

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

couchand

Looks good from my end (other than the shell code snippet type). Thanks!

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

v2.0/enable-node-map.md

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


Maybe first have a sentence with something about what you're supposed to see?

Yes, let's put this as a second code block showing the response:

~~~ Build Tag: {{page.release_info.version}} Build Time: {{page.release_info.build_time}} Distribution: CCL Platform: darwin amd64 Go Version: go1.8.3 C Compiler: 4.2.1 Compatible Clang 3.8.0 (tags/RELEASE_380/final) Build SHA-1: 5b757262d33d814bda1deb2af20161a1f7749df3 Build Type: release ~~~

Following that, I'd write out the sentence a bit more explicitly, e.g.:

If any node is running an earlier version, upgrade it to CockroachDB v2.0.

Added and updated to match 2.0 release requirements (Go version, SHA)

couchand · 2018-03-28T19:13:51Z

v2.0/enable-node-map.md

+
+{% include copy-clipboard.html %}
+~~~ sql


this should be shell

couchand · 2018-03-28T19:17:51Z

v2.0/enable-node-map.md

+~~~
+
+Insert the latitudes and longitudes of each region into the `system.locations` table:


Just had a thought, maybe we should sprinkle the word "approximate" or something when we talk about lat/long, to emphasize that it doesn't need to be perfect?

couchand · 2018-03-28T19:19:20Z

v2.0/enable-node-map.md

+### Step 2. Start (or Restart) the Nodes with the Correct `--locality` Flags
+
+If you have a cluster running without the `--locality` flags set, restart the nodes with the correct `--locality` flags(add link to rolling restart page once it's created).


Oh, just noting this TODO item...

Punting to post-2.0

jseldess

Looking good, @Amruta-Ranade. Just a handful more suggestions.

Also, you need to add (Enterprise) to the title and add this to the sidenav. I'd suggest adding it to the Deploy section for visibility, perhaps below Define Table Partition (Enterprise).

jseldess · 2018-03-28T19:10:42Z

v2.0/enable-node-map.md

+This page walks you through the process of setting up and enabling the **Node Map**.
+
+{{site.data.alerts.callout_info}}The <b>Node Map</b> is an <a href="enterprise-licensing.html">enterprise-only</a> feature. However, you can <a href="https://www.cockroachlabs.com/pricing/request-a-license/">request a trial license</a>  to enable the <b>Node Map</b>. {{site.data.alerts.end}}


I'd still prefer an slightly altered second sentence here:

However, you can request a trial license to try it out.

jseldess · 2018-03-28T19:14:23Z

v2.0/enable-node-map.md

+
+{% include copy-clipboard.html %}
+~~~ sql


sql > shell

jseldess · 2018-03-28T19:15:52Z

v2.0/enable-node-map.md

+### Step 5. View the Node Map
+
+[Open the **Overview page**](admin-ui-overview.html) and select **Node Map** from the **View** drop-down menu to view the **Node Map**.


Let's remove to view the **Node Map**.

Also, admin-ui-overview.html doesn't seem like the right link. Where do you want to send people?

Fixed link.

jseldess · 2018-03-28T19:16:36Z

v2.0/enable-node-map.md

+### Step 6. Navigate the Node Map
+
+Let's say you want to navigate to Node 2, which is in datacenter `us-east-1a` in the `us-east-1` region. To navigate to Node 2:


Remove To navigate to Node 2: and end the first sentence with a colon.

jseldess · 2018-03-28T19:17:02Z

v2.0/enable-node-map.md

+Let's say you want to navigate to Node 2, which is in datacenter `us-east-1a` in the `us-east-1` region. To navigate to Node 2:
+
+1. Click on map component marked as **region=us-east-1** on the **Node Map**. The datacenter view is displayed.


on map component > on the map component

jseldess · 2018-03-28T19:21:50Z

v2.0/enable-node-map.md

+<div id="toc"></div>
+
+## Setting Up and Enabling the Node Map


I think we can remove this entire section and just move the scenario details to step 2. That would let us promot all of the steps to h2s.

Not sure what you mean here. Let's discuss this in office tomorrow.

jseldess · 2018-03-28T19:45:02Z

v2.0/enable-node-map.md

+### Unable to Assign Latitude/Longitude Coordinates to Localities
+
+You won't be able to assign latitude/longitude coordinates to localities is if the components of your localities have the same name. For example, consider the following partial configuration:


Remove is in is if the components.

jseldess · 2018-03-28T19:45:46Z

v2.0/enable-node-map.md

+The **Node Map** is displayed only for the locality levels that have latitude/longitude coordinates assigned to them: 
+
+- If you assign the latitude/longitude coordinates at the region level, the **Node Map** shows the regions on the world map. However, when you drill down to the datacenter and further to the individual nodes level, the world map disappears and the datacenters/nodes are be plotted in a circular layout.  


Remove level in individual nodes level.

Remove be in are be plotted.

jseldess · 2018-03-28T19:48:03Z

v2.0/enable-node-map.md

+
+- If you assign the latitude/longitude coordinates at the region level, the **Node Map** shows the regions on the world map. However, when you drill down to the datacenter and further to the individual nodes level, the world map disappears and the datacenters/nodes are be plotted in a circular layout.  
+- If you assign the latitude/longitude coordinates at the datacenter level, the **Node Map** shows the regions with single datacenters at the same location assigned to the datacenter, while regions with multiple datacenters are shown at the center of the datacenter coordinates in the region. When you drill down to the datacenter levels, the **Node Map** shows the datacenter at their assigned coordinates. Further drilling down to individual node levels shows the nodes in a circular layout. 


center of the datacenter coordinates > average of the datacenter coordinates?

fwiw the precise term is "centroid"

Centroid of datacenter coordinates? (Sounds weird, but technically accurate I guess)

@jseldess @couchand What do we want to use here? Centroid, center, average?

jseldess · 2018-03-28T19:48:54Z

v2.0/enable-node-map.md

+## Location Coordinates for Reference
+
+|  **Location** | **SQL Statement** |  


Remove the bolding. Not needed in a header row.

cockroach-teamcity · 2018-03-28T22:51:15Z

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

cockroach-teamcity · 2018-03-28T23:21:46Z

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

cockroach-teamcity · 2018-03-28T23:47:48Z

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

cockroach-teamcity · 2018-03-28T23:49:09Z

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

jseldess

LGTM, with some final requests.

jseldess · 2018-03-29T01:46:40Z

v2.0/enable-node-map.md

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


Yes, let's put this as a second code block showing the response:

~~~ Build Tag: {{page.release_info.version}} Build Time: {{page.release_info.build_time}} Distribution: CCL Platform: darwin amd64 Go Version: go1.8.3 C Compiler: 4.2.1 Compatible Clang 3.8.0 (tags/RELEASE_380/final) Build SHA-1: 5b757262d33d814bda1deb2af20161a1f7749df3 Build Type: release ~~~

jseldess · 2018-03-29T01:48:20Z

v2.0/enable-node-map.md

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


Following that, I'd write out the sentence a bit more explicitly, e.g.:

If any node is running an earlier version, upgrade it to CockroachDB v2.0.

jseldess · 2018-03-29T01:49:38Z

v2.0/enable-node-map.md

+To start a new cluster with the correct `--locality` flags:
+
+In a new terminal, start Node 1:


Remove "In a new terminal" for each of the node commands. You'd be running these on separate machines.

jseldess · 2018-03-29T01:51:44Z

v2.0/enable-node-map.md

+<div id="toc"></div>
+
+## Setting Up and Enabling the Node Map


On another look, I'm fine with leaving this as-is, but let's change the heading to Set Up and Enable the Node Map to match the form of Troubleshoot the Node Map.

jseldess · 2018-03-29T01:53:25Z

v2.0/enable-node-map.md

@@ -1,7 +1,200 @@
 ---
-title: Enable the Node Map
+title: Enable the Node Map (Enterprise)


Just realized that we don't put (Enterprise) in the title for BACKUP/RESTORE. Let's also remove that from this page as well as the Table Partitioning page. However, please leave it in the sidenav and in the callouts.

Removed from this page. Made a note to remove from the partitioning doc.

jseldess · 2018-03-29T01:57:44Z

v2.0/enable-node-map.md

+### **Capacity Used** Value Displayed is More Than Configured Capacity
+
+If you are running multiple nodes on a single machine (not recommended), the **Capacity Used** 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** value is then displayed as the hard disk capacity used multiplied by the number of nodes on the machine.


Rich created an include with this message. Let's use it here: https://github.com/cockroachdb/docs/blob/master/_includes/available-capacity-metric.md

However, I'd like you to make a few minor changes to the include content to make it work in all contexts.

Instead of:

the Capacity Used metric in the Summary panel and the available capacity shown in the Capacity graph in the Admin UI are incorrect.

Please use:

capacity metrics in the Admin UI are incorrect.

jseldess · 2018-03-29T01:58:47Z

v2.0/enable-node-map.md

+
+|  Location | SQL Statement |  
+|  ------ | ------ | ------ | ------ |


There are two extra columns here.

Gah..fixed.

jseldess · 2018-03-29T02:01:59Z

v2.0/enable-node-map.md

Add the "new in v2.0" callout to the beginning of this paragraph. Please do that same on the Table Partitioning page.

Added to this doc. Made note to add it to the partitioning PR.

jseldess · 2018-03-29T02:06:48Z

After your final edits, it'd be great if you could squash all of your commits down into one. It should be as easy as:

Make sure your master is up-to-date.
git rebase -i master
Press i.
For all commits but the first, change pick to f.
Press esc then shift + : then wq! then enter.

We can do this together tomorrow, if you prefer.

cockroach-teamcity · 2018-03-29T16:18:12Z

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

cockroach-teamcity · 2018-03-29T16:35:34Z

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

cockroach-teamcity · 2018-03-29T16:43:34Z

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

Amruta-Ranade requested review from jseldess, vilterp and couchand March 24, 2018 17:35

jseldess suggested changes Mar 25, 2018

View reviewed changes

Amruta-Ranade commented Mar 27, 2018

View reviewed changes

couchand approved these changes Mar 28, 2018

View reviewed changes

couchand reviewed Mar 28, 2018

View reviewed changes

jseldess reviewed Mar 28, 2018

View reviewed changes

Amruta-Ranade force-pushed the enable_node_map branch from c67f1c7 to 9d8c55c Compare March 28, 2018 23:24

jseldess approved these changes Mar 29, 2018

View reviewed changes

jseldess changed the title ~~[WIP] Enable Node Map doc~~ Enable Node Map doc Mar 29, 2018

Added content for node map

c437b19

Amruta-Ranade force-pushed the enable_node_map branch from 05a1aa9 to c437b19 Compare March 29, 2018 16:33

Fixed formatting + nits

4fccb57

Amruta-Ranade merged commit 53eadd7 into master Mar 29, 2018

Amruta-Ranade deleted the enable_node_map branch March 29, 2018 16:45

Amruta-Ranade mentioned this pull request Mar 29, 2018

Cluster Visualization: General Overview #2033

Closed

		### Step 5. View the Node Map

		[Navigate to the Overview page](admin-ui-overview.html) to view the Node Map.

		<div id="toc"></div>

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

		{{site.data.alerts.callout_info}}The <b>Node Map</b> won't be displayed until <i>all</i> nodes are started with the correct <code>--locality</code> flags and all localities are assigned the corresponding latitudes and longitudes. {{site.data.alerts.end}}

		## Example

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

		### Step 2. Start (or Restart) the Nodes with the Correct `--locality` Flags

		To get the latitudes and longitudes of common AWS/Azure/GC regions, see [Locations Coordinates for Reference](#location-coordinates-for-reference).

		### Step 5. View the Node Map

		~~~

		Insert the latitudes and longitudes of each region into the `system.locations` table:

		### Step 2. Start (or Restart) the Nodes with the Correct `--locality` Flags

		If you have a cluster running without the `--locality` flags set, restart the nodes with the correct `--locality` flags(add link to rolling restart page once it's created).

		This page walks you through the process of setting up and enabling the Node Map.

		{{site.data.alerts.callout_info}}The <b>Node Map</b> is an <a href="enterprise-licensing.html">enterprise-only</a> feature. However, you can <a href="https://www.cockroachlabs.com/pricing/request-a-license/">request a trial license</a> to enable the <b>Node Map</b>. {{site.data.alerts.end}}

		### Step 5. View the Node Map

		[Open the Overview page](admin-ui-overview.html) and select Node Map from the View drop-down menu to view the Node Map.

		### Step 6. Navigate the Node Map

		Let's say you want to navigate to Node 2, which is in datacenter `us-east-1a` in the `us-east-1` region. To navigate to Node 2:

		Let's say you want to navigate to Node 2, which is in datacenter `us-east-1a` in the `us-east-1` region. To navigate to Node 2:

		1. Click on map component marked as region=us-east-1 on the Node Map. The datacenter view is displayed.

		### Unable to Assign Latitude/Longitude Coordinates to Localities

		You won't be able to assign latitude/longitude coordinates to localities is if the components of your localities have the same name. For example, consider the following partial configuration:

		The Node Map is displayed only for the locality levels that have latitude/longitude coordinates assigned to them:

		- If you assign the latitude/longitude coordinates at the region level, the Node Map shows the regions on the world map. However, when you drill down to the datacenter and further to the individual nodes level, the world map disappears and the datacenters/nodes are be plotted in a circular layout.

		## Location Coordinates for Reference

		\| Location \| SQL Statement \|

		To start a new cluster with the correct `--locality` flags:

		In a new terminal, start Node 1:

		### Capacity Used Value Displayed is More Than Configured Capacity

		If you are running multiple nodes on a single machine (not recommended), the Capacity Used 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 value is then displayed as the hard disk capacity used multiplied by the number of nodes on the machine.


		\| Location \| SQL Statement \|
		\| ------ \| ------ \| ------ \| ------ \|

Enable Node Map doc #2775

Enable Node Map doc #2775

Conversation

Amruta-Ranade commented Mar 24, 2018 • edited Loading

cockroach-teamcity commented Mar 24, 2018

cockroach-teamcity commented Mar 24, 2018

cockroach-teamcity commented Mar 24, 2018

cockroach-teamcity commented Mar 24, 2018

jseldess 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 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cockroach-teamcity commented Mar 28, 2018

couchand 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

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

jseldess 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

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 28, 2018

cockroach-teamcity commented Mar 28, 2018

cockroach-teamcity commented Mar 28, 2018

cockroach-teamcity commented Mar 28, 2018

jseldess 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

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

jseldess commented Mar 29, 2018

cockroach-teamcity commented Mar 29, 2018

cockroach-teamcity commented Mar 29, 2018

Amruta-Ranade commented Mar 24, 2018 •

edited

Loading