From c315862417747a2a8616facff199327eec8ab083 Mon Sep 17 00:00:00 2001 From: Ryan Bogan Date: Mon, 13 May 2024 10:44:58 -0700 Subject: [PATCH] Add KnnCircuitBreakerException and modify exception message (#1688) * Add KnnCircuitBreakerException and modify exception message Signed-off-by: Ryan Bogan * Add changelog entry and remove star import Signed-off-by: Ryan Bogan * Remove default exception constructor Signed-off-by: Ryan Bogan * Add class description and change parameter Signed-off-by: Ryan Bogan * Fix javadocs Signed-off-by: Ryan Bogan --------- Signed-off-by: Ryan Bogan --- CHANGELOG.md | 1 + .../knn/index/KnnCircuitBreakerException.java | 65 +++++++++++++++++++ .../index/mapper/KNNVectorFieldMapper.java | 5 +- .../opensearch/knn/index/OpenSearchIT.java | 8 +-- 4 files changed, 73 insertions(+), 6 deletions(-) create mode 100644 src/main/java/org/opensearch/knn/index/KnnCircuitBreakerException.java diff --git a/CHANGELOG.md b/CHANGELOG.md index de4319adf..f3d670f17 100644 --- 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 new file mode 100644 index 000000000..0bcae8dff --- /dev/null +++ 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. + * + *

Note that the detail message associated with {@code cause} is + * not 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 index b314a5dae..dd8c145db 100644 --- 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 index d82a7f98c..a03b338d0 100644 --- 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