Diagnostics reporting and global settings

_data/sidebar_doc.yml

@@ -426,6 +426,9 @@ entries:
                   url: /orchestrate-cockroachdb-with-docker-swarm.html
                   alternate_urls: [/orchestrate-cockroachdb-with-docker-swarm-insecure.html]
 
+        - title: Cluster Settings
+          url: /cluster-settings.html
+
         - title: Cockroach Commands
           url: /cockroach-commands.html
 
@@ -474,6 +477,9 @@ entries:
         - title: Generate CockroachDB Resources
           url: /generate-cockroachdb-resources.html
 
+        - title: Diagnostics Reporting
+          url: /diagnostics-reporting.html
+
         - title: Troubleshoot
           url: /troubleshoot.html
 

cluster-settings.md

@@ -0,0 +1,68 @@
+---
+title: Cluster Settings
+summary: Learn about cluster settings that apply to all nodes of a CockroachDB cluster.
+toc: false
+---
+
+This page shows you how to view and change CockroachDB's **cluster-wide settings**. These settings apply to all nodes of a CockroachDB cluster and control, for example, whether or not to share diagnostic details with Cockroach Labs as well as advanced options for debugging and cluster tuning. They are defined via `SET CLUSTER SETTING` SQL statements and can be updated anytime after a cluster has been started, but only by the `root` user.
+
+{{site.data.alerts.callout_info}}In contrast to cluster-wide settings, node-level settings apply to a single node. They are defined by flags passed to the <code>cockroach start</code> command when starting a node and cannot be changed without stopping and restarting the node. For more details, see <a href="start-a-node.html">Start a Node</a>.{{site.data.alerts.end}}
+
+<div id="toc"></div>
+
+<!-- Add this section back in once `system.settings` has been fleshed out.
+
+## Settings
+
+types:
+
+settings-registry.go
+
+s = string
+b = boolean
+i = int
+f = float
+d = duration
+z = byte-size (can set them with set cluster setting = 32 MiB)
+
+-->
+
+## View Current Cluster Settings
+
+To view the current settings for a running cluster:
+
+1. 	Connect [the built-in SQL client](use-the-built-in-sql-client.html) to any node of the cluster.
+
+2. 	Execute the `SHOW ALL CLUSTER SETTINGS` statement:
+
+	~~~ sql
+	> SHOW ALL CLUSTER SETTINGS;
+	~~~
+
+## Change a Cluster Setting
+
+Before changing a cluster setting, please note the following:
+
+- 	{{site.data.alerts.callout_danger}}Many cluster settings are intended for tuning CockroachDB internals. Before changing these settings, we strongly encourage you to discuss your goals with CockroachDB; otherwise, you use them at your own risk.{{site.data.alerts.end}}
+
+-	Only the `root` user has privileges to change cluster settings with `SET CLUSTER SETTING`.
+
+- 	Changing a cluster setting is not instantaneous, as the change must be propagated to other nodes in the cluster.
+
+- 	It's not recommended to change cluster settings while upgrading to a new version of CockroachDB (docs on online cluster upgrades coming soon); wait until all nodes have been upgraded and then make the change.
+
+To change a setting for a running cluster:
+
+1.	Connect the [built-in SQL client](use-the-built-in-sql-client.html) to any node of the cluster.
+
+2.	Execute the `SET CLUSTER SETTING` statement with the relevant setting name and value:
+
+	~~~ sql
+	> SET CLUSTER SETTING <setting name> = <setting value>;
+	~~~
+
+## See Also
+
+- [Diagnostics Reporting](diagnostics-reporting.html)
+- [Start a Node](start-a-node.html)
+- [Use the Built-in SQL Client](use-the-built-in-sql-client.html)

diagnostics-reporting.md

@@ -0,0 +1,128 @@
+---
+title: Diagnostics Reporting
+summary: Learn about the diagnostic details that get shared with CockroachDB and how to opt out of sharing.
+toc: false
+---
+
+By default, each node of a CockroachDB cluster shares diagnostic details with Cockroach Labs on a daily basis. These details, which are completely scrubbed of identifiable information, greatly help us understand and improve how the system behaves in real-world scenarios.
+
+This page explains the details that get shared and how to opt out of sharing.
+
+{{site.data.alerts.callout_success}}For insights into your cluster's performance and health, use the built-in <a href="explore-the-admin-ui.html">Admin UI</a> or a third-party monitoring tool like <a href="monitor-cockroachdb-with-prometheus.html">Prometheus</a>.{{site.data.alerts.end}}
+
+<div id="toc"></div>
+
+## What Gets Shared
+
+When diagnostics reporting is on, each node of a CockroachDB cluster shares anonymized storage and table structure details with Cockroach Labs on a daily basis. Please note that the details that get shared may change over time, but as that happens, we will update this page and announce the changes in release notes.
+
+### Storage Details
+
+Each node of a CockroachDB cluster shares the following storage details:
+
+Detail | Description
+-------|------------
+Node ID | The internal ID of the node.
+Store ID | The internal ID of each store on the node.
+Bytes | The amount of live data used by applications and the CockroachDB system on the node and per store. This excludes historical and deleted data.
+Range Count | The number of ranges on the node and per store.
+Key Count | The number of keys stored on the node and per store.
+
+#### Example
+
+This JSON example shows what storage details look like when sent to Cockroach Labs, in this case for a node with two stores.
+
+~~~ json
+{
+   "node":{
+      "node_id":1,
+      "bytes":64828,
+      "key_count":138,
+      "range_count":12
+   },
+   "stores":[
+      {
+         "node_id":1,
+         "store_id":1,
+         "bytes":64828,
+         "key_count":138,
+         "range_count":12
+      },
+      {
+         "node_id":1,
+         "store_id":2,
+         "bytes":0,
+         "key_count":0,
+         "range_count":0
+      }
+   ]
+}
+~~~
+
+### SQL Table Structure
+
+Each node of a CockroachDB cluster shares the following details about the structure of each table stored on the node:
+
+{{site.data.alerts.callout_info}}No actual table data or table/column names are shared, just metadata about the structure of tables. All names and other string values are scrubbed and replaced with underscores.{{site.data.alerts.end}}
+
+Detail | Description
+-------|------------
+Table | Metadata about each table, such as its internal ID, when it was last modified, and how many times it has been renamed. Table names are replaced with underscores.
+Column | Metadata about each column in a table, such as its internal ID and type. Column names are replaced with undescores.
+Column Families | Metadata about [column families](column-families.html) in a table, such as its internal ID and the columns included in the family. Family and column names are replaced with underscores.
+Indexes | Metadata about the primary index and any secondary indexes on the table, such as the internal ID of an index and the columns covered by an index. All index, column, and other strings are replaced with underscores.
+Privileges | Metadata about user [privileges](privileges.html) on the table, such as the number of privileges granted to each user. Usernames are replaced with underscores.
+Checks | Metadata about any [check constraints](check.html) on the table. Check constraint names and expressions are replaced with underscores.
+
+#### Example
+
+This JSON example shows an excerpt of what table structure details look like when sent to Cockroach Labs, in this case for a node with just one table. Note that all names and other strings have been scrubbed and replaced with underscores.
+
+~~~ json
+{
+   "schema":[
+      {
+         "name":"_",
+         "id":51,
+         "parent_id":50,
+         "version":1,
+         "up_version":false,
+         "modification_time":{
+            "wall_time":0,
+            "logical":0
+         },
+         "columns":[
+            {
+               "name":"_",
+               "id":1,
+               "type":{
+                  "kind":1,
+                  "width":0,
+                  "precision":0
+               },
+               "nullable":true,
+               "default_expr":"_",
+               "hidden":false
+            },
+            ...
+         ],
+         ...
+      }
+   ]
+}
+~~~
+
+## Opt Out of Diagnostics Reporting
+
+To stop sending diagnostic details to Cockroach Labs once a cluster is running, [use the built-in SQL client](use-the-built-in-sql-client.html) to execute the following `SET CLUSTER SETTING` statement, which switches the `diagnostics.reporting.enabled` [cluster setting](cluster-settings.html) to `false`:
+
+~~~ sql
+> SET CLUSTER SETTING diagnostics.reporting.enabled = false;
+~~~
+
+This change will not be instantaneous, as it must be propagated to other nodes in the cluster. If you want to make sure that no diagnostic details are shared, you can set the environment variable `COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING=true` before starting the first node of the cluster. Note that this works only when set before starting the first node of the cluster. Once the cluster is running, you need to use the `SET` method described above.
+
+## See Also
+
+- [Cluster Settings](cluster-settings.html)
+- [Start a Node](start-a-node.html)

show-all.md

@@ -1,10 +1,12 @@
 ---
 title: SHOW ALL
-summary: The SHOW ALL statement lists all current run-time settings. 
+summary: The SHOW ALL statement lists all run-time settings for the current session.
 toc: false
 ---
 
-The `SHOW ALL` [statement](sql-statements.html) lists all current run-time settings.
+The `SHOW ALL` [statement](sql-statements.html) lists all run-time settings for the current session.
+
+{{site.data.alerts.callout_success}}For details about cluster settings that apply across all nodes in a cluster, see <a href="cluster-settings.html">Cluster Settings</a>.{{site.data.alerts.end}}
 
 <div id="toc"></div>
 
@@ -22,8 +24,8 @@ The following run-time variables are returned by `SHOW ALL`:
 
 Variable | Description
 ------|------------
-`DATABASE` | The default database for the current session, as set by [`SET DATABASE`](set-database.html) or the client's connection string. This variable can be viewed with [`SHOW DATABASE`](show-database.html) as well. 
-`DEFAULT_TRANSACTION_ISOLATION` | The default transaction isolation level for the current session, as set by `SET DEFAULT_TRANSACTION_ISOLATION` or the client's connection string. 
+`DATABASE` | The default database for the current session, as set by [`SET DATABASE`](set-database.html) or the client's connection string. This variable can be viewed with [`SHOW DATABASE`](show-database.html) as well.
+`DEFAULT_TRANSACTION_ISOLATION` | The default transaction isolation level for the current session, as set by `SET DEFAULT_TRANSACTION_ISOLATION` or the client's connection string.
 `MAX_INDEX_KEYS` | Not usable; exposed only for ORM compatibility.
 `SEARCH_PATH` | A list of databases or namespaces that will be searched to resolve unqualified table or function names, as set by `SET SEARCH_PATH`. This variable can be viewed with `SHOW SEARCH_PATH` as well. For more details, see [Name Resolution](sql-name-resolution.html).
 `SERVER_VERSION` | The version of PostgreSQL that CockroachDB emulates.

sql-statements.md

@@ -87,6 +87,13 @@ Statement | Usage
 [`SHOW TIME ZONE`](show-time-zone.html) | View the default time zone for the session.
 [`SHOW TRANSACTION`](show-transaction.html) | View the isolation level or priority for the session or for an individual [transaction](transactions.html).
 
+## Cluster Management Statements
+
+Statement | Usage
+----------|------------
+[`SHOW ALL CLUSTER SETTINGS`](cluster-settings.html#view-current-cluster-settings) | List the current cluster-wide settings.
+[`SET CLUSTER SETTING`](cluster-settings.html#change-a-cluster-setting) | Set a cluster-wide setting.
+
 ## Backup & Restore Statements (Enterprise)
 
 The following statements are availably only to [enterprise license](https://www.cockroachlabs.com/pricing/) users.
@@ -97,5 +104,3 @@ Statement | Usage
 ----------|------------
 [`BACKUP`](backup.html) | Create disaster recovery backups of databases and tables.
 [`RESTORE`](restore.html) | Restore databases and tables using your backups.
-
-

start-a-node.md

@@ -6,6 +6,8 @@ toc: false
 
 To start a new CockroachDB cluster, or add a node to an existing cluster, run the `cockroach start` [command](cockroach-commands.html) with appropriate flags.
 
+{{site.data.alerts.callout_info}}Node-level settings are defined by flags passed to the <code>cockroach start</code> command and cannot be changed without stopping and restarting the node. In contrast, some cluster-wide settings are defined via SQL statements and can be updated anytime after a cluster has been started. For more details, see <a href="cluster-settings.html">Cluster Settings</a>.{{site.data.alerts.end}}
+
 <div id="toc"></div>
 
 ## Synopsis