Add KnnCircuitBreakerException and modify exception message (opensear…

…ch-project#1688) * Add KnnCircuitBreakerException and modify exception message Signed-off-by: Ryan Bogan <[email protected]> * Add changelog entry and remove star import Signed-off-by: Ryan Bogan <[email protected]> * Remove default exception constructor Signed-off-by: Ryan Bogan <[email protected]> * Add class description and change parameter Signed-off-by: Ryan Bogan <[email protected]> * Fix javadocs Signed-off-by: Ryan Bogan <[email protected]> --------- Signed-off-by: Ryan Bogan <[email protected]>
ryanbogan · May 13, 2024 · c315862 · c315862
1 parent 011775a
commit c315862
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased 2.x](https://github.com/opensearch-project/k-NN/compare/2.14...2.x)
 ### Features
 ### Enhancements
+* Add KnnCircuitBreakerException and modify exception message [#1688](https://github.com/opensearch-project/k-NN/pull/1688)
 ### Bug Fixes
 * Block commas in model description [#1692](https://github.com/opensearch-project/k-NN/pull/1692)
 ### Infrastructure

diff --git a/src/main/java/org/opensearch/knn/index/KnnCircuitBreakerException.java b/src/main/java/org/opensearch/knn/index/KnnCircuitBreakerException.java
@@ -0,0 +1,65 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+package org.opensearch.knn.index;
+
+/**
+ * An exception to be thrown when the k-NN circuit breaker is triggered.
+ */
+public class KnnCircuitBreakerException extends RuntimeException {
+
+    /**
+     * Constructs a KnnCircuitBreakerException with the specified detail
+     * message.  A detail message is a String that describes this particular
+     * exception.
+     *
+     * @param message the String that contains a detailed message
+     */
+    public KnnCircuitBreakerException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new exception with the specified detail message and
+     * cause.
+     *
+     * <p>Note that the detail message associated with {@code cause} is
+     * <i>not</i> automatically incorporated in this exception's detail
+     * message.
+     *
+     * @param  message the detail message (which is saved for later retrieval
+     *         by the {@link Throwable#getMessage()} method).
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link Throwable#getCause()} method).  (A {@code null} value
+     *         is permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public KnnCircuitBreakerException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Constructs a new exception with the specified cause and a detail
+     * message of {@code (cause==null ? null : cause.toString())} (which
+     * typically contains the class and detail message of {@code cause}).
+     * This constructor is useful for exceptions that are little more than
+     * wrappers for other throwables (for example, {@link
+     * java.security.PrivilegedActionException}).
+     *
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link Throwable#getCause()} method).  (A {@code null} value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public KnnCircuitBreakerException(Throwable cause) {
+        super(cause);
+    }
+}
diff --git a/src/main/java/org/opensearch/knn/index/mapper/KNNVectorFieldMapper.java b/src/main/java/org/opensearch/knn/index/mapper/KNNVectorFieldMapper.java
@@ -42,6 +42,7 @@
 import org.opensearch.index.query.QueryShardContext;
 import org.opensearch.index.query.QueryShardException;
 import org.opensearch.knn.common.KNNConstants;
+import org.opensearch.knn.index.KnnCircuitBreakerException;
 import org.opensearch.knn.index.KNNMethodContext;
 import org.opensearch.knn.index.KNNSettings;
 import org.opensearch.knn.index.KNNVectorIndexFieldData;
@@ -624,8 +625,8 @@ protected boolean isFaissSQClipToFP16RangeEnabled(MethodComponentContext methodC
 
     void validateIfCircuitBreakerIsNotTriggered() {
         if (KNNSettings.isCircuitBreakerTriggered()) {
-            throw new IllegalStateException(
-                "Indexing knn vector fields is rejected as circuit breaker triggered. Check _opendistro/_knn/stats for detailed state"
+            throw new KnnCircuitBreakerException(
+                "Parsing the created knn vector fields prior to indexing has failed as the circuit breaker triggered.  This indicates that the cluster is low on memory resources and cannot index more documents at the moment. Check _plugins/_knn/stats for the circuit breaker status."
             );
         }
     }

diff --git a/src/test/java/org/opensearch/knn/index/OpenSearchIT.java b/src/test/java/org/opensearch/knn/index/OpenSearchIT.java
@@ -189,8 +189,8 @@ public void testAddDoc_blockedWhenCbTrips() throws Exception {
 
         Float[] vector = { 6.0f, 6.0f };
         ResponseException ex = expectThrows(ResponseException.class, () -> addKnnDoc(INDEX_NAME, "1", FIELD_NAME, vector));
-        String expMessage = "Indexing knn vector fields is rejected as circuit breaker triggered."
-            + " Check _opendistro/_knn/stats for detailed state";
+        String expMessage =
+            "Parsing the created knn vector fields prior to indexing has failed as the circuit breaker triggered.  This indicates that the cluster is low on memory resources and cannot index more documents at the moment. Check _plugins/_knn/stats for the circuit breaker status.";
         assertThat(EntityUtils.toString(ex.getResponse().getEntity()), containsString(expMessage));
 
         // reset
@@ -207,8 +207,8 @@ public void testUpdateDoc_blockedWhenCbTrips() throws Exception {
         updateClusterSettings("knn.circuit_breaker.triggered", "true");
         Float[] updatedVector = { 8.0f, 8.0f };
         ResponseException ex = expectThrows(ResponseException.class, () -> updateKnnDoc(INDEX_NAME, "1", FIELD_NAME, vector));
-        String expMessage = "Indexing knn vector fields is rejected as circuit breaker triggered."
-            + " Check _opendistro/_knn/stats for detailed state";
+        String expMessage =
+            "Parsing the created knn vector fields prior to indexing has failed as the circuit breaker triggered.  This indicates that the cluster is low on memory resources and cannot index more documents at the moment. Check _plugins/_knn/stats for the circuit breaker status.";
         assertThat(EntityUtils.toString(ex.getResponse().getEntity()), containsString(expMessage));
 
         // reset