Merge pull request #463 from couchbase/3.8-api

3.8 api

Author: RichardSmedley

modules/concept-docs/pages/durability-replication-failure-considerations.adoc

@@ -19,6 +19,7 @@ This page covers the durability options offered by Couchbase Server,
 with the rest of this section covering logging, health check, and observability --
 all key to understanding the health of a complex, distributed environment.
 
+TIP: From Couchbase Server version 8.0 (including in Capella Operational), statistics from the SDK are collected automatically by the Cluster.
 
 
 include::{version-common}@sdk:shared:partial$durability-replication-failure-considerations.adoc[tag=intro]

modules/concept-docs/pages/response-time-observability.adoc

@@ -8,6 +8,15 @@
 [abstract]
 {description}
 
+
+[TIP] 
+====
+In addition to Tracing and other metrics, and client logging, SDK is telemetry is also sent to the Server -- available from 8.0, and in new Capella Operational clusters -- for ingestion with other Prometheus metrics.
+Capella Operatioal exposes these metrics through the UI.
+====
+
+
+
 include::{version-common}@sdk:shared:partial$rto.adoc[tag=rto]
 
 

modules/devguide/examples/java/ParameterizedVectorQuery.java

@@ -0,0 +1,44 @@
+import com.couchbase.client.core.error.CouchbaseException;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.ClusterOptions;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.query.QueryResult;
+import static com.couchbase.client.java.query.QueryOptions.queryOptions;
+
+public class ParameterizedVectorQuery {
+  static String connectionString = "couchbases://cb.<your-endpoint-here>.cloud.couchbase.com";
+  static String username = "Administrator";
+  static String password = "password";
+
+ public static void main(String[] args) throws Exception {
+    Cluster cluster = Cluster.connect(
+    connectionString,
+    ClusterOptions.clusterOptions(username, password).environment(env -> {
+    env.applyProfile("wan-development");
+    })
+    );
+
+    { 
+      try {
+// tag::parameterized[]
+	final QueryResult result = cluster.query(
+        "SELECT d.id, d.question, d.wanted_similar_color_from_search, " +
+        "  ARRAY_CONCAT( " +
+          "d.couchbase_search_query.knn[0].vector[0:4], " +
+          "['...'] " +
+        ") AS vector " +
+	    "FROM `vector-sample`.`color`.`rgb-questions` AS d " +
+		"WHERE d.id = $id;",
+	queryOptions()
+		.parameters(JsonObject.create().put("id", "#87CEEB")));
+
+        for (JsonObject row : result.rowsAsObject()) {
+          System.out.println(row);
+          }
+// end::parameterized[]
+      } catch (CouchbaseException ex) {
+        ex.printStackTrace();
+      }
+    }
+  }
+}

modules/devguide/examples/java/SimpleVectorQuery.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2021 Couchbase, Inc.
+ *
+ * Licensed 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.
+ */
+
+// tag::imports[]
+import com.couchbase.client.core.error.CouchbaseException;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.ClusterOptions;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.query.QueryResult;
+import static com.couchbase.client.java.query.QueryOptions.queryOptions;
+// tag::imports[]
+
+public class SimpleVectorQuery {
+  static String connectionString = "couchbases://cb.<your-endpoint-here>.cloud.couchbase.com";
+  static String username = "Administrator";
+  static String password = "password";
+
+  public static void main(String[] args) throws Exception {
+    Cluster cluster = Cluster.connect(
+    connectionString,
+    ClusterOptions.clusterOptions(username, password).environment(env -> {
+    env.applyProfile("wan-development");
+    })
+    );
+
+    { 
+      try {
+        // tag::hyperscale[]
+        QueryResult result = cluster.query(
+        "SELECT d.id, d.question, d.wanted_similar_color_from_search, " +
+        "  ARRAY_CONCAT( " +
+          "d.couchbase_search_query.knn[0].vector[0:4], " +
+          "['...'] " +
+        ") AS vector " +
+        "FROM `vector-sample`.`color`.`rgb-questions` AS d " +
+        "WHERE d.id = '#87CEEB';",
+        queryOptions().metrics(true));
+
+        for (JsonObject row : result.rowsAsObject()) {
+          System.out.println(row);
+        }
+        // end::hyperscale[]
+      } catch (CouchbaseException ex) {
+        ex.printStackTrace();
+      }
+    }
+  }
+}

modules/devguide/examples/striptags.sh

@@ -255,3 +255,29 @@ Note that you need to run this command before any of the SDK code is initialized
 Once the SDK writes the logs with the tags to a file, you can then use the xref:7.2@server:cli:cbcli/cblogredaction.adoc[`cblogredaction` tool] to obfuscate the log.
 
 * You may wish to read more on Log Redaction xref:7.2@server:manage:manage-logging/manage-logging.adoc#understanding_redaction[in the Server docs].
+
+== SDK Telemetry from the Server
+
+In addition to Tracing and other metrics, and client logging, SDK is telemetry is also sent to the Server -- available from 8.0, and in new Capella Operational clusters -- for ingestion with other Prometheus metrics.
+Capella Operatioal exposes these metrics through the UI.
+
+For self-managed Server, collection can be disabled and enabled through the REST API:
+
+[source,console]
+----
+curl --user Administrator:password http://172.17.0.2:8091/settings/appTelemetry -d enabled=true
+----
+
+And the Prometheus-format metrics fetched with:
+
+[source,console]
+----
+curl --user Administrator:password http://172.17.0.2:8091/metrics
+----
+
+There may be advantages to collecting information this way,
+but note that metrics are collected per node,
+and a central Prometheus instance should be set to collect all metrics so that information is not lost in case of a sudden failover.
+
+Also note that if the cluster is behind a load balancer, the collected metrics may not accurately record the actual correct node with which the SDK interacts.
+

modules/howtos/pages/collecting-information-and-logging.adoc

@@ -8,6 +8,19 @@
 
 For a high-level overview of this feature, see xref:concept-docs:encryption.adoc[].
 
+[TIP]
+.Native Encryption at Rest
+====
+Server 8.x (and new Capella Operational clusters) offer xref:server:learn:security/native-encryption-at-rest-overview.adoc[encryption at rest].
+It's a comprehensive way of encrypting all data in a non-ephemeral bucket,
+as well as logs, configuration data, and audit data.
+However, you may prefer the relative simplicity of key management in Field Level Encryption for use cases where there are a limited number of data to be encrypted.
+====
+
+
+
+
+
 [#package]
 == Packaging
 
@@ -179,47 +192,10 @@ include::devguide:example$java/EncryptingUsingSDK.java[tag=encrypting_using_sdk_
 [#migration-from-sdk2]
 == Migrating from SDK 2
 
-WARNING: SDK 2 cannot read fields encrypted by SDK 3.
-
-It's inadvisable to have both the old and new versions of your application active at the same time.
-The simplest way to migrate is to do an offline upgrade during a scheduled a maintenance window.
-For an online upgrade without downtime, consider a https://en.wikipedia.org/wiki/Blue-green_deployment[blue-green deployment^].
-
-SDK 3 requires additional configuration to read fields encrypted by SDK 2.
-The rest of this section describes how to configure Field-Level Encryption in SDK 3 for backwards compatibility with SDK 2.
-
-[#configure-field-name-prefix]
-=== Changing the field name prefix
-
-In SDK 2, the default prefix for encrypted field names was `\__crypt_`.
-This caused problems for Couchbase Sync Gateway, which does not like field names to begin with an underscore.
-In SDK 3, the default prefix is `encrypted$`.
-
-For compatibility with SDK 2, you can configure the `CryptoManager` to use the old `\__crypt_` prefix:
-
-[source,java]
-----
-include::devguide:example$java/EncryptingUsingSDK.java[tag=legacy_field_name_prefix,indent=0]
-----
-
-Alternatively, you can https://forums.couchbase.com/t/replacing-field-name-prefix/28786[rename the existing fields] using a {sqlpp_url}[{sqlpp} (formerly N1QL)] statement.
-
-WARNING: In SDK 2, only top-level fields could be encrypted.
-SDK 3 allows encrypting fields at any depth.
-If you decide to rename the existing fields, make sure to do so _before_ writing any encrypted fields below the top level, otherwise it may be difficult to rename the nested fields using a generic {sqlpp} statement.
-
+SDK 2.x reached end-of-life long ago,
+but should you have fields encrypted by SDK 2.x, and the need to read them from SDK 3.x, 
+then follow the steps in the https://docs-archive.couchbase.com/java-sdk/3.4/howtos/encrypting-using-sdk.html#migration-from-sdk2[archived documents].
 
-[#configure-legacy-decrypters]
-=== Enabling decrypters for legacy algorithms
-
-The encryption algorithms used by SDK 2 are deprecated, and are no longer used for encrypting new data.
-To enable decrypting fields written by SDK 2, register the legacy decrypters when configuring the `CryptoManager`:
-
-[source,java]
-----
-include::devguide:example$java/EncryptingUsingSDK.java[tag=legacy_decrypters,indent=0]
-----
 
-NOTE: The legacy decrypters require a mapping function.
-For AES, this function accepts an encryption key name and returns the corresponding signing key name.
-For RSA, this function accepts a public key name and returns the corresponding private key name.
+IMPORTANT: The encryption algorithms used by SDK 2 are deprecated, and are no longer used for encrypting new data.
+Do not rely on the security of outdated encryption algorithms.