从单位中解放 cassandra.yaml 参数名称
目标
作为 CASSANDRA-15234 的一部分，发生了三件大事
1) cassandra.yaml 中参数的重命名，以遵循 noun_verb 的形式。
2) 从单位中解放 cassandra.yaml 参数（DataStorage、DataRate 和 Duration），并为每个参数引入临时最小可接受单位（仅针对 DataStorage 和 Duration 参数）
3) 向后兼容框架，以支持旧名称和缺乏单位支持，直到至少下一个主要版本。
重命名的参数
社区已决定允许操作员为 Cassandra 参数指定持续时间、数据存储和数据速率类型的单位。所有具有特定单位（大多数情况下作为后缀添加到其名称中）的参数现在可以使用格式 [value][unit] 设置。单位后缀已从其名称中删除。支持的单位
| 参数类型 | 支持的单位 |
|---|---|
持续时间 |
d、h、m、s、ms、us、µs、ns |
数据存储 |
B、KiB、MiB、GiB |
数据速率 |
B/s、MiB/s、KiB/s |
示例:
旧名称和值格式
permissions_update_interval_ms: 0
新名称和可能的格式
permissions_update_interval: 0ms permissions_update_interval: 0s permissions_update_interval: 0d permissions_update_interval: 0us permissions_update_interval: 0µs
在 CASSANDRA-15234 中的工作已经相当大，因此我们决定为持续时间和数据存储参数引入最小允许单位的概念。这意味着什么？Cassandra 的内部仍然使用参数的旧单位。例如，如果内部使用秒，但您想在 cassandra.yaml 中添加一个以纳秒为单位的值，您将收到一个配置异常，其中包含以下信息
Accepted units: seconds, minutes, hours, days.
为什么需要这样做？因为我们可能会遇到精度问题。解决此问题的完整方案是将所有参数值的内部转换为使用 Cassandra 支持的最小单位进行操作。将来将打开一系列票证来评估并可能迁移到参数的最小单位（增量式，在 CASSANDRA-15234 之后）。
| 旧名称 | 新名称 | 支持的最小单位 |
|---|---|---|
permissions_validity_in_ms |
permissions_validity |
ms |
permissions_update_interval_in_ms |
permissions_update_interval |
ms |
roles_validity_in_ms |
roles_validity |
ms |
roles_update_interval_in_ms |
roles_update_interval |
ms |
credentials_validity_in_ms |
credentials_validity |
ms |
credentials_update_interval_in_ms |
credentials_update_interval |
ms |
max_hint_window_in_ms |
max_hint_window |
ms |
native_transport_idle_timeout_in_ms |
native_transport_idle_timeout |
ms |
request_timeout_in_ms |
request_timeout |
ms |
read_request_timeout_in_ms |
read_request_timeout |
ms |
range_request_timeout_in_ms |
range_request_timeout |
ms |
write_request_timeout_in_ms |
write_request_timeout |
ms |
counter_write_request_timeout_in_ms |
counter_write_request_timeout |
ms |
cas_contention_timeout_in_ms |
cas_contention_timeout |
ms |
truncate_request_timeout_in_ms |
truncate_request_timeout |
ms |
streaming_keep_alive_period_in_secs |
streaming_keep_alive_period |
s |
cross_node_timeout |
internode_timeout |
- |
slow_query_log_timeout_in_ms |
slow_query_log_timeout |
ms |
memtable_heap_space_in_mb |
memtable_heap_space |
MiB |
memtable_offheap_space_in_mb |
memtable_offheap_space |
MiB |
repair_session_space_in_mb |
repair_session_space |
MiB |
internode_max_message_size_in_bytes |
internode_max_message_size |
B |
internode_send_buff_size_in_bytes |
internode_socket_send_buffer_size |
B |
internode_socket_send_buffer_size_in_bytes |
internode_socket_send_buffer_size |
B |
internode_socket_receive_buffer_size_in_bytes |
internode_socket_receive_buffer_size |
B |
internode_recv_buff_size_in_bytes |
internode_socket_receive_buffer_size |
B |
internode_application_send_queue_capacity_in_bytes |
internode_application_send_queue_capacity |
B |
internode_application_send_queue_reserve_endpoint_capacity_in_bytes |
internode_application_send_queue_reserve_endpoint_capacity |
B |
internode_application_send_queue_reserve_global_capacity_in_bytes |
internode_application_send_queue_reserve_global_capacity |
B |
internode_application_receive_queue_capacity_in_bytes |
internode_application_receive_queue_capacity |
B |
internode_application_receive_queue_reserve_endpoint_capacity_in_bytes |
internode_application_receive_queue_reserve_endpoint_capacity |
B |
internode_application_receive_queue_reserve_global_capacity_in_bytes |
internode_application_receive_queue_reserve_global_capacity |
B |
internode_tcp_connect_timeout_in_ms |
internode_tcp_connect_timeout |
ms |
internode_tcp_user_timeout_in_ms |
internode_tcp_user_timeout |
ms |
internode_streaming_tcp_user_timeout_in_ms |
internode_streaming_tcp_user_timeout |
ms |
native_transport_max_frame_size_in_mb |
native_transport_max_frame_size |
MiB |
max_value_size_in_mb |
max_value_size |
MiB |
column_index_size_in_kb |
column_index_size |
KiB |
column_index_cache_size_in_kb |
column_index_cache_size |
KiB |
batch_size_warn_threshold_in_kb |
batch_size_warn_threshold |
KiB |
batch_size_fail_threshold_in_kb |
batch_size_fail_threshold |
KiB |
compaction_throughput_mb_per_sec |
compaction_throughput |
MiB/s |
compaction_large_partition_warning_threshold_mb |
compaction_large_partition_warning_threshold |
MiB |
min_free_space_per_drive_in_mb |
min_free_space_per_drive |
MiB |
stream_throughput_outbound_megabits_per_sec |
stream_throughput_outbound |
MiB/s |
inter_dc_stream_throughput_outbound_megabits_per_sec |
inter_dc_stream_throughput_outbound |
MiB/s |
commitlog_total_space_in_mb |
commitlog_total_space |
MiB |
commitlog_sync_group_window_in_ms |
commitlog_sync_group_window |
ms |
commitlog_sync_period_in_ms |
commitlog_sync_period |
ms |
commitlog_segment_size_in_mb |
commitlog_segment_size |
MiB |
periodic_commitlog_sync_lag_block_in_ms |
periodic_commitlog_sync_lag_block |
ms |
max_mutation_size_in_kb |
max_mutation_size |
KiB |
cdc_total_space_in_mb |
cdc_total_space |
MiB |
cdc_free_space_check_interval_ms |
cdc_free_space_check_interval |
ms |
dynamic_snitch_update_interval_in_ms |
dynamic_snitch_update_interval |
ms |
dynamic_snitch_reset_interval_in_ms |
dynamic_snitch_reset_interval |
ms |
hinted_handoff_throttle_in_kb |
hinted_handoff_throttle |
KiB |
batchlog_replay_throttle_in_kb |
batchlog_replay_throttle |
KiB |
hints_flush_period_in_ms |
hints_flush_period |
ms |
max_hints_file_size_in_mb |
max_hints_file_size |
MiB |
trickle_fsync_interval_in_kb |
trickle_fsync_interval |
KiB |
sstable_preemptive_open_interval_in_mb |
sstable_preemptive_open_interval |
MiB |
key_cache_size_in_mb |
key_cache_size |
MiB |
row_cache_size_in_mb |
row_cache_size |
MiB |
counter_cache_size_in_mb |
counter_cache_size |
MiB |
networking_cache_size_in_mb |
networking_cache_size |
MiB |
file_cache_size_in_mb |
file_cache_size |
MiB |
index_summary_capacity_in_mb |
index_summary_capacity |
MiB |
index_summary_resize_interval_in_minutes |
index_summary_resize_interval |
m |
gc_log_threshold_in_ms |
gc_log_threshold |
ms |
gc_warn_threshold_in_ms |
gc_warn_threshold |
ms |
tracetype_query_ttl |
trace_type_query_ttl |
s |
tracetype_repair_ttl |
trace_type_repair_ttl |
s |
prepared_statements_cache_size_mb |
prepared_statements_cache_size |
MiB |
enable_user_defined_functions |
user_defined_functions_enabled |
- |
enable_scripted_user_defined_functions |
scripted_user_defined_functions_enabled |
- |
enable_materialized_views |
materialized_views_enabled |
- |
enable_transient_replication |
transient_replication_enabled |
- |
enable_sasi_indexes |
sasi_indexes_enabled |
- |
enable_drop_compact_storage |
drop_compact_storage_enabled |
- |
enable_user_defined_functions_threads |
user_defined_functions_threads_enabled |
- |
enable_legacy_ssl_storage_port |
legacy_ssl_storage_port_enabled |
- |
user_defined_function_fail_timeout |
user_defined_functions_fail_timeout |
ms |
user_defined_function_warn_timeout |
user_defined_functions_warn_timeout |
ms |
cache_load_timeout_seconds |
cache_load_timeout |
s |
另一个待办事项是添加支持新格式的 JMX 方法。但是，如果虚拟表在不久的将来支持配置更改，我们可能会放弃此操作。
Cassandra 开发人员注意事项:
-
我们的大多数参数已作为 CASSANDRA-15234 的一部分迁移到新框架。
@Replaces是在您对Config类和cassandra.yaml中的任何配置参数进行更改时要使用的注释，并且您希望添加与以前 Cassandra 版本的向后兼容性。Converters类枚举了用于向后兼容性的不同方法。IDENTITY是仅用于名称更改的方法。有关其他转换器的更多信息，请查看类中的 JavaDoc。为了向后兼容，虚拟表Settings包含旧参数和新参数，以及旧值格式和新值格式。目前唯一的例外是以下三个参数：key_cache_save_period、row_cache_save_period和counter_cache_save_period，它们只出现一次，使用新值格式。旧名称和值格式至少可以在下一个主要版本之前使用。启动时会发出弃用警告。如果参数是持续时间、数据速率或数据存储类型，则在使用新名称时，其值应伴随一个单位。 -
添加新的配置参数时，请遵循新的格式
noun_verb。 -
如果可能，请考虑使用 Cassandra 支持的最低单位添加任何新参数。我们的新类型还支持长整型和整型上限，具体取决于您的需求。配置参数类型的全部选项是我们的三个主要抽象类中的嵌套类 -
DurationSpec、DataStorageSpec、DataRateSpec。 -
如果出于某种原因，您认为新参数的最小单位不应该是 Cassandra 中支持的单位，您可以使用
DurationSpec、DataStorageSpec中的其余嵌套类。允许的最小单位是我们内部用于该属性的单位，因此我们不必进行转换为更大的单位，这会导致精度问题。这仅是DurationSpec和DataStorageSpec的问题。DataRateSpec在内部以双精度处理。 -
新参数应添加为非负数。对于过去您可能已将 -1 设置为禁用的参数，您可能需要考虑使用单独的标志参数或空值。如果您使用空值，请确保在 DatabaseDescriptor 中引入的任何处理它的默认值也在任何相关的 setter 中复制。
-
数据存储、持续时间和数据速率类型的参数不能设置为 Long.MAX_VALUE（以前的长类型参数）和 Integer.MAX_VALUE（以前的 int 类型参数）。这些数字在单位之间的转换过程中使用，以防止发生溢出。
-
每次您添加 @Replaces 并更改名称时，我们都需要在 CCM 中的 此 Python 字典 中添加一个条目，以支持与 SnakeYAML 相同的向后兼容性。
请按照 DTest 存储库中 requirements.txt 中的说明，在提交任何更改后重新标记 CCM。您可能还想在您的存储库中进行标记测试，以确保在重新标记官方 CCM 后不会出现意外情况。请确保在进行任何更改后运行完整的 CI，因为 CCM 会影响我们的一些测试套件。
-
一些配置参数未在 cassandra.yaml 中公布，但它们在 Config 类中提供给高级用户。这些也应该使用新的框架和命名约定。
-
由于我们具有向后兼容性，因此我们不必重新编写所有 python DTest 以使用新格式设置配置，并且我们在测试时会利用向后兼容性。但是，请考虑使用新名称和值格式添加任何新测试。
-
JVM 内升级测试目前不支持每个版本的配置，因此我们必须保留旧名称和值格式。目前，如果我们尝试对较新版本使用新配置，则会静默忽略并使用默认配置。
-
SnakeYAML 支持参数的重载。这意味着如果您在
cassandra.yaml中多次添加配置参数，则最新的出现将是在 Cassandra 启动期间加载到 Config 中的出现。为了使升级尽可能少地造成破坏，我们继续支持这种行为，并将参数的旧名称和新名称添加到cassandra.yaml中。 -
请确保任何 JMX setter/getter 更新 Config 类属性，而不是一些本地副本。设置虚拟表报告 Config 类中随时加载的配置。
示例:
如果您将以下内容添加到 cassandra.yaml
hinted_handoff_enabled: true enabled_hinted_handolff: false
您将在 Config 中加载
hinted_handoff_enabled: false
CASSANDRA-17379 已打开以改善用户体验并弃用重载。默认情况下，我们拒绝使用包含相同参数的旧配置键和新配置键的配置启动 Cassandra。使用 -Dcassandra.allow_new_old_config_keys=true 启动 Cassandra 以覆盖。出于历史原因，cassandra.yaml 中的重复配置键默认情况下是允许的，使用 -Dcassandra.allow_duplicate_config_keys=false 启动 Cassandra 以禁止此操作。请注意，key_cache_save_period、row_cache_save_period、counter_cache_save_period 仅受 -Dcassandra.allow_duplicate_config_keys 影响。
