將 cassandra.yaml 參數名稱從其單位中解放出來
目標
作為 CASSANDRA-15234 的一部分，發生了三件大事
1) 將 cassandra.yaml 中的參數重新命名為 noun_verb 形式。
2) 將 cassandra.yaml 參數從其單位 (DataStorage、DataRate 和 Duration) 中解放出來，並為每個參數引入暫時最小可接受單位 (僅適用於 DataStorage 和 Duration 單位)
3) 向後相容性架構，以支援舊名稱和至少在下次主要版本發布之前缺乏單位支援。
重新命名的參數
社群已決定允許操作員為類型為持續時間、資料儲存和資料速率的 Cassandra 參數指定單位。所有具有特定單位的參數 (大多數時候會將其作為後綴新增至其名稱) 現在可以使用 [值][單位] 格式設定。單位後綴已從其名稱中移除。支援的單位
| 參數類型 | 支援的單位 |
|---|---|
持續時間 |
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 的一部分。當您在
Config類別和cassandra.yaml中變更任何設定參數，並且您想要新增與先前 Cassandra 版本的向後相容性時，@Replaces是要使用的註解。Converters類別列舉用於向後相容性的不同方法。IDENTITY是僅用於變更名稱的方法。有關其他轉換器的詳細資訊，請查看類別中的 JavaDoc。為了向後相容性，虛擬表格Settings包含舊參數和新參數，以及舊值格式和新值格式。目前唯一的例外是下列三個參數：key_cache_save_period、row_cache_save_period和counter_cache_save_period，它們僅出現一次，且採用新值格式。舊名稱和值格式至少可以使用到下一個主要版本。啟動時會發出棄用警告。如果參數的類型為持續時間、資料速率或資料儲存，則在使用新名稱時，其值應附帶單位。 -
新增新的設定參數時，請遵循新的格式
名詞_動詞。 -
請考慮在可能的情況下，新增任何新的參數，並使用 Cassandra 支援的最低單位。我們的類型也支援長整數和整數上限，具體取決於您的需求。所有設定參數類型的選項都是我們三個主要抽象類別的巢狀類別 -
DurationSpec、DataStorageSpec、DataRateSpec。 -
如果您出於某種原因認為新參數的最小單位不應該是 Cassandra 中支援的單位，則可以使用
DurationSpec、DataStorageSpec中的其餘巢狀類別。允許的最小單位是我們在內部用於屬性的單位，因此我們不必轉換為較大的單位，這將導致精確度問題。這只會在DurationSpec和DataStorageSpec中發生問題。DataRateSpec在內部以雙精度處理。 -
新的參數應新增為非負數。對於您過去會設定為 -1 以停用的參數，您可能需要考慮使用單獨的旗標參數或 null 值。如果您使用 null 值，請確保在 DatabaseDescriptor 中引入的任何預設值以處理它，也會複製到任何相關的設定程式中。
-
資料儲存、持續時間和資料速率類型的參數無法設定為 Long.MAX_VALUE（長整型前參數）和 Integer.MAX_VALUE（整型前參數）。這些數字用於單位之間的轉換，以防止發生溢位。
-
任何時候，只要您使用名稱變更新增 @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 設定程式/取得程式更新 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 影響。
