Incorporated Mike’s feedback.

florence-crl · florence-crl · commit 0bad9f1de49f · 2025-10-28T16:10:59.000-04:00
diff --git a/src/current/v25.4/configure-logs.md b/src/current/v25.4/configure-logs.md
@@ -16,9 +16,9 @@ This page describes how to configure CockroachDB logs with the [`--log` or `log-
 For examples of how these settings can be used in practice, see [Logging Use Cases]({% link {{ page.version.version }}/logging-use-cases.md %}).
 
 {{site.data.alerts.callout_info}}
-In a future release, certain events will be directed to new [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels). For more details, refer to [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled).
+In a future major release, certain events will be directed by default to new [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels).
 
-To assess potential downstream impacts on your logging setup and pipelines, set the `log.channel_compatibility_mode.enabled` cluster setting to `false` in a non-production environment.
+To prepare for the change and assess potential downstream impacts on your logging setup and pipelines, review the [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled) cluster setting. After reviewing the documentation, set `log.channel_compatibility_mode.enabled` to `false` in a non-production environment.
 {{site.data.alerts.end}}
 
 ## Flag
diff --git a/src/current/v25.4/log-sql-activity-to-datadog.md b/src/current/v25.4/log-sql-activity-to-datadog.md
@@ -8,9 +8,9 @@ docs_area: manage
 This tutorial describes how to configure logging of telemetry events, including [`sampled_query`]({% link {{ page.version.version }}/eventlog.md %}#sampled_query) and [`sampled_transaction`]({% link {{ page.version.version }}/eventlog.md %}#sampled_query), to [Datadog](https://www.datadoghq.com/) for finer granularity and long-term retention of SQL activity. The `sampled_query` and `sampled_transaction` events contain common SQL event and execution details for [statements]({% link {{ page.version.version }}/sql-statements.md %}) and [transactions]({% link {{ page.version.version }}/transactions.md %}).
 
 {{site.data.alerts.callout_info}}
-`sampled_query` and `sampled_transaction` events currently sent to the [`TELEMETRY`]({% link {{ page.version.version }}/logging-overview.md %}#telemetry) channel will be routed to the [`SQL_EXEC`]({% link {{ page.version.version }}/logging-overview.md %}#sql_exec) channel in a future release.
+`sampled_query` and `sampled_transaction` events, which are sent by default to the [`TELEMETRY`]({% link {{ page.version.version }}/logging-overview.md %}#telemetry) channel in {{ page.version.version }} and earlier versions, will instead be routed by default to the [`SQL_EXEC`]({% link {{ page.version.version }}/logging-overview.md %}#sql_exec) channel in a future major release.
 
-To assess potential downstream impacts on your logging setup and pipelines, set the [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled) cluster setting to `false` in a non-production environment. This will log these events to the [`SQL_EXEC`]({% link {{ page.version.version }}/logging-overview.md %}#sql_exec) channel.
+To prepare for the change and assess potential downstream impacts on your logging setup and pipelines, review the [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled) cluster setting. After reviewing the documentation, set `log.channel_compatibility_mode.enabled` to `false` in a non-production environment to log `sampled_query` and `sampled_transaction` events to the [SQL_EXEC]({% link {{ page.version.version }}/logging-overview.md %}#sql_exec) channel.
 {{site.data.alerts.end}}
 
 CockroachDB supports a built-in integration with Datadog which sends these events as logs via the [Datadog HTTP API](https://docs.datadoghq.com/api/latest/logs/). This integration is the recommended path to achieve high throughput data ingestion, which will in turn provide more query and transaction events for greater workload observability.
diff --git a/src/current/v25.4/logging-overview.md b/src/current/v25.4/logging-overview.md
@@ -30,7 +30,7 @@ This allows you to group channels that log related information (e.g., operationa
 
 | Channel                                             | Description                                                                                                                                                                                                                                                                                                                |
 |-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| <a id="changefeed"></a><span class="version-tag">New in v25.4:</span> [`CHANGEFEED`]({% link {{ page.version.version }}/logging.md %})                | Changefeed events.<br><br>**Note**: [Changefeed telemetry events]({% link {{ page.version.version }}/eventlog.md %}#changefeed-telemetry-events) currently sent to the [`TELEMETRY`](#telemetry) channel will be routed to this channel in a future release.<br>To prepare for that change and assess potential downstream impacts on your logging setup and pipelines, set the [`log.channel_compatibility_mode.enabled`](#log-channel_compatibility_mode-enabled) cluster setting to `false` in a non-production environment. This will log these events to this `CHANGEFEED` channel. |
+| <a id="changefeed"></a><span class="version-tag">New in v25.4:</span> [`CHANGEFEED`]({% link {{ page.version.version }}/logging.md %})                | Changefeed events.<br><br>**Note**: [Changefeed telemetry events]({% link {{ page.version.version }}/eventlog.md %}#changefeed-telemetry-events), which are sent by default to the [`TELEMETRY`](#telemetry) channel in {{ page.version.version }} and earlier versions, will be routed by default to this channel  in a future major release.<br>To prepare for that change and assess potential downstream impacts on your logging setup and pipelines, review the [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled) cluster setting. After reviewing the documentation, set `log.channel_compatibility_mode.enabled` to `false` in a non-production environment to log these events to this `CHANGEFEED` channel. |
 | [`DEV`]({% link {{ page.version.version }}/logging.md %}#dev)                           | Uncategorized and debug messages.                                                                                                                                                                                                                                                                                          |
 | [`KV_DISTRIBUTION`]({% link {{ page.version.version }}/logging.md %}#kv_distribution)   | Data distribution events, such as moving [replicas]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-replica) between [stores]({% link {{ page.version.version }}/cockroach-start.md %}#store) in a cluster, adding replicas to [ranges]({% link {{ page.version.version }}/architecture/overview.md %}#range), and removing replicas from ranges. |
 | <a id="kv_exec"></a><span class="version-tag">New in v25.4:</span> [`KV_EXEC`]({% link {{ page.version.version }}/logging.md %})                   | KV execution events that are not related to distribution.|
@@ -43,7 +43,7 @@ This allows you to group channels that log related information (e.g., operationa
 | <a id="sql_perf"></a>[`SQL_PERF`]({% link {{ page.version.version }}/logging.md %}#sql_perf)                 | SQL executions that impact performance, such as slow queries (enabled via the `sql.log.slow_query.latency_threshold` and `sql.log.slow_query.experimental_full_table_scans.enabled` [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %})).<br><br>**Note**: The `SQL_PERF` and `SQL_INTERNAL_PERF` channels will be removed in a future release. [SQL Slow Query Log]({% link {{ page.version.version }}/eventlog.md %}#sql-slow-query-log) and [SQL Slow Query Log (Internal)]({% link {{ page.version.version }}/eventlog.md %}#sql-slow-query-log-internal) events currently sent to the `SQL_PERF` and [`SQL_INTERNAL_PERF`]({% link {{ page.version.version }}/logging.md %}#sql_internal_perf) channels, respectively, will be routed to the [`SQL_EXEC`](#sql_exec) channel in a future release. Internal queries are tagged as `internal`, allowing users to filter them out downstream.<br><br>To prepare for that change and assess potential downstream impacts on your logging setup and pipelines, set the [`log.channel_compatibility_mode.enabled`](#log-channel_compatibility_mode-enabled) cluster setting to `false` in a non-production environment. This logs these events to the [`SQL_EXEC`](#sql_exec) channel. |
 | [`SQL_SCHEMA`]({% link {{ page.version.version }}/logging.md %}#sql_schema)             | Database, schema, table, sequence, view, and type creation; changes to table columns and sequence parameters.                                                                                                                                                                                                              |
 | [`STORAGE`]({% link {{ page.version.version }}/logging.md %}#storage)                   | Low-level storage logs from the [Pebble storage engine]({% link {{ page.version.version }}/architecture/storage-layer.md %}#pebble).                                                                                                                                                                                                                           |
-| <a id="telemetry"></a>[`TELEMETRY`]({% link {{ page.version.version }}/logging.md %}#telemetry)               | Telemetry events for internal usage, except for [`sampled_query`]({% link {{ page.version.version }}/eventlog.md %}#sampled_query) and [`sampled_transaction`]({% link {{ page.version.version }}/eventlog.md %}#sampled_transaction) events which may be [logged externally to Datadog]({% link {{ page.version.version }}/log-sql-activity-to-datadog.md %}).<br><br>**Note**: `sampled_query` and `sampled_transaction` events currently sent to this channel will be routed to the [`SQL_EXEC`](#sql_exec) channel in a future release. [Changefeed telemetry events]({% link {{ page.version.version }}/eventlog.md %}#changefeed-telemetry-events) currently sent to this channel will be routed to the [`CHANGEFEED`](#changefeed) channel in a future release.<br>To prepare for that change and assess potential downstream impacts on your logging setup and pipelines, set the [`log.channel_compatibility_mode.enabled`](#log-channel_compatibility_mode-enabled) cluster setting to `false` in a non-production environment. This will log these events to the [`SQL_EXEC`](#sql_exec) channel. |
+| <a id="telemetry"></a>[`TELEMETRY`]({% link {{ page.version.version }}/logging.md %}#telemetry)               | Telemetry events for internal usage, except for [`sampled_query`]({% link {{ page.version.version }}/eventlog.md %}#sampled_query) and [`sampled_transaction`]({% link {{ page.version.version }}/eventlog.md %}#sampled_transaction) events which may be [logged externally to Datadog]({% link {{ page.version.version }}/log-sql-activity-to-datadog.md %}).<br><br>**Note**: `sampled_query` and `sampled_transaction` events, which are sent by default to this channel in {{ page.version.version }} and earlier versions, will instead be routed by default to the [`SQL_EXEC`](#sql_exec) channel in a future major release. [Changefeed telemetry events]({% link {{ page.version.version }}/eventlog.md %}#changefeed-telemetry-events), which are sent by default to this channel in {{ page.version.version }} and earlier versions, will instead be routed by default to the [`CHANGEFEED`](#changefeed) channel in a future major release.<br>To prepare for these changes and assess potential downstream impacts on your logging setup and pipelines, review the [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled) cluster setting. After reviewing the documentation, set `log.channel_compatibility_mode.enabled` to `false` in a non-production environment to log these events to their new channels. |
 | [`USER_ADMIN`]({% link {{ page.version.version }}/logging.md %}#user_admin)             | Changes to users, roles, and authentication credentials.                                                                                                                                                                                                                                                                   |
 
 Logging channels are analogous to [logging facilities in Syslog](https://wikipedia.org/wiki/Syslog) or [logging services in Datadog](https://docs.datadoghq.com/logs/log_collection/?tab=http#reserved-attributes). For more details on the contents of each logging channel, see the [Logging reference]({% link {{ page.version.version }}/logging.md %}#logging-channels).
@@ -52,7 +52,7 @@ Logging channels are analogous to [logging facilities in Syslog](https://wikiped
 
 {% include_cached new-in.html version="v25.4" %} The `log.channel_compatibility_mode.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) controls logging channel behavior. When set to:
 
-- `true` (default): Logs are sent to the standard [logging channels](#logging-channels). This reflects the current behavior. Specifically, the system sends:
+- `true` (default): Logs are sent to the standard [logging channels](#logging-channels). This maintains the behavior in v25.3 and earlier supported versions. Specifically, the system sends:
 
   - [Changefeed telemetry events]({% link {{ page.version.version }}/eventlog.md %}#changefeed-telemetry-events) to the [`TELEMETRY`](#telemetry) channel.
   - [SQL Slow Query Log]({% link {{ page.version.version }}/eventlog.md %}#sql-slow-query-log) and [SQL Slow Query Log (Internal)]({% link {{ page.version.version }}/eventlog.md %}#sql-slow-query-log-internal) events to the [`SQL_PERF`](#sql_perf) and [`SQL_INTERNAL_PERF`]({% link {{ page.version.version }}/logging.md %}#sql_internal_perf) channels, respectively.
diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md
@@ -14,12 +14,12 @@ This page describes some common logging use cases, their relevant [logging chann
 
 We provide an example [file sink configuration]({% link {{ page.version.version }}/configure-logs.md %}#output-to-files) for each use case. These configurations are entirely optional and are intended to highlight the contents of each logging channel. A sink can include any combination of logging channels. Moreover, a single logging channel can be used in more than one sink in your logging configuration.
 
-Your deployment may use an external service (e.g., [Elasticsearch](https://www.elastic.co/elastic-stack), [Splunk](https://www.splunk.com/)) to collect and programmatically read logging data.
+Your deployment may use an external service (e.g., [Elasticsearch](https://www.elastic.co/elastic-stack) or [Splunk](https://www.splunk.com/)) to collect and programmatically read logging data.
 
 {{site.data.alerts.callout_info}}
-In a future release, certain events will be directed to new [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels). For more details, refer to [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled).
+In a future major release, certain events will be directed by default to new [logging channels]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels).
 
-To assess potential downstream impacts on your logging setup and pipelines, set the `log.channel_compatibility_mode.enabled` cluster setting to `false` in a non-production environment.
+To prepare for the change and assess potential downstream impacts on your logging setup and pipelines, review the [`log.channel_compatibility_mode.enabled`]({% link {{ page.version.version }}/logging-overview.md %}#log-channel_compatibility_mode-enabled) cluster setting. After reviewing the documentation, set `log.channel_compatibility_mode.enabled` to `false` in a non-production environment.
 {{site.data.alerts.end}}
 
 {{site.data.alerts.callout_info}}
