schematelemetry: add job, schedule, controller and executor

This commit adds all the boilerplate for automatically scheduling SQL
schema telemetry jobs, by default on a daily basis.

This commit also adds a couple of builtins to create the job schedule
and also to immediately create a schema telemetry logging job.

Fixes cockroachdb#84284.

Release note (sql change): this change ensures the existence of
a new scheduled job for collecting SQL schema telemetry. By default it
runs daily but this can be adjusted via the
sql.schema.telemetry.recurrence cluster setting. The schedule can also
be paused via PAUSE SCHEDULE followed by its ID, which can be retrieved
by SELECT * FROM [SHOW SCHEDULES] WHERE label = 'sql-schema-telemetry'.

docs/generated/settings/settings-for-tenants.txt

@@ -248,6 +248,8 @@ sql.multiple_modifications_of_table.enabled boolean false if true, allow stateme
 sql.multiregion.drop_primary_region.enabled boolean true allows dropping the PRIMARY REGION of a database if it is the last region
 sql.notices.enabled boolean true enable notices in the server/client protocol being sent
 sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled boolean false if enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probability
+sql.schema.telemetry.recurrence string @daily cron-tab recurrence for SQL schema telemetry job
+sql.schema_telemetry.job.enabled boolean true whether the schema telemetry job is enabled
 sql.spatial.experimental_box2d_comparison_operators.enabled boolean false enables the use of certain experimental box2d comparison operators
 sql.stats.automatic_collection.enabled boolean true automatic statistics collection mode
 sql.stats.automatic_collection.fraction_stale_rows float 0.2 target fraction of stale rows per table that will trigger a statistics refresh

docs/generated/settings/settings.html

@@ -179,6 +179,8 @@
 <tr><td><code>sql.multiregion.drop_primary_region.enabled</code></td><td>boolean</td><td><code>true</code></td><td>allows dropping the PRIMARY REGION of a database if it is the last region</td></tr>
 <tr><td><code>sql.notices.enabled</code></td><td>boolean</td><td><code>true</code></td><td>enable notices in the server/client protocol being sent</td></tr>
 <tr><td><code>sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled</code></td><td>boolean</td><td><code>false</code></td><td>if enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probability</td></tr>
+<tr><td><code>sql.schema.telemetry.recurrence</code></td><td>string</td><td><code>@daily</code></td><td>cron-tab recurrence for SQL schema telemetry job</td></tr>
+<tr><td><code>sql.schema_telemetry.job.enabled</code></td><td>boolean</td><td><code>true</code></td><td>whether the schema telemetry job is enabled</td></tr>
 <tr><td><code>sql.spatial.experimental_box2d_comparison_operators.enabled</code></td><td>boolean</td><td><code>false</code></td><td>enables the use of certain experimental box2d comparison operators</td></tr>
 <tr><td><code>sql.stats.automatic_collection.enabled</code></td><td>boolean</td><td><code>true</code></td><td>automatic statistics collection mode</td></tr>
 <tr><td><code>sql.stats.automatic_collection.fraction_stale_rows</code></td><td>float</td><td><code>0.2</code></td><td>target fraction of stale rows per table that will trigger a statistics refresh</td></tr>

docs/generated/sql/functions.md

@@ -3023,6 +3023,8 @@ SELECT * FROM crdb_internal.check_consistency(true, ‘\x02’, ‘\x04’)</p>
 </span></td><td>Volatile</td></tr>
 <tr><td><a name="crdb_internal.create_session_revival_token"></a><code>crdb_internal.create_session_revival_token() &rarr; <a href="bytes.html">bytes</a></code></td><td><span class="funcdesc"><p>Generate a token that can be used to create a new session for the current user.</p>
 </span></td><td>Volatile</td></tr>
+<tr><td><a name="crdb_internal.create_sql_schema_telemetry_job"></a><code>crdb_internal.create_sql_schema_telemetry_job() &rarr; <a href="int.html">int</a></code></td><td><span class="funcdesc"><p>This function is used to create a schema telemetry job instance.</p>
+</span></td><td>Volatile</td></tr>
 <tr><td><a name="crdb_internal.decode_cluster_setting"></a><code>crdb_internal.decode_cluster_setting(setting: <a href="string.html">string</a>, value: <a href="string.html">string</a>) &rarr; <a href="string.html">string</a></code></td><td><span class="funcdesc"><p>Decodes the given encoded value for a cluster setting.</p>
 </span></td><td>Immutable</td></tr>
 <tr><td><a name="crdb_internal.deserialize_session"></a><code>crdb_internal.deserialize_session(session: <a href="bytes.html">bytes</a>) &rarr; <a href="bool.html">bool</a></code></td><td><span class="funcdesc"><p>This function deserializes the serialized variables into the current session.</p>
@@ -3120,6 +3122,8 @@ table. Returns an error if validation fails.</p>
 </span></td><td>Immutable</td></tr>
 <tr><td><a name="crdb_internal.round_decimal_values"></a><code>crdb_internal.round_decimal_values(val: <a href="decimal.html">decimal</a>[], scale: <a href="int.html">int</a>) &rarr; <a href="decimal.html">decimal</a>[]</code></td><td><span class="funcdesc"><p>This function is used internally to round decimal array values during mutations.</p>
 </span></td><td>Stable</td></tr>
+<tr><td><a name="crdb_internal.schedule_sql_schema_telemetry"></a><code>crdb_internal.schedule_sql_schema_telemetry() &rarr; <a href="bool.html">bool</a></code></td><td><span class="funcdesc"><p>This function is used to create the schema telemetry job schedule.</p>
+</span></td><td>Volatile</td></tr>
 <tr><td><a name="crdb_internal.schedule_sql_stats_compaction"></a><code>crdb_internal.schedule_sql_stats_compaction() &rarr; <a href="bool.html">bool</a></code></td><td><span class="funcdesc"><p>This function is used to start a SQL stats compaction job.</p>
 </span></td><td>Volatile</td></tr>
 <tr><td><a name="crdb_internal.serialize_session"></a><code>crdb_internal.serialize_session() &rarr; <a href="bytes.html">bytes</a></code></td><td><span class="funcdesc"><p>This function serializes the variables in the current session.</p>

pkg/BUILD.bazel

@@ -255,6 +255,7 @@ ALL_TESTS = [
  "//pkg/sql/catalog/resolver:resolver_test",
  "//pkg/sql/catalog/schemadesc:schemadesc_test",
  "//pkg/sql/catalog/schemaexpr:schemaexpr_test",
+ "//pkg/sql/catalog/schematelemetry:schematelemetry_test",
  "//pkg/sql/catalog/seqexpr:seqexpr_disallowed_imports_test",
  "//pkg/sql/catalog/seqexpr:seqexpr_test",
  "//pkg/sql/catalog/systemschema_test:systemschema_test_test",
@@ -1247,6 +1248,9 @@ GO_TARGETS = [
  "//pkg/sql/catalog/schemadesc:schemadesc_test",
  "//pkg/sql/catalog/schemaexpr:schemaexpr",
  "//pkg/sql/catalog/schemaexpr:schemaexpr_test",
+ "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller:schematelemetrycontroller",
+ "//pkg/sql/catalog/schematelemetry:schematelemetry",
+ "//pkg/sql/catalog/schematelemetry:schematelemetry_test",
  "//pkg/sql/catalog/seqexpr:seqexpr",
  "//pkg/sql/catalog/seqexpr:seqexpr_test",
  "//pkg/sql/catalog/systemschema:systemschema",
@@ -2351,6 +2355,8 @@ GET_X_DATA_TARGETS = [
  "//pkg/sql/catalog/rewrite:get_x_data",
  "//pkg/sql/catalog/schemadesc:get_x_data",
  "//pkg/sql/catalog/schemaexpr:get_x_data",
+ "//pkg/sql/catalog/schematelemetry:get_x_data",
+ "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller:get_x_data",
  "//pkg/sql/catalog/seqexpr:get_x_data",
  "//pkg/sql/catalog/systemschema:get_x_data",
  "//pkg/sql/catalog/systemschema_test:get_x_data",

pkg/base/testing_knobs.go

@@ -38,6 +38,7 @@ type TestingKnobs struct {
  JobsTestingKnobs ModuleTestingKnobs
  BackupRestore ModuleTestingKnobs
  TTL ModuleTestingKnobs
+ SchemaTelemetry ModuleTestingKnobs
  Streaming ModuleTestingKnobs
  UpgradeManager ModuleTestingKnobs
  IndexUsageStatsKnobs ModuleTestingKnobs

pkg/clusterversion/cockroach_versions.go

@@ -331,6 +331,9 @@ const (
  AlterSystemSQLInstancesAddLocality
  // SystemExternalConnectionsTable adds system.external_connections table.
  SystemExternalConnectionsTable
+ // SQLSchemaTelemetryScheduledJobs adds an automatic schedule for SQL schema
+ // telemetry logging jobs.
+ SQLSchemaTelemetryScheduledJobs
 
  // *************************************************
  // Step (1): Add new versions here.
@@ -572,6 +575,10 @@ var versionsSingleton = keyedVersions{
  Key: SystemExternalConnectionsTable,
  Version: roachpb.Version{Major: 22, Minor: 1, Internal: 30},
  },
+ {
+ Key: SQLSchemaTelemetryScheduledJobs,
+ Version: roachpb.Version{Major: 22, Minor: 1, Internal: 32},
+ },
 
  // *************************************************
  // Step (2): Add new versions here.

pkg/gen/protobuf.bzl

@@ -38,6 +38,7 @@ PROTOBUF_SRCS = [
  "//pkg/settings:settings_go_proto",
  "//pkg/sql/catalog/catpb:catpb_go_proto",
  "//pkg/sql/catalog/descpb:descpb_go_proto",
+ "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller:schematelemetrycontroller_go_proto",
  "//pkg/sql/contentionpb:contentionpb_go_proto",
  "//pkg/sql/execinfrapb:execinfrapb_go_proto",
  "//pkg/sql/inverted:inverted_go_proto",

pkg/server/BUILD.bazel

@@ -162,6 +162,7 @@ go_library(
  "//pkg/sql/catalog/descs",
  "//pkg/sql/catalog/hydratedtables",
  "//pkg/sql/catalog/lease",
+ "//pkg/sql/catalog/schematelemetry",
  "//pkg/sql/catalog/systemschema",
  "//pkg/sql/clusterunique",
  "//pkg/sql/colexec",

pkg/server/server.go

@@ -60,6 +60,7 @@ import (
  "github.com/cockroachdb/cockroach/pkg/spanconfig/spanconfigkvsubscriber"
  "github.com/cockroachdb/cockroach/pkg/spanconfig/spanconfigptsreader"
  "github.com/cockroachdb/cockroach/pkg/sql"
+ _ "github.com/cockroachdb/cockroach/pkg/sql/catalog/schematelemetry" // register schedules declared outside of pkg/sql
  "github.com/cockroachdb/cockroach/pkg/sql/catalog/systemschema"
  "github.com/cockroachdb/cockroach/pkg/sql/flowinfra"
  _ "github.com/cockroachdb/cockroach/pkg/sql/gcjob" // register jobs declared outside of pkg/sql

pkg/server/server_sql.go

@@ -873,6 +873,9 @@ func newSQLServer(ctx context.Context, cfg sqlServerArgs) (*SQLServer, error) {
  if ttlKnobs := cfg.TestingKnobs.TTL; ttlKnobs != nil {
  execCfg.TTLTestingKnobs = ttlKnobs.(*sql.TTLTestingKnobs)
  }
+ if schemaTelemetryKnobs := cfg.TestingKnobs.SchemaTelemetry; schemaTelemetryKnobs != nil {
+ execCfg.SchemaTelemetryTestingKnobs = schemaTelemetryKnobs.(*sql.SchemaTelemetryTestingKnobs)
+ }
  if sqlStatsKnobs := cfg.TestingKnobs.SQLStatsKnobs; sqlStatsKnobs != nil {
  execCfg.SQLStatsTestingKnobs = sqlStatsKnobs.(*sqlstats.TestingKnobs)
  }
@@ -913,6 +916,7 @@ func newSQLServer(ctx context.Context, cfg sqlServerArgs) (*SQLServer, error) {
  )
 
  distSQLServer.ServerConfig.SQLStatsController = pgServer.SQLServer.GetSQLStatsController()
+ distSQLServer.ServerConfig.SchemaTelemetryController = pgServer.SQLServer.GetSchemaTelemetryController()
  distSQLServer.ServerConfig.IndexUsageStatsController = pgServer.SQLServer.GetIndexUsageStatsController()
 
  // We use one BytesMonitor for all InternalExecutor's created by the

pkg/sql/BUILD.bazel

@@ -320,6 +320,7 @@ go_library(
  "//pkg/sql/catalog/resolver",
  "//pkg/sql/catalog/schemadesc",
  "//pkg/sql/catalog/schemaexpr",
+ "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller",
  "//pkg/sql/catalog/seqexpr",
  "//pkg/sql/catalog/systemschema",
  "//pkg/sql/catalog/tabledesc",

pkg/sql/catalog/schematelemetry/BUILD.bazel

@@ -0,0 +1,62 @@
+load("//build/bazelutil/unused_checker:unused.bzl", "get_x_data")
+load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+ name = "schematelemetry",
+ srcs = [
+ "scheduled_job_executor.go",
+ "schema_telemetry_event.go",
+ "schema_telemetry_job.go",
+ ],
+ importpath = "github.com/cockroachdb/cockroach/pkg/sql/catalog/schematelemetry",
+ visibility = ["//visibility:public"],
+ deps = [
+ "//pkg/jobs",
+ "//pkg/jobs/jobspb",
+ "//pkg/kv",
+ "//pkg/scheduledjobs",
+ "//pkg/security/username",
+ "//pkg/server/telemetry",
+ "//pkg/settings",
+ "//pkg/settings/cluster",
+ "//pkg/sql",
+ "//pkg/sql/catalog/descs",
+ "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller",
+ "//pkg/sql/sem/tree",
+ "//pkg/sql/sqltelemetry",
+ "//pkg/sql/sqlutil",
+ "//pkg/util/hlc",
+ "//pkg/util/log/eventpb",
+ "//pkg/util/metric",
+ "@com_github_cockroachdb_errors//:errors",
+ ],
+)
+
+go_test(
+ name = "schematelemetry_test",
+ srcs = [
+ "main_test.go",
+ "schema_telemetry_test.go",
+ ],
+ deps = [
+ "//pkg/base",
+ "//pkg/jobs",
+ "//pkg/jobs/jobstest",
+ "//pkg/security/securityassets",
+ "//pkg/security/securitytest",
+ "//pkg/server",
+ "//pkg/sql",
+ "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller",
+ "//pkg/sql/sem/builtins/builtinconstants",
+ "//pkg/sql/sem/tree",
+ "//pkg/testutils/serverutils",
+ "//pkg/testutils/sqlutils",
+ "//pkg/testutils/testcluster",
+ "//pkg/util/leaktest",
+ "//pkg/util/log",
+ "//pkg/util/timeutil",
+ "@com_github_stretchr_testify//require",
+ ],
+)
+
+get_x_data(name = "get_x_data")

pkg/sql/catalog/schematelemetry/main_test.go

@@ -0,0 +1,31 @@
+// Copyright 2022 The Cockroach Authors.
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package schematelemetry_test
+
+import (
+ "os"
+ "testing"
+
+ "github.com/cockroachdb/cockroach/pkg/security/securityassets"
+ "github.com/cockroachdb/cockroach/pkg/security/securitytest"
+ "github.com/cockroachdb/cockroach/pkg/server"
+ "github.com/cockroachdb/cockroach/pkg/testutils/serverutils"
+ "github.com/cockroachdb/cockroach/pkg/testutils/testcluster"
+)
+
+//go:generate ../../../util/leaktest/add-leaktest.sh *_test.go
+
+func TestMain(m *testing.M) {
+ securityassets.SetLoader(securitytest.EmbeddedAssets)
+ serverutils.InitTestServerFactory(server.TestServerFactory)
+ serverutils.InitTestClusterFactory(testcluster.TestClusterFactory)
+ os.Exit(m.Run())
+}