Author: slebresne
Date: Wed Aug 31 10:55:41 2016
New Revision: 1758581
URL: http://svn.apache.org/viewvc?rev=1758581&view=rev
Log:
Fix problems from CASSANDRA-12533
Added:
cassandra/site/src/doc/3.7/_images/
cassandra/site/src/doc/3.7/_images/eclipse_debug0.png (with props)
cassandra/site/src/doc/3.7/_images/eclipse_debug1.png (with props)
cassandra/site/src/doc/3.7/_images/eclipse_debug2.png (with props)
cassandra/site/src/doc/3.7/_images/eclipse_debug3.png (with props)
cassandra/site/src/doc/3.7/_images/eclipse_debug4.png (with props)
cassandra/site/src/doc/3.7/_images/eclipse_debug5.png (with props)
cassandra/site/src/doc/3.7/_images/eclipse_debug6.png (with props)
cassandra/site/src/doc/3.7/_sources/development/
cassandra/site/src/doc/3.7/_sources/development/code_style.txt
cassandra/site/src/doc/3.7/_sources/development/how_to_commit.txt
cassandra/site/src/doc/3.7/_sources/development/how_to_review.txt
cassandra/site/src/doc/3.7/_sources/development/ide.txt
cassandra/site/src/doc/3.7/_sources/development/index.txt
cassandra/site/src/doc/3.7/_sources/development/patches.txt
cassandra/site/src/doc/3.7/_sources/development/testing.txt
cassandra/site/src/doc/3.7/development/
cassandra/site/src/doc/3.7/development/code_style.html
cassandra/site/src/doc/3.7/development/how_to_commit.html
cassandra/site/src/doc/3.7/development/how_to_review.html
cassandra/site/src/doc/3.7/development/ide.html
cassandra/site/src/doc/3.7/development/index.html
cassandra/site/src/doc/3.7/development/patches.html
cassandra/site/src/doc/3.7/development/testing.html
Removed:
cassandra/site/src/doc/3.10/
Modified:
cassandra/site/src/_config.yml
cassandra/site/src/css/sphinx.scss
cassandra/site/src/doc/3.7/_sources/bugs.txt
cassandra/site/src/doc/3.7/_sources/configuration/cassandra_config_file.txt
cassandra/site/src/doc/3.7/_sources/cql/changes.txt
cassandra/site/src/doc/3.7/_sources/cql/dml.txt
cassandra/site/src/doc/3.7/_sources/index.txt
cassandra/site/src/doc/3.7/_sources/operating/compaction.txt
cassandra/site/src/doc/3.7/_sources/operating/metrics.txt
cassandra/site/src/doc/3.7/architecture/dynamo.html
cassandra/site/src/doc/3.7/architecture/guarantees.html
cassandra/site/src/doc/3.7/architecture/index.html
cassandra/site/src/doc/3.7/architecture/overview.html
cassandra/site/src/doc/3.7/architecture/storage_engine.html
cassandra/site/src/doc/3.7/bugs.html
cassandra/site/src/doc/3.7/configuration/cassandra_config_file.html
cassandra/site/src/doc/3.7/configuration/index.html
cassandra/site/src/doc/3.7/contactus.html
cassandra/site/src/doc/3.7/cql/appendices.html
cassandra/site/src/doc/3.7/cql/changes.html
cassandra/site/src/doc/3.7/cql/ddl.html
cassandra/site/src/doc/3.7/cql/definitions.html
cassandra/site/src/doc/3.7/cql/dml.html
cassandra/site/src/doc/3.7/cql/functions.html
cassandra/site/src/doc/3.7/cql/index.html
cassandra/site/src/doc/3.7/cql/indexes.html
cassandra/site/src/doc/3.7/cql/json.html
cassandra/site/src/doc/3.7/cql/mvs.html
cassandra/site/src/doc/3.7/cql/security.html
cassandra/site/src/doc/3.7/cql/triggers.html
cassandra/site/src/doc/3.7/cql/types.html
cassandra/site/src/doc/3.7/data_modeling/index.html
cassandra/site/src/doc/3.7/faq/index.html
cassandra/site/src/doc/3.7/genindex.html
cassandra/site/src/doc/3.7/getting_started/configuring.html
cassandra/site/src/doc/3.7/getting_started/drivers.html
cassandra/site/src/doc/3.7/getting_started/index.html
cassandra/site/src/doc/3.7/getting_started/installing.html
cassandra/site/src/doc/3.7/getting_started/querying.html
cassandra/site/src/doc/3.7/index.html
cassandra/site/src/doc/3.7/objects.inv
cassandra/site/src/doc/3.7/operating/backups.html
cassandra/site/src/doc/3.7/operating/bloom_filters.html
cassandra/site/src/doc/3.7/operating/bulk_loading.html
cassandra/site/src/doc/3.7/operating/cdc.html
cassandra/site/src/doc/3.7/operating/compaction.html
cassandra/site/src/doc/3.7/operating/compression.html
cassandra/site/src/doc/3.7/operating/hardware.html
cassandra/site/src/doc/3.7/operating/hints.html
cassandra/site/src/doc/3.7/operating/index.html
cassandra/site/src/doc/3.7/operating/metrics.html
cassandra/site/src/doc/3.7/operating/read_repair.html
cassandra/site/src/doc/3.7/operating/repair.html
cassandra/site/src/doc/3.7/operating/security.html
cassandra/site/src/doc/3.7/operating/snitch.html
cassandra/site/src/doc/3.7/operating/topo_changes.html
cassandra/site/src/doc/3.7/search.html
cassandra/site/src/doc/3.7/searchindex.js
cassandra/site/src/doc/3.7/tools/cqlsh.html
cassandra/site/src/doc/3.7/tools/index.html
cassandra/site/src/doc/3.7/tools/nodetool.html
cassandra/site/src/doc/3.7/troubleshooting/index.html
cassandra/site/src/doc/latest
Modified: cassandra/site/src/_config.yml
URL:
http://svn.apache.org/viewvc/cassandra/site/src/_config.yml?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/_config.yml (original)
+++ cassandra/site/src/_config.yml Wed Aug 31 10:55:41 2016
@@ -16,6 +16,9 @@ destination: ../publish
exclude: [ Makefile, README ]
+include:
+ - _images
+
# Build settings
markdown: kramdown
Modified: cassandra/site/src/css/sphinx.scss
URL:
http://svn.apache.org/viewvc/cassandra/site/src/css/sphinx.scss?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/css/sphinx.scss (original)
+++ cassandra/site/src/css/sphinx.scss Wed Aug 31 10:55:41 2016
@@ -223,7 +223,7 @@ div.admonition {
}
}
-.admonition.note {
+.admonition.note, .admonition.hint {
border-color: #d6e9c6;
.admonition-title {
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug0.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug0.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug0.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug1.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug1.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug1.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug2.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug2.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug2.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug3.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug3.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug3.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug4.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug4.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug4.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug5.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug5.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug5.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: cassandra/site/src/doc/3.7/_images/eclipse_debug6.png
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_images/eclipse_debug6.png?rev=1758581&view=auto
==============================================================================
Binary file - no diff available.
Propchange: cassandra/site/src/doc/3.7/_images/eclipse_debug6.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Modified: cassandra/site/src/doc/3.7/_sources/bugs.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/bugs.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/bugs.txt (original)
+++ cassandra/site/src/doc/3.7/_sources/bugs.txt Wed Aug 31 10:55:41 2016
@@ -14,7 +14,7 @@
.. See the License for the specific language governing permissions and
.. limitations under the License.
-Reporting bugs and contributing
+Reporting Bugs and Contributing
===============================
If you encounter a problem with Cassandra, the first places to ask for help
are the :ref:`user mailing list
@@ -25,7 +25,6 @@ ticket through the `Apache Cassandra JIR
details as you can on your problem, and don't forget to indicate which version
of Cassandra you are running and on which
environment.
-If you would like to contribute, please check `the section on contributing
-<https://wiki.apache.org/cassandra/HowToContribute>`__ on the Cassandra wiki.
Please note that the source of this
-documentation is part of the Cassandra git repository and hence contributions
to the documentation should follow the
+Further details on how to contribute can be found at our
:doc:`development/index` section. Please note that the source of
+this documentation is part of the Cassandra git repository and hence
contributions to the documentation should follow the
same path.
Modified:
cassandra/site/src/doc/3.7/_sources/configuration/cassandra_config_file.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/configuration/cassandra_config_file.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/configuration/cassandra_config_file.txt
(original)
+++ cassandra/site/src/doc/3.7/_sources/configuration/cassandra_config_file.txt
Wed Aug 31 10:55:41 2016
@@ -722,6 +722,10 @@ If omitted, Cassandra will set both to 1
------------------------------
*This option is commented out by default.*
+memtable_cleanup_threshold is deprecated. The default calculation
+is the only reasonable choice. See the comments on memtable_flush_writers
+for more information.
+
Ratio of occupied non-flushing memtable size to total permitted size
that will trigger a flush of the largest memtable. Larger mct will
mean larger flushes and hence less compaction, but also less concurrent
@@ -769,16 +773,35 @@ of the commitlog volume.
--------------------------
*This option is commented out by default.*
-This sets the amount of memtable flush writer threads. These will
-be blocked by disk io, and each one will hold a memtable in memory
-while blocked.
-
-memtable_flush_writers defaults to one per data_file_directory.
+This sets the number of memtable flush writer threads per disk
+as well as the total number of memtables that can be flushed concurrently.
+These are generally a combination of compute and IO bound.
+
+Memtable flushing is more CPU efficient than memtable ingest and a single
thread
+can keep up with the ingest rate of a whole server on a single fast disk
+until it temporarily becomes IO bound under contention typically with
compaction.
+At that point you need multiple flush threads. At some point in the future
+it may become CPU bound all the time.
+
+You can tell if flushing is falling behind using the
MemtablePool.BlockedOnAllocation
+metric which should be 0, but will be non-zero if threads are blocked waiting
on flushing
+to free memory.
+
+memtable_flush_writers defaults to two for a single data directory.
+This means that two memtables can be flushed concurrently to the single data
directory.
+If you have multiple data directories the default is one memtable flushing at
a time
+but the flush will use a thread per data directory so you will get two or more
writers.
+
+Two is generally enough to flush on a fast disk [array] mounted as a single
data directory.
+Adding more flush writers will result in smaller more frequent flushes that
introduce more
+compaction overhead.
+
+There is a direct tradeoff between number of memtables that can be flushed
concurrently
+and flush size and frequency. More is not better you just need enough flush
writers
+to never stall waiting for flushing to free memory.
-If your data directories are backed by SSD, you can increase this, but
-avoid having memtable_flush_writers * data_file_directories > number of cores
-*Default Value:* 1
+*Default Value:* 2
``cdc_total_space_in_mb``
-------------------------
@@ -1324,6 +1347,15 @@ The default timeout for other, miscellan
*Default Value:* 10000
+``slow_query_log_timeout_in_ms``
+--------------------------------
+
+How long before a node logs slow queries. Select queries that take longer than
+this timeout to execute, will generate an aggregated log message, so that slow
queries
+can be identified. Set this value to zero to disable slow query logging.
+
+*Default Value:* 500
+
``cross_node_timeout``
----------------------
Modified: cassandra/site/src/doc/3.7/_sources/cql/changes.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/cql/changes.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/cql/changes.txt (original)
+++ cassandra/site/src/doc/3.7/_sources/cql/changes.txt Wed Aug 31 10:55:41 2016
@@ -24,7 +24,10 @@ The following describes the changes in e
3.4.3
^^^^^
+- Support for ``GROUP BY`` (:jira:`10707`).
- Adds a ``DEFAULT UNSET`` option for ``INSERT JSON`` to ignore omitted
columns (:jira:`11424`).
+- Allows ``null`` as a legal value for TTL on insert and update. It will be
treated as equivalent to
+inserting a 0 (:jira:`12216`).
3.4.2
^^^^^
Modified: cassandra/site/src/doc/3.7/_sources/cql/dml.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/cql/dml.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/cql/dml.txt (original)
+++ cassandra/site/src/doc/3.7/_sources/cql/dml.txt Wed Aug 31 10:55:41 2016
@@ -34,6 +34,7 @@ Querying data from data is done using a
select_statement: SELECT [ JSON | DISTINCT ] ( `select_clause` | '*' )
: FROM `table_name`
: [ WHERE `where_clause` ]
+ : [ GROUP BY `group_by_clause` ]
: [ ORDER BY `ordering_clause` ]
: [ PER PARTITION LIMIT (`integer` | `bind_marker`) ]
: [ LIMIT (`integer` | `bind_marker`) ]
@@ -49,6 +50,7 @@ Querying data from data is done using a
: '(' `column_name` ( ',' `column_name` )* ')' `operator`
`tuple_literal`
: TOKEN '(' `column_name` ( ',' `column_name` )* ')' `operator`
`term`
operator: '=' | '<' | '>' | '<=' | '>=' | '!=' | IN | CONTAINS | CONTAINS
KEY
+ group_by_clause: `column_name` ( ',' `column_name` )*
ordering_clause: `column_name` [ ASC | DESC ] ( ',' `column_name` [ ASC |
DESC ] )*
For instance::
@@ -208,6 +210,25 @@ The ``CONTAINS`` operator may only be us
``CONTAINS`` applies to the map values. The ``CONTAINS KEY`` operator may only
be used on map columns and applies to the
map keys.
+.. _group-by-clause:
+
+Grouping results
+~~~~~~~~~~~~~~~~
+
+The ``GROUP BY`` option allows to condense into a single row all selected rows
that share the same values for a set
+of columns.
+
+Using the ``GROUP BY`` option, it is only possible to group rows at the
partition key level or at a clustering column
+level. By consequence, the ``GROUP BY`` option only accept as arguments
primary key column names in the primary key
+order. If a primary key column is restricted by an equality restriction it is
not required to be present in the
+``GROUP BY`` clause.
+
+Aggregate functions will produce a separate value for each group. If no
``GROUP BY`` clause is specified,
+aggregates functions will produce a single value for all the rows.
+
+If a column is selected without an aggregate function, in a statement with a
``GROUP BY``, the first value encounter
+in each group will be returned.
+
.. _ordering-clause:
Ordering results
@@ -399,7 +420,8 @@ parameters:
automatically removed from the database after the specified time. Note that
the TTL concerns the inserted values, not
the columns themselves. This means that any subsequent update of the column
will also reset the TTL (to whatever TTL
is specified in that update). By default, values never expire. A TTL of 0 is
equivalent to no TTL. If the table has a
- default_time_to_live, a TTL of 0 will remove the TTL for the inserted or
updated values.
+ default_time_to_live, a TTL of 0 will remove the TTL for the inserted or
updated values. A TTL of ``null`` is equivalent
+ to inserting with a TTL of 0.
.. _delete_statement:
Added: cassandra/site/src/doc/3.7/_sources/development/code_style.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/code_style.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/code_style.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/code_style.txt Wed Aug 31
10:55:41 2016
@@ -0,0 +1,94 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Code Style
+==========
+
+General Code Conventions
+------------------------
+
+ - The Cassandra project follows `Sun's Java coding conventions
<http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html>`_ with an
important exception: ``{`` and ``}`` are always placed on a new line
+
+Exception handling
+------------------
+
+ - Never ever write ``catch (...) {}`` or ``catch (...) { logger.error() }``
merely to satisfy Java's compile-time exception checking. Always propagate the
exception up or throw ``RuntimeException`` (or, if it "can't happen,"
``AssertionError``). This makes the exceptions visible to automated tests.
+ - Avoid propagating up checked exceptions that no caller handles. Rethrow as
``RuntimeException`` (or ``IOError``, if that is more applicable).
+ - Similarly, logger.warn() is often a cop-out: is this an error or not? If it
is don't hide it behind a warn; if it isn't, no need for the warning.
+ - If you genuinely know an exception indicates an expected condition, it's
okay to ignore it BUT this must be explicitly explained in a comment.
+
+Boilerplate
+-----------
+
+ - Avoid redundant ``@Override`` annotations when implementing abstract or
interface methods.
+ - Do not implement equals or hashcode methods unless they are actually needed.
+ - Prefer public final fields to private fields with getters. (But prefer
encapsulating behavior in "real" methods to either.)
+ - Prefer requiring initialization in the constructor to setters.
+ - Avoid redundant ``this`` references to member fields or methods.
+ - Do not extract interfaces (or abstract classes) unless you actually need
multiple implementations of it.
+ - Always include braces for nested levels of conditionals and loops. Only
avoid braces for single level.
+
+Multiline statements
+--------------------
+
+ - Try to keep lines under 120 characters, but use good judgement -- it's
better to exceed 120 by a little, than split a line that has no natural
splitting points.
+ - When splitting inside a method call, use one line per parameter and align
them, like this:
+
+ ::
+
+ SSTableWriter writer = new SSTableWriter(cfs.getTempSSTablePath(),
+ columnFamilies.size(),
+ StorageService.getPartitioner());
+
+ - When splitting a ternary, use one line per clause, carry the operator, and
align like this:
+
+ ::
+
+ var = bar == null
+ ? doFoo()
+ : doBar();
+
+Whitespace
+----------
+
+ - Please make sure to use 4 spaces instead of the tab character for all your
indentation.
+ - Many lines in many files have a bunch of trailing whitespace... Please
either clean these up in a separate patch, or leave them alone, so that
reviewers now and anyone reading code history later doesn't have to pay
attention to whitespace diffs.
+
+Imports
+-------
+
+Please observe the following order for your imports::
+
+ java
+ [blank line]
+ com.google.common
+ org.apache.commons
+ org.junit
+ org.slf4j
+ [blank line]
+ everything else alphabetically
+
+Format files for IDEs
+---------------------
+
+ - IntelliJ: `intellij-codestyle.jar
<https://wiki.apache.org/cassandra/CodeStyle?action=AttachFile&do=view&target=intellij-codestyle.jar>`_
+ - IntelliJ 13: `gist for IntelliJ 13
<https://gist.github.com/jdsumsion/9ab750a05c2a567c6afc>`_ (this is a work in
progress, still working on javadoc, ternary style, line continuations, etc)
+ - Eclipse (https://github.com/tjake/cassandra-style-eclipse)
+
+
+
Added: cassandra/site/src/doc/3.7/_sources/development/how_to_commit.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/how_to_commit.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/how_to_commit.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/how_to_commit.txt Wed Aug
31 10:55:41 2016
@@ -0,0 +1,75 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+How-to Commit
+=============
+
+If you are a committer, feel free to pick any process that works for you - so
long as you are planning to commit the work yourself.
+
+Here is how committing and merging will usually look for merging and pushing
for tickets that follow the convention (if patch-based):
+
+Hypothetical CASSANDRA-12345 ticket is a cassandra-3.0 based bug fix that
requires different code for cassandra-3.3, and trunk. Contributor Jackie
supplied a patch for the root branch (12345-3.0.patch), and patches for the
remaining branches (12345-3.3.patch, 12345-trunk.patch).
+
+On cassandra-3.0:
+ #. ``git am -3 12345-3.0.patch`` (if we have a problem b/c of CHANGES.txt
not merging anymore, we fix it ourselves, in place)
+
+On cassandra-3.3:
+ #. ``git merge cassandra-3.0 -s ours``
+ #. ``git apply -3 12345-3.3.patch`` (likely to have an issue with
CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit âamend``
+
+On trunk:
+ #. ``git merge cassandra-3.3 -s ours``
+ #. ``git apply -3 12345-trunk.patch`` (likely to have an issue with
CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit âamend``
+
+On any branch:
+ #. ``git push origin cassandra-3.0 cassandra-3.3 trunk âatomic``
+
+Same scenario, but a branch-based contribution:
+
+On cassandra-3.0:
+ #. ``git cherry-pick <sha-of-3.0-commit>`` (if we have a problem b/c of
CHANGES.txt not merging anymore, we fix it ourselves, in place)
+
+On cassandra-3.3:
+ #. ``git merge cassandra-3.0 -s ours``
+ #. ``git format-patch -1 <sha-of-3.3-commit>``
+ #. ``git apply -3 <sha-of-3.3-commit>.patch`` (likely to have an issue with
CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit âamend``
+
+On trunk:
+ #. ``git merge cassandra-3.3 -s ours``
+ #. ``git format-patch -1 <sha-of-trunk-commit>``
+ #. ``git apply -3 <sha-of-trunk-commit>.patch`` (likely to have an issue
with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit âamend``
+
+On any branch:
+ #. ``git push origin cassandra-3.0 cassandra-3.3 trunk âatomic``
+
+.. tip::
+
+ Notes on git flags:
+ ``-3`` flag to am and apply will instruct git to perform a 3-way merge for
you. If a conflict is detected, you can either resolve it manually or invoke
git mergetool - for both am and apply.
+
+ ``âatomic`` flag to git push does the obvious thing: pushes all or
nothing. Without the flag, the command is equivalent to running git push once
per each branch. This is nifty in case a race condition happens - you wonât
push half the branches, blocking other committersâ progress while you are
resolving the issue.
+
+.. tip::
+
+ The fastest way to get a patch from someoneâs commit in a branch on GH -
if you donât have their repo in remotes - is to append .patch to the commit
url, e.g.
+ curl -O
https://github.com/apache/cassandra/commit/7374e9b5ab08c1f1e612bf72293ea14c959b0c3c.patch
+
Added: cassandra/site/src/doc/3.7/_sources/development/how_to_review.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/how_to_review.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/how_to_review.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/how_to_review.txt Wed Aug
31 10:55:41 2016
@@ -0,0 +1,71 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Review Checklist
+****************
+
+When reviewing tickets in Apache JIRA, the following items should be covered
as part of the review process:
+
+**General**
+
+ * Does it conform to the :doc:`code_style` guidelines?
+ * Is there any redundant or duplicate code?
+ * Is the code as modular as possible?
+ * Can any singletons be avoided?
+ * Can any of the code be replaced with library functions?
+ * Are units of measurement used in the code consistent, both internally and
with the rest of the ecosystem?
+
+**Error-Handling**
+
+ * Are all data inputs and outputs checked (for the correct type, length,
format, and range) and encoded?
+ * Where third-party utilities are used, are returning errors being caught?
+ * Are invalid parameter values handled?
+ * Are any Throwable/Exceptions passed to the JVMStabilityInspector?
+ * Are errors well-documented? Does the error message tell the user how to
proceed?
+ * Do exceptions propagate to the appropriate level in the code?
+
+**Documentation**
+
+ * Do comments exist and describe the intent of the code (the "why", not the
"how")?
+ * Are javadocs added where appropriate?
+ * Is any unusual behavior or edge-case handling described?
+ * Are data structures and units of measurement explained?
+ * Is there any incomplete code? If so, should it be removed or flagged with a
suitable marker like âTODOâ?
+ * Does the code self-document via clear naming, abstractions, and flow
control?
+ * Have NEWS.txt, the cql3 docs, and the native protocol spec been updated if
needed?
+ * Is the ticket tagged with "client-impacting" and "doc-impacting", where
appropriate?
+ * Has lib/licences been updated for third-party libs? Are they Apache License
compatible?
+ * Is the Component on the JIRA ticket set appropriately?
+
+**Testing**
+
+ * Is the code testable? i.e. donât add too many or hide dependencies,
unable to initialize objects, test frameworks can use methods etc.
+ * Do tests exist and are they comprehensive?
+ * Do unit tests actually test that the code is performing the intended
functionality?
+ * Could any test code use common functionality (e.g. ccm, dtest, or CqlTester
methods) or abstract it there for reuse?
+ * If the code may be affected by multi-node clusters, are there dtests?
+ * If the code may take a long time to test properly, are there CVH tests?
+ * Is the test passing on CI for all affected branches (up to trunk, if
applicable)? Are there any regressions?
+ * If patch affects read/write path, did we test for performance regressions
w/multiple workloads?
+ * If adding a new feature, were tests added and performed confirming it meets
the expected SLA/use-case requirements for the feature?
+
+**Logging**
+
+ * Are logging statements logged at the correct level?
+ * Are there logs in the critical path that could affect performance?
+ * Is there any log that could be added to communicate status or troubleshoot
potential problems in this feature?
+ * Can any unnecessary logging statement be removed?
+
Added: cassandra/site/src/doc/3.7/_sources/development/ide.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/ide.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/ide.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/ide.txt Wed Aug 31 10:55:41
2016
@@ -0,0 +1,157 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Building and IDE Integration
+****************************
+
+Building From Source
+====================
+
+Getting started with Cassandra and IntelliJ IDEA or Eclipse is simple, once
you manage to build Cassandra from source using `Java 8
<http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_, `Git
<https://git-scm.com/>`_ and `Ant <http://ant.apache.org/>`_.
+
+The source code for Cassandra is shared through the central Apache Git
repository and organized by different branches. You can access the code for the
current development branch through git as follows::
+
+ git clone http://git-wip-us.apache.org/repos/asf/cassandra.git
cassandra-trunk
+
+Other branches will point to different versions of Cassandra. Switching to a
different branch requires checking out the branch by its name::
+
+ git checkout cassandra-3.0
+
+You can get a list of available branches with ``git branch``.
+
+Finally build Cassandra using ant::
+
+ ant
+
+This may take a significant amount of time depending on whether artifacts have
to be downloaded and the number of classes that need to be compiled.
+
+.. hint::
+
+ You can setup multiple working trees for different Cassandra versions from
the same repository using `git-worktree
<https://git-scm.com/docs/git-worktree>`_.
+
+Setting up Cassandra in IntelliJ IDEA
+=====================================
+
+`IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ by JetBrains is one of the
most popular IDEs for Cassandra and Java development in general. The Community
Edition is provided as a free download with all features needed to get started
developing Cassandra.
+
+Setup Cassandra as a Project (C* 2.1 and newer)
+-----------------------------------------------
+
+Since 2.1.5, there is a new ant target: ``generate-idea-files``. Please see
our `wiki <https://wiki.apache.org/cassandra/RunningCassandraInIDEA>`_ for
instructions for older Cassandra versions.
+
+Please clone and build Cassandra as described above and execute the following
steps:
+
+1. Once Cassandra is built, generate the IDEA files using ant:
+
+::
+
+ ant generate-idea-files
+
+2. Start IDEA
+
+3. Open the IDEA project from the checked out Cassandra directory using the
menu item Open in IDEA's File menu
+
+The project generated by the ant task ``generate-idea-files`` contains nearly
everything you need to debug Cassandra and execute unit tests.
+
+ * Run/debug defaults for JUnit
+ * Run/debug configuration for Cassandra daemon
+ * License header for Java source files
+ * Cassandra code style
+ * Inspections
+
+Setting up Cassandra in Eclipse
+===============================
+
+Eclipse is a popular open source IDE that can be used for Cassandra
development. Various Eclipse environments are available from the `download page
<https://www.eclipse.org/downloads/eclipse-packages/>`_. The following guide
was created with "Eclipse IDE for Java Developers".
+
+These instructions were tested on Ubuntu 16.04 with Eclipse Neon (4.6) using
Cassandra 2.1, 2.2 and 3.x.
+
+Project Settings
+----------------
+
+**It is important that you generate the Eclipse files with Ant before trying
to set up the Eclipse project.**
+
+ * Clone and build Cassandra as described above.
+ * Run ``ant generate-eclipse-files`` to create the Eclipse settings.
+ * Start Eclipse.
+ * Select ``File->Import->Existing Projects into Workspace->Select git
directory``.
+ * Make sure "cassandra-trunk" is recognized and selected as a project
(assuming you checked the code out into the folder cassandra-trunk as described
above).
+ * Confirm "Finish" to have your project imported.
+
+You should now be able to find the project as part of the "Package Explorer"
or "Project Explorer" without having Eclipse complain about any errors after
building the project automatically.
+
+Unit Tests
+----------
+
+Unit tests can be run from Eclipse by simply right-clicking the class file or
method and selecting ``Run As->JUnit Test``. Tests can be debugged this way as
well by defining breakpoints (double-click line number) and selecting ``Debug
As->JUnit Test``.
+
+Alternatively all unit tests can be run from the command line as described in
:doc:`testing`
+
+Debugging Cassandra Using Eclipse
+---------------------------------
+
+There are two ways how to start and debug a local Cassandra instance with
Eclipse. You can either start Cassandra just as you normally would by using the
``./bin/cassandra`` script and connect to the JVM through `remotely
<https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/introclientissues005.html>`_
from Eclipse or start Cassandra from Eclipse right away.
+
+Starting Cassandra From Command Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ * Set environment variable to define remote debugging options for the JVM:
+ ``export
JVM_EXTRA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=1414"``
+ * Start Cassandra by executing the ``./bin/cassandra``
+
+Afterwards you should be able to connect to the running Cassandra process
through the following steps:
+
+From the menu, select ``Run->Debug Configurations..``
+
+.. image:: images/eclipse_debug0.png
+
+Create new remote application
+
+.. image:: images/eclipse_debug1.png
+
+Configure connection settings by specifying a name and port 1414
+
+.. image:: images/eclipse_debug2.png
+
+Afterwards confirm "Debug" to connect to the JVM and start debugging Cassandra!
+
+Starting Cassandra From Eclipse
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cassandra can also be started directly from Eclipse if you don't want to use
the command line.
+
+From the menu, select ``Run->Run Configurations..``
+
+.. image:: images/eclipse_debug3.png
+
+Create new application
+
+.. image:: images/eclipse_debug4.png
+
+Specify name, project and main class
``org.apache.cassandra.service.CassandraDaemon``
+
+.. image:: images/eclipse_debug5.png
+
+Configure additional JVM specific parameters that will start Cassandra with
some of the settings created by the regular startup script. Change heap related
values as needed.
+
+::
+
+ -Xms1024M -Xmx1024M -Xmn220M -Xss256k -ea -XX:+UseThreadPriorities
-XX:ThreadPriorityPolicy=42 -XX:+UseParNewGC -XX:+UseConcMarkSweepGC
-XX:+CMSParallelRemarkEnabled -XX:+UseCondCardMark
-javaagent:./lib/jamm-0.3.0.jar -Djava.net.preferIPv4Stack=true
+
+.. image:: images/eclipse_debug6.png
+
+Now just confirm "Debug" and you should see the output of Cassandra starting
up in the Eclipse console and should be able to set breakpoints and start
debugging!
+
Added: cassandra/site/src/doc/3.7/_sources/development/index.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/index.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/index.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/index.txt Wed Aug 31
10:55:41 2016
@@ -0,0 +1,28 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Cassandra Development
+*********************
+
+.. toctree::
+ :maxdepth: 2
+
+ ide
+ testing
+ patches
+ code_style
+ how_to_review
+ how_to_commit
Added: cassandra/site/src/doc/3.7/_sources/development/patches.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/patches.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/patches.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/patches.txt Wed Aug 31
10:55:41 2016
@@ -0,0 +1,125 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Contributing Code Changes
+*************************
+
+Choosing What to Work on
+========================
+
+Submitted patches can include bug fixes, changes to the Java code base,
improvements for tooling (both Java or Python), documentation, testing or any
other changes that requires changing the code base. Although the process of
contributing code is always the same, the amount of work and time it takes to
get a patch accepted also depends on the kind of issue you're addressing.
+
+As a general rule of thumb:
+ * Major new features and significant changes to the code based will likely
not going to be accepted without deeper discussion within the `developer
community <http://cassandra.apache.org/community/>`_
+ * Bug fixes take higher priority compared to features
+ * The extend to which tests are required depend on how likely your changes
will effect the stability of Cassandra in production. Tooling changes requires
fewer tests than storage engine changes.
+ * Less complex patches will be faster to review: consider breaking up an
issue into individual tasks and contributions that can be reviewed separately
+
+.. hint::
+
+ Not sure what to work? Just pick an issue tagged with the `low hanging
fruit label
<https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+=+12310865+AND+labels+=+lhf+AND+status+!=+resolved>`_
in JIRA, which we use to flag issues that could turn out to be good starter
tasks for beginners.
+
+Before You Start Coding
+=======================
+
+Although contributions are highly appreciated, we do not guarantee that each
contribution will become a part of Cassandra. Therefor it's generally a good
idea to first get some feedback on the things you plan to work on, especially
about any new features or major changes to the code base. You can reach out to
other developers on the mailing list or IRC channel listed on our `community
page <http://cassandra.apache.org/community/>`_.
+
+You should also
+ * Avoid redundant work by searching for already reported issues in `JIRA
<https://issues.apache.org/jira/browse/CASSANDRA>`_
+ * Create a new issue early in the process describing what you're working on -
not just after finishing your patch
+ * Link related JIRA issues with your own ticket to provide a better context
+ * Update your ticket from time to time by giving feedback on your progress
and link a GitHub WIP branch with your current code
+ * Ping people who you actively like to ask for advice on JIRA by `mentioning
users
<https://confluence.atlassian.com/conf54/confluence-user-s-guide/sharing-content/using-mentions>`_
+
+There are also some fixed rules that you need to be aware:
+ * Patches will only be applied to branches by following the release model
+ * Code must be testable
+ * Code must follow the :doc:`code_style` convention
+ * Changes must not break compatibility between different Cassandra versions
+ * Contributions must be covered by the Apache License
+
+Choosing the Right Branches to Work on
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are currently multiple Cassandra versions maintained in individual
branches:
+
+======= ======
+Version Policy
+======= ======
+3.x Tick-tock (see below)
+3.0 Bug fixes only
+2.2 Bug fixes only
+2.1 Critical bug fixes only
+======= ======
+
+Corresponding branches in git are easy to recognize as they are named
``cassandra-<release>`` (e.g. ``cassandra-3.0``). The ``trunk`` branch is an
exception, as it contains the most recent commits from all other branches and
is used for creating new branches for future tick-tock releases.
+
+Tick-Tock Releases
+""""""""""""""""""
+
+New releases created as part of the `tick-tock release process
<http://www.planetcassandra.org/blog/cassandra-2-2-3-0-and-beyond/>`_ will
either focus on stability (odd version numbers) or introduce new features (even
version numbers). Any code for new Cassandra features you should be based on
the latest, unreleased 3.x branch with even version number or based on trunk.
+
+Bug Fixes
+"""""""""
+
+Creating patches for bug fixes is a bit more complicated as this will depend
on how many different versions of Cassandra are affected. In each case, the
order for merging such changes will be ``cassandra-2.1`` -> ``cassandra-2.2``
-> ``cassandra-3.0`` -> ``cassandra-3.x`` -> ``trunk``. But don't worry,
merging from 2.1 would be the worst case for bugs that affect all currently
supported versions, which isn't very common. As a contributor, you're also not
expected to provide a single patch for each version. What you need to do
however is:
+
+ * Be clear about which versions you could verify to be affected by the bug
+ * For 2.x: ask if a bug qualifies to be fixed in this release line, as this
may be handled on case by case bases
+ * If possible, create a patch against the lowest version in the branches
listed above (e.g. if you found the bug in 3.9 you should try to fix it already
in 3.0)
+ * Test if the patch can be merged cleanly across branches in the direction
listed above
+ * Be clear which branches may need attention by the committer or even create
custom patches for those if you can
+
+Creating a Patch
+================
+
+So you've finished coding and the great moment arrives: it's time to submit
your patch!
+
+ 1. Create a branch for your changes if you haven't done already. Many
contributors name their branches based on ticket number and Cassandra version,
e.g. ``git checkout -b 12345-3.0``
+ 2. Verify that you follow Cassandra's :doc:`code_style`
+ 3. Make sure all tests (including yours) pass using ant as described in
:doc:`testing`. If you suspect a test failure is unrelated to your change, it
may be useful to check the test's status by searching the issue tracker or
looking at `CI <https://cassci.datastax.com/>`_ results for the relevant
upstream version. Note that the full test suites take many hours to complete,
so it is common to only run specific relevant tests locally before uploading a
patch. Once a patch has been uploaded, the reviewer or committer can help
setup CI jobs to run the full test suites.
+ 4. Consider going through the :doc:`how_to_review` for your code. This will
help you to understand how others will consider your change for inclusion.
+ 5. Donât make the committer squash commits for you in the root branch
either. Multiple commits are fine - and often preferable - during review stage,
especially for incremental review, but once +1d, do either:
+
+ a. Attach a patch to JIRA with a single squashed commit in it (per branch),
or
+ b. Squash the commits in-place in your branches into one
+
+ 6. Include a CHANGES.txt entry (put it at the top of the list), and format
the commit message appropriately in your patch ending with the following
statement on the last line: ``patch by X; reviewed by Y for CASSANDRA-ZZZZZ``
+ 7. When you're happy with the result, create a patch:
+
+ ::
+
+ git add <any new or modified file>
+ git commit -m '<message>'
+ git format-patch HEAD~1
+ mv <patch-file> <ticket-branchname.txt> (e.g. 12345-trunk.txt,
12345-3.0.txt)
+
+ Alternatively, many contributors prefer to make their branch available on
GitHub. In this case, fork the Cassandra repository on GitHub and push your
branch:
+
+ ::
+
+ git push --set-upstream origin 12345-3.0
+
+ 8. To make life easier for your reviewer/committer, you may want to make sure
your patch applies cleanly to later branches and create additional
patches/branches for later Cassandra versions to which your original patch does
not apply cleanly. That said, this is not critical, and you will receive
feedback on your patch regardless.
+ 9. Attach the newly generated patch to the ticket/add a link to your branch
and click "Submit Patch" at the top of the ticket. This will move the ticket
into "Patch Available" status, indicating that your submission is ready for
review.
+ 10. Wait for other developers or committers to review it and hopefully +1 the
ticket (see :doc:`how_to_review`). If your change does not receive a +1, do not
be discouraged. If possible, the reviewer will give suggestions to improve your
patch or explain why it is not suitable.
+ 11. If the reviewer has given feedback to improve the patch, make the
necessary changes and move the ticket into "Patch Available" once again.
+
+Once the review process is complete, you will receive a +1. Wait for a
committer to commit it. Do not delete your branches immediately after theyâve
been committed - keep them on GitHub for a while. Alternatively, attach a patch
to JIRA for historical record. Itâs not that uncommon for a committer to mess
up a merge. In case of that happening, access to the original code is required,
or else youâll have to redo some of the work.
+
+
Added: cassandra/site/src/doc/3.7/_sources/development/testing.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/development/testing.txt?rev=1758581&view=auto
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/development/testing.txt (added)
+++ cassandra/site/src/doc/3.7/_sources/development/testing.txt Wed Aug 31
10:55:41 2016
@@ -0,0 +1,86 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Testing
+*******
+
+Creating tests is one of the most important and also most difficult parts of
developing Cassandra. There are different ways to test your code depending on
what you're working on.
+
+
+Unit Testing
+============
+
+The most simple way to test code in Cassandra is probably by writing a unit
test. Cassandra uses JUnit as a testing framework and test cases can be found
in the ``test/unit`` directory. Ideally youâd be able to create a unit test
for your implementation that would exclusively cover the class you created (the
unit under test). Unfortunately this is not always possible and Cassandra
doesnât have a very mock friendly code base. Often youâll find yourself in
a situation where you have to make use of an embedded Cassandra instance that
youâll be able to interact with in your test. If you want to make use of CQL
in your test, you can simply extend CQLTester and use some of the convenient
helper methods such as in the following example.
+
+.. code-block:: java
+
+ @Test
+ public void testBatchAndList() throws Throwable
+ {
+ createTable("CREATE TABLE %s (k int PRIMARY KEY, l list<int>)");
+ execute("BEGIN BATCH " +
+ "UPDATE %1$s SET l = l +[ 1 ] WHERE k = 0; " +
+ "UPDATE %1$s SET l = l + [ 2 ] WHERE k = 0; " +
+ "UPDATE %1$s SET l = l + [ 3 ] WHERE k = 0; " +
+ "APPLY BATCH");
+
+ assertRows(execute("SELECT l FROM %s WHERE k = 0"),
+ row(list(1, 2, 3)));
+ }
+
+Unit tests can be run from the command line using the ``ant test`` command,
``ant test -Dtest.name=<simple_classname>`` to execute a test suite or ``ant
testsome -Dtest.name=<FQCN> -Dtest.methods=<testmethod1>[,testmethod2]`` for
individual tests. For example, to run all test methods in the
``org.apache.cassandra.cql3.SimpleQueryTest`` class, you would run::
+
+ ant test -Dtest.name=SimpleQueryTest
+
+To run only the ``testStaticCompactTables()`` test method from that class, you
would run::
+
+ ant testsome -Dtest.name=org.apache.cassandra.cql3.SimpleQueryTest
-Dtest.methods=testStaticCompactTables
+
+Long running tests
+------------------
+
+Test that consume a significant amount of time during execution can be found
in the ``test/long`` directory and executed as a regular JUnit test or
standalone program. Except for the execution time, thereâs nothing really
special about them. However, ant will execute tests under ``test/long`` only
when using the ``ant long-test`` target.
+
+DTests
+======
+
+One way of doing integration or system testing at larger scale is by using
`dtest <https://github.com/riptano/cassandra-dtest>`_, which stands for
âCassandra Distributed Testsâ. The idea is to automatically setup Cassandra
clusters using various configurations and simulate certain use cases you want
to test. This is done using Python scripts and ``ccmlib`` from the `ccm
<https://github.com/pcmanus/ccm>`_ project. Dtests will setup clusters using
this library just as you do running ad-hoc ``ccm`` commands on your local
machine. Afterwards dtests will use the `Python driver
<http://datastax.github.io/python-driver/installation.html>`_ to interact with
the nodes, manipulate the file system, analyze logs or mess with individual
nodes.
+
+Using dtests helps us to prevent regression bugs by continually executing
tests on the `CI server <http://cassci.datastax.com/>`_ against new patches.
For frequent contributors, this Jenkins is set up to build branches from their
GitHub repositories. It is likely that your reviewer will use this Jenkins
instance to run tests for your patch. Read more on the motivation behind the CI
server `here
<http://www.datastax.com/dev/blog/cassandra-testing-improvements-for-developer-convenience-and-confidence>`_.
+
+The best way to learn how to write dtests is probably by reading the
introduction "`How to Write a Dtest
<http://www.datastax.com/dev/blog/how-to-write-a-dtest>`_" and by looking at
existing, recently updated tests in the project. New tests must follow certain
`style conventions
<https://github.com/riptano/cassandra-dtest/blob/master/CONTRIBUTING.md>`_ that
are being checked before accepting contributions. In contrast to Cassandra,
dtest issues and pull-requests are managed on github, therefor you should make
sure to link any created dtests in your Cassandra ticket and also refer to the
ticket number in your dtest PR.
+
+Creating a good dtest can be tough, but it should not prevent you from
submitting patches! Please ask in the corresponding JIRA ticket how to write a
good dtest for the patch. In most cases a reviewer or committer will able to
support you, and in some cases they may offer to write a dtest for you.
+
+Performance Testing
+===================
+
+Performance tests for Cassandra are a special breed of tests that are not part
of the usual patch contribution process. In fact you can contribute tons of
patches to Cassandra without ever running performance tests. They are important
however when working on performance improvements, as such improvements must be
measurable.
+
+Cassandra Stress Tool
+---------------------
+
+TODO: `CASSANDRA-12365
<https://issues.apache.org/jira/browse/CASSANDRA-12365>`_
+
+cstar_perf
+----------
+
+Another tool available on github is `cstar_perf
<https://github.com/datastax/cstar_perf>`_ that can be used for intensive
performance testing in large clusters or locally. Please refer to the project
page on how to set it up and how to use it.
+
+
+
Modified: cassandra/site/src/doc/3.7/_sources/index.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/index.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/index.txt (original)
+++ cassandra/site/src/doc/3.7/_sources/index.txt Wed Aug 31 10:55:41 2016
@@ -34,6 +34,7 @@ Contents:
operating/index
tools/index
troubleshooting/index
+ development/index
faq/index
bugs
Modified: cassandra/site/src/doc/3.7/_sources/operating/compaction.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/operating/compaction.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/operating/compaction.txt (original)
+++ cassandra/site/src/doc/3.7/_sources/operating/compaction.txt Wed Aug 31
10:55:41 2016
@@ -45,6 +45,12 @@ Secondary index rebuild
rebuild the secondary indexes on the node.
Anticompaction
after repair the ranges that were actually repaired are split out of the
sstables that existed when repair started.
+Sub range compaction
+ It is possible to only compact a given sub range - this could be useful if
you know a token that has been
+ misbehaving - either gathering many updates or many deletes. (``nodetool
compact -st x -et y``) will pick
+ all sstables containing the range between x and y and issue a compaction
for those sstables. For STCS this will
+ most likely include all sstables but with LCS it can issue the compaction
for a subset of the sstables. With LCS
+ the resulting sstable will end up in L0.
When is a minor compaction triggered?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Modified: cassandra/site/src/doc/3.7/_sources/operating/metrics.txt
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/_sources/operating/metrics.txt?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/_sources/operating/metrics.txt (original)
+++ cassandra/site/src/doc/3.7/_sources/operating/metrics.txt Wed Aug 31
10:55:41 2016
@@ -585,6 +585,93 @@ connectedNativeClients Counter
connectedThriftClients Counter Number of clients connected to this
nodes thrift protocol server
=========================== ============== ===========
+JVM Metrics
+^^^^^^^^^^^
+
+JVM metrics such as memory and garbage collection statistics can either be
accessed by connecting to the JVM using JMX or can be exported using `Metric
Reporters`_.
+
+BufferPool
+++++++++++
+
+**Metric Name**
+ ``jvm.buffers.<direct|mapped>.<MetricName>``
+
+**JMX MBean**
+ ``java.nio:type=BufferPool name=<direct|mapped>``
+
+========================== ============== ===========
+Name Type Description
+========================== ============== ===========
+Capacity Gauge<Long> Estimated total capacity of the
buffers in this pool
+Count Gauge<Long> Estimated number of buffers in the
pool
+Used Gauge<Long> Estimated memory that the Java
virtual machine is using for this buffer pool
+========================== ============== ===========
+
+FileDescriptorRatio
++++++++++++++++++++
+
+**Metric Name**
+ ``jvm.fd.<MetricName>``
+
+**JMX MBean**
+ ``java.lang:type=OperatingSystem
name=<OpenFileDescriptorCount|MaxFileDescriptorCount>``
+
+========================== ============== ===========
+Name Type Description
+========================== ============== ===========
+Usage Ratio Ratio of used to total file
descriptors
+========================== ============== ===========
+
+GarbageCollector
+++++++++++++++++
+
+**Metric Name**
+ ``jvm.gc.<gc_type>.<MetricName>``
+
+**JMX MBean**
+ ``java.lang:type=GarbageCollector name=<gc_type>``
+
+========================== ============== ===========
+Name Type Description
+========================== ============== ===========
+Count Gauge<Long> Total number of collections that
have occurred
+Time Gauge<Long> Approximate accumulated collection
elapsed time in milliseconds
+========================== ============== ===========
+
+Memory
+++++++
+
+**Metric Name**
+ ``jvm.memory.<heap/non-heap/total>.<MetricName>``
+
+**JMX MBean**
+ ``java.lang:type=Memory``
+
+========================== ============== ===========
+Committed Gauge<Long> Amount of memory in bytes that is
committed for the JVM to use
+Init Gauge<Long> Amount of memory in bytes that the
JVM initially requests from the OS
+Max Gauge<Long> Maximum amount of memory in bytes
that can be used for memory management
+Usage Ratio Ratio of used to maximum memory
+Used Gauge<Long> Amount of used memory in bytes
+========================== ============== ===========
+
+MemoryPool
+++++++++++
+
+**Metric Name**
+ ``jvm.memory.pools.<memory_pool>.<MetricName>``
+
+**JMX MBean**
+ ``java.lang:type=MemoryPool name=<memory_pool>``
+
+========================== ============== ===========
+Committed Gauge<Long> Amount of memory in bytes that is
committed for the JVM to use
+Init Gauge<Long> Amount of memory in bytes that the
JVM initially requests from the OS
+Max Gauge<Long> Maximum amount of memory in bytes
that can be used for memory management
+Usage Ratio Ratio of used to maximum memory
+Used Gauge<Long> Amount of used memory in bytes
+========================== ============== ===========
+
JMX
^^^
Modified: cassandra/site/src/doc/3.7/architecture/dynamo.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/architecture/dynamo.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/architecture/dynamo.html (original)
+++ cassandra/site/src/doc/3.7/architecture/dynamo.html Wed Aug 31 10:55:41 2016
@@ -77,8 +77,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/architecture/guarantees.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/architecture/guarantees.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/architecture/guarantees.html (original)
+++ cassandra/site/src/doc/3.7/architecture/guarantees.html Wed Aug 31 10:55:41
2016
@@ -70,8 +70,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/architecture/index.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/architecture/index.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/architecture/index.html (original)
+++ cassandra/site/src/doc/3.7/architecture/index.html Wed Aug 31 10:55:41 2016
@@ -67,8 +67,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/architecture/overview.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/architecture/overview.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/architecture/overview.html (original)
+++ cassandra/site/src/doc/3.7/architecture/overview.html Wed Aug 31 10:55:41
2016
@@ -70,8 +70,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/architecture/storage_engine.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/architecture/storage_engine.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/architecture/storage_engine.html (original)
+++ cassandra/site/src/doc/3.7/architecture/storage_engine.html Wed Aug 31
10:55:41 2016
@@ -75,8 +75,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/bugs.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/bugs.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/bugs.html (original)
+++ cassandra/site/src/doc/3.7/bugs.html Wed Aug 31 10:55:41 2016
@@ -6,7 +6,7 @@ title: "Documentation"
is_homepage: false
is_sphinx_doc: true
-doc-title: "Reporting bugs and contributing"
+doc-title: "Reporting Bugs and Contributing"
doc-header-links: '
<link rel="top" title="Apache Cassandra Documentation v3.7"
href="index.html"/>
<link rel="next" title="Contact us" href="contactus.html"/>
@@ -61,8 +61,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1 current"><a class="current reference internal"
href="#">Reporting bugs and contributing</a></li>
+<li class="toctree-l1 current"><a class="current reference internal"
href="#">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="contactus.html">Contact us</a></li>
</ul>
@@ -77,14 +78,14 @@ extra-footer: '
<div class="container">
<div class="section" id="reporting-bugs-and-contributing">
-<h1>Reporting bugs and contributing<a class="headerlink"
href="#reporting-bugs-and-contributing" title="Permalink to this
headline">¶</a></h1>
+<h1>Reporting Bugs and Contributing<a class="headerlink"
href="#reporting-bugs-and-contributing" title="Permalink to this
headline">¶</a></h1>
<p>If you encounter a problem with Cassandra, the first places to ask for help
are the <a class="reference internal" href="contactus.html#mailing-lists"><span
class="std std-ref">user mailing list</span></a> and the <code class="docutils
literal"><span class="pre">#cassandra</span></code> <a class="reference
internal" href="contactus.html#irc-channels"><span class="std std-ref">IRC
channel</span></a>.</p>
<p>If, after having asked for help, you suspect that you have found a bug in
Cassandra, you should report it by opening a
ticket through the <a class="reference external"
href="https://issues.apache.org/jira/browse/CASSANDRA";>Apache Cassandra
JIRA</a>. Please provide as much
details as you can on your problem, and don’t forget to indicate which
version of Cassandra you are running and on which
environment.</p>
-<p>If you would like to contribute, please check <a class="reference external"
href="https://wiki.apache.org/cassandra/HowToContribute";>the section on
contributing</a> on the Cassandra wiki. Please note that the source of this
-documentation is part of the Cassandra git repository and hence contributions
to the documentation should follow the
+<p>Further details on how to contribute can be found at our <a
class="reference internal" href="development/index.html"><span
class="doc">Cassandra Development</span></a> section. Please note that the
source of
+this documentation is part of the Cassandra git repository and hence
contributions to the documentation should follow the
same path.</p>
</div>
Modified: cassandra/site/src/doc/3.7/configuration/cassandra_config_file.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/configuration/cassandra_config_file.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/configuration/cassandra_config_file.html
(original)
+++ cassandra/site/src/doc/3.7/configuration/cassandra_config_file.html Wed Aug
31 10:55:41 2016
@@ -178,6 +178,7 @@ extra-footer: '
<li class="toctree-l3"><a class="reference internal"
href="#cas-contention-timeout-in-ms"><code class="docutils literal"><span
class="pre">cas_contention_timeout_in_ms</span></code></a></li>
<li class="toctree-l3"><a class="reference internal"
href="#truncate-request-timeout-in-ms"><code class="docutils literal"><span
class="pre">truncate_request_timeout_in_ms</span></code></a></li>
<li class="toctree-l3"><a class="reference internal"
href="#request-timeout-in-ms"><code class="docutils literal"><span
class="pre">request_timeout_in_ms</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal"
href="#slow-query-log-timeout-in-ms"><code class="docutils literal"><span
class="pre">slow_query_log_timeout_in_ms</span></code></a></li>
<li class="toctree-l3"><a class="reference internal"
href="#cross-node-timeout"><code class="docutils literal"><span
class="pre">cross_node_timeout</span></code></a></li>
<li class="toctree-l3"><a class="reference internal"
href="#streaming-socket-timeout-in-ms"><code class="docutils literal"><span
class="pre">streaming_socket_timeout_in_ms</span></code></a></li>
<li class="toctree-l3"><a class="reference internal"
href="#phi-convict-threshold"><code class="docutils literal"><span
class="pre">phi_convict_threshold</span></code></a></li>
@@ -214,8 +215,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
@@ -816,6 +818,9 @@ If omitted, Cassandra will set both to 1
<div class="section" id="memtable-cleanup-threshold">
<h2><code class="docutils literal"><span
class="pre">memtable_cleanup_threshold</span></code><a class="headerlink"
href="#memtable-cleanup-threshold" title="Permalink to this
headline">¶</a></h2>
<p><em>This option is commented out by default.</em></p>
+<p>memtable_cleanup_threshold is deprecated. The default calculation
+is the only reasonable choice. See the comments on memtable_flush_writers
+for more information.</p>
<p>Ratio of occupied non-flushing memtable size to total permitted size
that will trigger a flush of the largest memtable. Larger mct will
mean larger flushes and hence less compaction, but also less concurrent
@@ -852,13 +857,28 @@ of the commitlog volume.</p>
<div class="section" id="memtable-flush-writers">
<h2><code class="docutils literal"><span
class="pre">memtable_flush_writers</span></code><a class="headerlink"
href="#memtable-flush-writers" title="Permalink to this headline">¶</a></h2>
<p><em>This option is commented out by default.</em></p>
-<p>This sets the amount of memtable flush writer threads. These will
-be blocked by disk io, and each one will hold a memtable in memory
-while blocked.</p>
-<p>memtable_flush_writers defaults to one per data_file_directory.</p>
-<p>If your data directories are backed by SSD, you can increase this, but
-avoid having memtable_flush_writers * data_file_directories > number of
cores</p>
-<p><em>Default Value:</em> 1</p>
+<p>This sets the number of memtable flush writer threads per disk
+as well as the total number of memtables that can be flushed concurrently.
+These are generally a combination of compute and IO bound.</p>
+<p>Memtable flushing is more CPU efficient than memtable ingest and a single
thread
+can keep up with the ingest rate of a whole server on a single fast disk
+until it temporarily becomes IO bound under contention typically with
compaction.
+At that point you need multiple flush threads. At some point in the future
+it may become CPU bound all the time.</p>
+<p>You can tell if flushing is falling behind using the
MemtablePool.BlockedOnAllocation
+metric which should be 0, but will be non-zero if threads are blocked waiting
on flushing
+to free memory.</p>
+<p>memtable_flush_writers defaults to two for a single data directory.
+This means that two memtables can be flushed concurrently to the single data
directory.
+If you have multiple data directories the default is one memtable flushing at
a time
+but the flush will use a thread per data directory so you will get two or more
writers.</p>
+<p>Two is generally enough to flush on a fast disk [array] mounted as a single
data directory.
+Adding more flush writers will result in smaller more frequent flushes that
introduce more
+compaction overhead.</p>
+<p>There is a direct tradeoff between number of memtables that can be flushed
concurrently
+and flush size and frequency. More is not better you just need enough flush
writers
+to never stall waiting for flushing to free memory.</p>
+<p><em>Default Value:</em> 2</p>
</div>
<div class="section" id="cdc-total-space-in-mb">
<h2><code class="docutils literal"><span
class="pre">cdc_total_space_in_mb</span></code><a class="headerlink"
href="#cdc-total-space-in-mb" title="Permalink to this headline">¶</a></h2>
@@ -1298,6 +1318,13 @@ we need to flush first so we can snapsho
<p>The default timeout for other, miscellaneous operations</p>
<p><em>Default Value:</em> 10000</p>
</div>
+<div class="section" id="slow-query-log-timeout-in-ms">
+<h2><code class="docutils literal"><span
class="pre">slow_query_log_timeout_in_ms</span></code><a class="headerlink"
href="#slow-query-log-timeout-in-ms" title="Permalink to this
headline">¶</a></h2>
+<p>How long before a node logs slow queries. Select queries that take longer
than
+this timeout to execute, will generate an aggregated log message, so that slow
queries
+can be identified. Set this value to zero to disable slow query logging.</p>
+<p><em>Default Value:</em> 500</p>
+</div>
<div class="section" id="cross-node-timeout">
<h2><code class="docutils literal"><span
class="pre">cross_node_timeout</span></code><a class="headerlink"
href="#cross-node-timeout" title="Permalink to this headline">¶</a></h2>
<p>Enable operation timeout information exchange between nodes to accurately
Modified: cassandra/site/src/doc/3.7/configuration/index.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/configuration/index.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/configuration/index.html (original)
+++ cassandra/site/src/doc/3.7/configuration/index.html Wed Aug 31 10:55:41 2016
@@ -64,8 +64,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/contactus.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/contactus.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/contactus.html (original)
+++ cassandra/site/src/doc/3.7/contactus.html Wed Aug 31 10:55:41 2016
@@ -9,7 +9,7 @@ is_sphinx_doc: true
doc-title: "Contact us"
doc-header-links: '
<link rel="top" title="Apache Cassandra Documentation v3.7"
href="index.html"/>
- <link rel="prev" title="Reporting bugs and contributing"
href="bugs.html"/>
+ <link rel="prev" title="Reporting Bugs and Contributing"
href="bugs.html"/>
'
doc-search-path: "search.html"
@@ -60,8 +60,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1 current"><a class="current reference internal"
href="#">Contact us</a><ul>
<li class="toctree-l2"><a class="reference internal"
href="#mailing-lists">Mailing lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="#irc">IRC</a></li>
@@ -115,7 +116,7 @@ following channels are available:</p>
<div class="doc-prev-next-links" role="navigation"
aria-label="footer navigation">
- <a href="bugs.html" class="btn btn-default" role="button"
title="Reporting bugs and contributing" accesskey="p"><span class="glyphicon
glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a>
+ <a href="bugs.html" class="btn btn-default" role="button"
title="Reporting Bugs and Contributing" accesskey="p"><span class="glyphicon
glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a>
</div>
Modified: cassandra/site/src/doc/3.7/cql/appendices.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/cql/appendices.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/cql/appendices.html (original)
+++ cassandra/site/src/doc/3.7/cql/appendices.html Wed Aug 31 10:55:41 2016
@@ -82,8 +82,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
Modified: cassandra/site/src/doc/3.7/cql/changes.html
URL:
http://svn.apache.org/viewvc/cassandra/site/src/doc/3.7/cql/changes.html?rev=1758581&r1=1758580&r2=1758581&view=diff
==============================================================================
--- cassandra/site/src/doc/3.7/cql/changes.html (original)
+++ cassandra/site/src/doc/3.7/cql/changes.html Wed Aug 31 10:55:41 2016
@@ -101,8 +101,9 @@ extra-footer: '
<li class="toctree-l1"><a class="reference internal"
href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../troubleshooting/index.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../development/index.html">Cassandra Development</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../faq/index.html">Frequently Asked Questions</a></li>
-<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting bugs and contributing</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="../bugs.html">Reporting Bugs and Contributing</a></li>
<li class="toctree-l1"><a class="reference internal"
href="../contactus.html">Contact us</a></li>
</ul>
@@ -122,8 +123,11 @@ extra-footer: '
<div class="section" id="id1">
<h2>3.4.3<a class="headerlink" href="#id1" title="Permalink to this
headline">¶</a></h2>
<ul class="simple">
+<li>Support for <code class="docutils literal"><span class="pre">GROUP</span>
<span class="pre">BY</span></code> (<a class="reference external"
href="https://issues.apache.org/jira/browse/CASSANDRA-10707";>CASSANDRA-10707</a>).</li>
<li>Adds a <code class="docutils literal"><span class="pre">DEFAULT</span>
<span class="pre">UNSET</span></code> option for <code class="docutils
literal"><span class="pre">INSERT</span> <span class="pre">JSON</span></code>
to ignore omitted columns (<a class="reference external"
href="https://issues.apache.org/jira/browse/CASSANDRA-11424";>CASSANDRA-11424</a>).</li>
+<li>Allows <code class="docutils literal"><span class="pre">null</span></code>
as a legal value for TTL on insert and update. It will be treated as equivalent
to</li>
</ul>
+<p>inserting a 0 (<a class="reference external"
href="https://issues.apache.org/jira/browse/CASSANDRA-12216";>CASSANDRA-12216</a>).</p>
</div>
<div class="section" id="id2">
<h2>3.4.2<a class="headerlink" href="#id2" title="Permalink to this
headline">¶</a></h2>
