michaelsembwever commented on code in PR #2973:
URL: https://github.com/apache/cassandra/pull/2973#discussion_r1420921721
##########
doc/modules/cassandra/pages/architecture/storage-engine.adoc:
##########
@@ -1,46 +1,42 @@
= Storage Engine
+{cassandra} processes data at several stages on the write path, starting with
the immediate logging of a write and ending in with a write of data to disk:
+
+* Logging data in the commit log
+* Writing data to the memtable
+* Flushing data from the memtable
+* Storing data on disk in SSTables
+
[[commit-log]]
-== CommitLog
-
-Commitlogs are an append-only log of all mutations local to a Cassandra
-node. Any data written to Cassandra will first be written to a commit
-log before being written to a memtable. This provides durability in the
-case of unexpected shutdown. On startup, any mutations in the commit log
-will be applied to memtables.
-
-All mutations are write-optimized by storing in commitlog segments, reducing
-the number of seeks needed to write to disk. Commitlog segments are
-limited by the `commitlog_segment_size` option. Once the size is
-reached, a new commitlog segment is created. Commitlog segments can be
-archived, deleted, or recycled once all the data has been flushed to
-SSTables. Commitlog segments are truncated when Cassandra has written
-data older than a certain point to the SSTables. Running "nodetool
-drain" before stopping Cassandra will write everything in the memtables
-to SSTables and remove the need to sync with the commitlogs on startup.
-
-* `commitlog_segment_size`: The default size is 32MiB, which is
-almost always fine, but if you are archiving commitlog segments (see
-commitlog_archiving.properties), then you probably want a finer
-granularity of archiving; 8 or 16 MiB is reasonable.
-`commitlog_segment_size` also determines the default value of
-`max_mutation_size` in `cassandra.yaml`. By default,
-`max_mutation_size` is a half the size of `commitlog_segment_size`.
+== Logging writes to commit logs
+
+When a write occurs, {cassandra} writes the data to a local append-only
https://cassandra.apache.org/_/glossary.html#commit-log[commit log] on disk.
+This action provides
xref:cassandra:managing/configuration/cass_yaml_file.adoc[configurable
durability] by logging every write made to a {cassandra} node.
+If an unexpected shutdown occurs, the commit log provides permanent durable
writes of the data.
+On startup, any mutations in the commit log will be applied to
https://cassandra.apache.org/_/glossary.html#memtable[memtables].
+The commit log is shared among tables.
+
+All mutations are write-optimized on storage in commit log segments, reducing
the number of seeks needed to write to disk.
+Commit log segments are limited by the
xref:cassandra:managing/configuration/cass_yaml_file.adoc#commitlog_segment_size[`commitlog_segment_size`]
option.
+Once the defined size is reached, a new commit log segment is created.
+Commit log segments can be archived, deleted, or recycled once all the data is
flushed to
+https://cassandra.apache.org/_/glossary.html#sstable[SSTables].
+Commit log segments are truncated when {cassandra} has written data older than
a certain point to the SSTables.
+Running xref:managing:tools/nodetool/drain.adoc[`nodetool drain`] before
stopping {cassandra} will write everything in the memtables
+to SSTables and remove the need to sync with the commit logs on startup.
+
+*
xref:cassandra:managing/configuration/cass_yaml_file.adoc#commitlog_segment_size
[`commitlog_segment_size`]: The default size is 32MiB, which is almost always
fine, but if you are archiving commitlog segments (see
commitlog_archiving.properties), then you probably want a finer granularity of
archiving; 8 or 16 MiB is reasonable.
+`commitlog_segment_size` also determines the default value of
xref:cassandra:managing/configuration/cass_yaml_file.adoc#max_mutation_size[`max_mutation_size`]
in `cassandra.yaml`. By default, `max_mutation_size` is a half the size of
`commitlog_segment_size`.
[NOTE]
====
-If `max_mutation_size` is set explicitly then
-`commitlog_segment_size` must be set to at least twice the size of
-`max_mutation_size`.
+If `max_mutation_size` is set explicitly then `commitlog_segment_size` must be
set to at least twice the size of `max_mutation_size`.
====
-* `commitlog_sync`: may be either _periodic_ or _batch_.
-** `batch`: In batch mode, Cassandra won’t ack writes until the commit
-log has been fsynced to disk.
+*
xref:cassandra:managing/configuration/cass_yaml_file.adoc#commitlog_sync[`commitlog_sync`]:
may be either _periodic_ or _batch_.
+** `batch`: In batch mode, {cassandra} won't acknowledge writes until the
commit log has been fsynced to disk.
+
-** `periodic`: In periodic mode, writes are immediately ack'ed, and the
-CommitLog is simply synced every "commitlog_sync_period"
-milliseconds.
+** `periodic`: In periodic mode, writes are immediately acknowledged, and the
commit log is simply synced every "commitlog_sync_period" milliseconds.
+
- `commitlog_sync_period`: Time to wait between "periodic" fsyncs
_Default Value:_ 10000ms
Review Comment:
for later, these default value lines are not indented, so it doesn't read
easy
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
