[_transactions2] Part 21: Release Notes and Exposing Transactions2 (#…

…3740)

* Docs for configuration of transactions2

* Changelog

* CR comments part 1

* Add beta mention

* Remove references to new namespace

docs/source/configuration/index.rst

@@ -17,6 +17,7 @@ Configuration
    leader_config
    logging
    timestamp_client
+   internal-schemas
 
 AtlasDB Configuration
 =====================

docs/source/configuration/internal-schemas.rst

@@ -0,0 +1,34 @@
+.. _internal-schema-configuration:
+
+=============================
+Internal Schema Configuration
+=============================
+
+This document covers configuration pertaining to settings about the internal schema that AtlasDB uses for storing
+some of its state. These settings should be specified under the ``internalSchema`` key in an
+``AtlasDbRuntimeConfiguration``.
+
+For a full list of the configurations available at this block, see
+`InternalSchemaConfig.java <https://github.com/palantir/atlasdb/blob/develop/atlasdb-impl-shared/src/main/java/com/palantir/atlasdb/internalschema/InternalSchemaConfig.java>`__.
+
+Target Transactions Schema Version
+==================================
+
+.. warning::
+
+   _transactions2 is currently only supported for Cassandra and In-Memory KVSes.
+
+AtlasDB needs to persist information about the start and commit timestamps of transactions that have committed.
+This may be done in various ways, and is configurable. We currently support two strategies:
+
+- version 1, which variable-length encodes the start and commit timestamps and stores them in the ``_transactions``
+  table.
+- version 2, which variable-length encodes the start and commit timestamps following the
+  `TicketsEncodingStrategy <https://github.com/palantir/atlasdb/blob/develop/atlasdb-impl-shared/src/main/java/com/palantir/atlasdb/transaction/encoding/TicketsEncodingStrategy.java>`__,
+  storing them in the ``_transactions2`` table.
+
+If specified, this AtlasDB client will attempt to install the provided transaction schema version. This can be done in
+a live fashion without downtime, though it may take a while (in terms of AtlasDB timestamps) to take effect. If
+install is successful, a message will be logged indicating when the switch will take place. If needed, one can force
+the new version to be used by fast-forwarding the timestamp to that point. To do this, see
+:ref:`Timestamp Service Management <timestamp-service-management>`.

docs/source/release_notes/release-notes.rst

@@ -297,16 +297,29 @@ v0.118.0
     *    - Type
          - Change
 
-    *    - |devbreak| |improved|
-         - The `TableMetadata` class has been refactored to use Immutables.
-           (`Pull Request <https://github.com/palantir/atlasdb/pull/3624>`__)
+    *    - |new|
+         - AtlasDB now supports _transactions2 if backed by Cassandra KVS or In-Memory KVS.
+           This is expected to improve transaction performance by making ``putUnlessExists`` faster, and increase stability by avoiding hotspotting of the transactions table in Cassandra.
+           This is a beta feature; please contact the AtlasDB team if you are interested to use _transactions2.
+           (Many PRs; key PRs include `Pull Request 1 <https://github.com/palantir/atlasdb/pull/3706>`__,
+           `Pull Request 2 <https://github.com/palantir/atlasdb/pull/3707>`__,
+           `Pull Request 3 <https://github.com/palantir/atlasdb/pull/3726>`__,
+           `Pull Request 4 <https://github.com/palantir/atlasdb/pull/3732>`__)
 
     *    - |improved| |devbreak|
          - AtlasDB Cassandra KVS now depends on ``com.palantir.cassandra`` instead of ``org.apache.cassandra``.
            This version of Cassandra thrift client supports a ``put_unless_exists`` operation that can update multiple columns in the same row simultaneously.
            The Cassandra KVS putUnlessExists method has been updated to use the above call.
            (`Pull Request <https://github.com/palantir/atlasdb/pull/3726>`__)
 
+    *    - |devbreak| |improved|
+         - The `TableMetadata` class has been refactored to use Immutables.
+           (`Pull Request <https://github.com/palantir/atlasdb/pull/3624>`__)
+
+    *    - |new| |metrics|
+         - Transaction services now expose timer metrics indicating how long committing or getting values takes.
+           (`Pull Request <https://github.com/palantir/atlasdb/pull/3733>`__)
+
     *    - |fixed|
          - Entries with the same value in adjacent ranges in a timestamp partitioning map will now be properly coalesced, and for the purposes of coordination will not be written as new values.
            Previously, these were stored as separate entries, meaning that unnecessary values may have been written to the coordination store; this does not affect correctness, but is unperformant.

docs/source/services/timestamp_service/management.rst

@@ -1,3 +1,5 @@
+.. _timestamp-service-management:
+
 ==================
 Service Management
 ==================
@@ -22,3 +24,14 @@ on the Timelock Server. Fast forward operates by updating the last known issued
 TS.
 
 Note that fast forward is idempotent, since we use maximums. Also, fast forwarding to the past is a no-op.
+
+Fast Forward on TimeLock
+------------------------
+
+The following command needs to be run on the TimeLock leader, and will fast forward the timestamp to TS.
+
+.. code:: bash
+
+      curl -XPOST localhost:8080/timelock/api/namespace/timestamp-management/fast-forward?currentTimestamp=TS
+
+On success, timestamps serviced for this namespace will now return values greater than ``TS``.