diff --git a/.github/workflows/java-ci.yml b/.github/workflows/java-ci.yml index 5731fcd96..9523dd9b2 100644 --- a/.github/workflows/java-ci.yml +++ b/.github/workflows/java-ci.yml @@ -22,6 +22,30 @@ concurrency: cancel-in-progress: true jobs: + qdrant-compatibility: + name: Qdrant client ${{ matrix.qdrant-version }} + runs-on: ubuntu-latest + timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + qdrant-version: ['1.16.2', '1.20.0'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '21' + cache: maven + cache-dependency-path: 'java/**/pom.xml' + - name: Test async lifecycle and loopback gRPC to OTLP + working-directory: java + run: >- + mvn -B -ntp -pl traceai-java-qdrant -am + -Dqdrant.version=${{ matrix.qdrant-version }} + -Dtest=TracedQdrantClientTest,TracedQdrantWireTest + -Dsurefire.failIfNoSpecifiedTests=false test + verify: name: Build, test, and validate Central artifacts runs-on: ubuntu-latest diff --git a/java/traceai-java-qdrant/pom.xml b/java/traceai-java-qdrant/pom.xml index 2434b6603..4ec5328ca 100644 --- a/java/traceai-java-qdrant/pom.xml +++ b/java/traceai-java-qdrant/pom.xml @@ -25,11 +25,24 @@ io.qdrant client - 1.16.2 + ${qdrant.version} provided + + io.opentelemetry.proto + opentelemetry-proto + 1.0.0-alpha + test + + + + com.google.protobuf + protobuf-java + + + org.junit.jupiter junit-jupiter @@ -39,6 +52,13 @@ org.assertj assertj-core test + + + + net.bytebuddy + byte-buddy + + org.mockito diff --git a/java/traceai-java-qdrant/src/main/java/ai/traceai/qdrant/TracedQdrantClient.java b/java/traceai-java-qdrant/src/main/java/ai/traceai/qdrant/TracedQdrantClient.java index 0539d73f5..1f83eb2fe 100644 --- a/java/traceai-java-qdrant/src/main/java/ai/traceai/qdrant/TracedQdrantClient.java +++ b/java/traceai-java-qdrant/src/main/java/ai/traceai/qdrant/TracedQdrantClient.java @@ -1,325 +1,321 @@ package ai.traceai.qdrant; -import ai.traceai.*; -import io.qdrant.client.QdrantClient; -import io.qdrant.client.grpc.Points.*; -import io.qdrant.client.grpc.Common.PointId; -import io.qdrant.client.grpc.Common.Filter; -import io.qdrant.client.grpc.Collections.*; +import ai.traceai.FISpanKind; +import ai.traceai.FITracer; +import ai.traceai.SemanticConventions; +import ai.traceai.TraceAI; +import com.google.common.util.concurrent.ForwardingListenableFuture; +import com.google.common.util.concurrent.SettableFuture; +import com.google.common.util.concurrent.FutureCallback; +import com.google.common.util.concurrent.Futures; +import com.google.common.util.concurrent.ListenableFuture; +import com.google.common.util.concurrent.MoreExecutors; import io.opentelemetry.api.trace.Span; import io.opentelemetry.api.trace.StatusCode; +import io.opentelemetry.context.Context; import io.opentelemetry.context.Scope; - +import io.qdrant.client.QdrantClient; +import io.qdrant.client.grpc.Collections.CollectionOperationResponse; +import io.qdrant.client.grpc.Collections.Distance; +import io.qdrant.client.grpc.Collections.VectorParams; +import io.qdrant.client.grpc.Common.Filter; +import io.qdrant.client.grpc.Common.PointId; +import io.qdrant.client.grpc.Points.BatchResult; +import io.qdrant.client.grpc.Points.PointGroup; +import io.qdrant.client.grpc.Points.PointStruct; +import io.qdrant.client.grpc.Points.QueryPointGroups; +import io.qdrant.client.grpc.Points.QueryPoints; +import io.qdrant.client.grpc.Points.ReadConsistency; +import io.qdrant.client.grpc.Points.RetrievedPoint; +import io.qdrant.client.grpc.Points.ScoredPoint; +import io.qdrant.client.grpc.Points.SearchPoints; +import io.qdrant.client.grpc.Points.UpdateResult; +import io.qdrant.client.grpc.Points.Vectors; + +import java.time.Duration; import java.util.List; import java.util.concurrent.ExecutionException; +import java.util.function.BiConsumer; +import java.util.function.Consumer; +import java.util.function.Supplier; /** - * Instrumentation wrapper for Qdrant Java client. - * Wraps the QdrantClient to provide automatic tracing of all vector operations. + * Semantic tracing for Qdrant search, universal queries (including batch and groups), + * upsert, delete, retrieval, collection creation and collection listing. * - *

Usage:

- *
- * QdrantClient client = new QdrantClient(
- *     QdrantGrpcClient.newBuilder("localhost", 6334, false).build());
- * TracedQdrantClient traced = new TracedQdrantClient(client);
+ * 

Async methods preserve the SDK's result, failure cause and cancellation behavior. + * Spans finish on SDK completion, before the returned future exposes the outcome. + * The calling context is used as the parent and the operation span is current when + * invoking the SDK. No scope is held open while waiting. As with the SDK itself, + * applications must propagate context when scheduling their own future listeners.

* - * List<ScoredPoint> results = traced.search(SearchPoints.newBuilder() - * .setCollectionName("my-collection") - * .addAllVector(queryVector) - * .setLimit(10) - * .build()); - *
+ *

The existing blocking methods remain available and delegate to the async methods. + * Operations performed via {@link #unwrap()} are not traced by this wrapper.

*/ public class TracedQdrantClient { - private final QdrantClient client; private final FITracer tracer; - /** - * Creates a new traced Qdrant client with the given client and tracer. - * - * @param client the QdrantClient to wrap - * @param tracer the FITracer for instrumentation - */ public TracedQdrantClient(QdrantClient client, FITracer tracer) { this.client = client; this.tracer = tracer; } - /** - * Creates a new traced Qdrant client using the global TraceAI tracer. - * - * @param client the QdrantClient to wrap - */ public TracedQdrantClient(QdrantClient client) { this(client, TraceAI.getTracer()); } - /** - * Searches for similar vectors with tracing. - * Builds a SearchPoints request from the given parameters. - * - * @param collectionName the collection to search - * @param queryVector the query vector - * @param limit maximum number of results - * @return list of scored points - * @throws ExecutionException if search fails - * @throws InterruptedException if interrupted - */ public List search(String collectionName, List queryVector, int limit) throws ExecutionException, InterruptedException { - // Build SearchPoints request from simple params - SearchPoints searchRequest = SearchPoints.newBuilder() - .setCollectionName(collectionName) - .addAllVector(queryVector) - .setLimit(limit) - .build(); - - return search(searchRequest); - } - - /** - * Searches with filter and additional options with tracing. - * - * @param searchRequest the search request - * @return list of scored points - * @throws ExecutionException if search fails - * @throws InterruptedException if interrupted - */ - public List search(SearchPoints searchRequest) + return searchAsync(collectionName, queryVector, limit).get(); + } + + public List search(SearchPoints request) throws ExecutionException, InterruptedException { - Span span = tracer.startSpan("Qdrant Search", FISpanKind.RETRIEVER); + return searchAsync(request).get(); + } - try (Scope scope = span.makeCurrent()) { - // Set attributes - span.setAttribute(SemanticConventions.DB_SYSTEM, "qdrant"); - span.setAttribute(SemanticConventions.DB_VECTOR_COLLECTION_NAME, searchRequest.getCollectionName()); - span.setAttribute(SemanticConventions.RETRIEVER_TOP_K, searchRequest.getLimit()); + public ListenableFuture> searchAsync( + String collectionName, List queryVector, int limit) { + return searchAsync(SearchPoints.newBuilder().setCollectionName(collectionName) + .addAllVector(queryVector).setLimit(limit).build()); + } - // Capture vector dimensions from the repeated vector field - int vectorCount = searchRequest.getVectorCount(); - if (vectorCount > 0) { - span.setAttribute(SemanticConventions.EMBEDDING_DIMENSIONS, (long) vectorCount); - } + public ListenableFuture> searchAsync(SearchPoints request) { + return searchAsync(request, null); + } - if (searchRequest.hasFilter()) { + public ListenableFuture> searchAsync(SearchPoints request, Duration timeout) { + return traceAsync("Search", FISpanKind.RETRIEVER, request.getCollectionName(), span -> { + span.setAttribute(SemanticConventions.RETRIEVER_TOP_K, request.getLimit()); + if (request.getVectorCount() > 0) { + span.setAttribute(SemanticConventions.EMBEDDING_DIMENSIONS, (long) request.getVectorCount()); + } + if (request.hasFilter()) { span.setAttribute("qdrant.has_filter", true); } + }, () -> client.searchAsync(request, timeout), this::recordScoredPoints); + } - // Execute search - List results = client.searchAsync(searchRequest).get(); + /** Universal query, including hybrid and multi-stage requests. */ + public List query(QueryPoints request) throws ExecutionException, InterruptedException { + return queryAsync(request).get(); + } + + public ListenableFuture> queryAsync(QueryPoints request) { + return queryAsync(request, null); + } - // Capture results - span.setAttribute(SemanticConventions.DB_VECTOR_RESULTS_COUNT, (long) results.size()); - if (!results.isEmpty()) { - span.setAttribute("qdrant.top_score", results.get(0).getScore()); + /** Passes the request and optional SDK timeout through unchanged. */ + public ListenableFuture> queryAsync(QueryPoints request, Duration timeout) { + return traceAsync("Query", FISpanKind.RETRIEVER, request.getCollectionName(), span -> { + if (request.hasLimit()) { + span.setAttribute(SemanticConventions.RETRIEVER_TOP_K, request.getLimit()); } + if (request.hasFilter()) { + span.setAttribute("qdrant.has_filter", true); + } + span.setAttribute("qdrant.prefetch_count", (long) request.getPrefetchCount()); + }, () -> client.queryAsync(request, timeout), this::recordScoredPoints); + } + + public List queryBatch(String collectionName, List queries) + throws ExecutionException, InterruptedException { + return queryBatchAsync(collectionName, queries).get(); + } - span.setStatus(StatusCode.OK); - return results; + public ListenableFuture> queryBatchAsync( + String collectionName, List queries) { + return queryBatchAsync(collectionName, queries, null, null); + } - } catch (Exception e) { - tracer.setError(span, e); - throw e; - } finally { - span.end(); - } + public ListenableFuture> queryBatchAsync( + String collectionName, List queries, ReadConsistency readConsistency) { + return queryBatchAsync(collectionName, queries, readConsistency, null); + } + + public ListenableFuture> queryBatchAsync( + String collectionName, List queries, + ReadConsistency readConsistency, Duration timeout) { + return traceAsync("Query Batch", FISpanKind.RETRIEVER, collectionName, + span -> span.setAttribute("qdrant.query_count", (long) queries.size()), + () -> client.queryBatchAsync(collectionName, queries, readConsistency, timeout), + (span, results) -> { + span.setAttribute("qdrant.batch_count", (long) results.size()); + span.setAttribute(SemanticConventions.DB_VECTOR_RESULTS_COUNT, + results.stream().mapToLong(BatchResult::getResultCount).sum()); + }); + } + + public List queryGroups(QueryPointGroups request) + throws ExecutionException, InterruptedException { + return queryGroupsAsync(request).get(); + } + + public ListenableFuture> queryGroupsAsync(QueryPointGroups request) { + return queryGroupsAsync(request, null); + } + + public ListenableFuture> queryGroupsAsync(QueryPointGroups request, Duration timeout) { + return traceAsync("Query Groups", FISpanKind.RETRIEVER, request.getCollectionName(), span -> { + if (request.hasLimit()) { + span.setAttribute(SemanticConventions.RETRIEVER_TOP_K, request.getLimit()); + } + if (request.hasFilter()) { + span.setAttribute("qdrant.has_filter", true); + } + }, () -> client.queryGroupsAsync(request, timeout), (span, groups) -> { + span.setAttribute("qdrant.groups_count", (long) groups.size()); + span.setAttribute(SemanticConventions.DB_VECTOR_RESULTS_COUNT, + groups.stream().mapToLong(PointGroup::getHitsCount).sum()); + }); } - /** - * Upserts points with tracing. - * - * @param collectionName the collection name - * @param points the points to upsert - * @return the update result - * @throws ExecutionException if upsert fails - * @throws InterruptedException if interrupted - */ public UpdateResult upsert(String collectionName, List points) throws ExecutionException, InterruptedException { - Span span = tracer.startSpan("Qdrant Upsert", FISpanKind.VECTOR_DB); + return upsertAsync(collectionName, points).get(); + } - try (Scope scope = span.makeCurrent()) { - // Set attributes - span.setAttribute(SemanticConventions.DB_SYSTEM, "qdrant"); - span.setAttribute(SemanticConventions.DB_VECTOR_COLLECTION_NAME, collectionName); + public ListenableFuture upsertAsync(String collectionName, List points) { + return traceAsync("Upsert", FISpanKind.VECTOR_DB, collectionName, span -> { span.setAttribute(SemanticConventions.DB_VECTOR_UPSERT_COUNT, (long) points.size()); - - // Try to capture vector dimensions from the first point if (!points.isEmpty() && points.get(0).hasVectors()) { Vectors vectors = points.get(0).getVectors(); if (vectors.hasVector()) { span.setAttribute(SemanticConventions.EMBEDDING_DIMENSIONS, - (long) vectors.getVector().getDataCount()); + (long) vectors.getVector().getDataCount()); } } - - // Execute upsert - UpdateResult result = client.upsertAsync(collectionName, points).get(); - - // Capture result - span.setAttribute("qdrant.status", result.getStatus().name()); - - span.setStatus(StatusCode.OK); - return result; - - } catch (Exception e) { - tracer.setError(span, e); - throw e; - } finally { - span.end(); - } + }, () -> client.upsertAsync(collectionName, points), this::recordUpdate); } - /** - * Deletes points by filter with tracing. - * In Qdrant Java client v1.16.x, deleteAsync takes a Filter, not a list of PointIds. - * - * @param collectionName the collection name - * @param filter the filter to match points for deletion - * @return the update result - * @throws ExecutionException if delete fails - * @throws InterruptedException if interrupted - */ public UpdateResult delete(String collectionName, Filter filter) throws ExecutionException, InterruptedException { - Span span = tracer.startSpan("Qdrant Delete", FISpanKind.VECTOR_DB); - - try (Scope scope = span.makeCurrent()) { - // Set attributes - span.setAttribute(SemanticConventions.DB_SYSTEM, "qdrant"); - span.setAttribute(SemanticConventions.DB_VECTOR_COLLECTION_NAME, collectionName); - span.setAttribute("qdrant.has_filter", true); - - // Execute delete - UpdateResult result = client.deleteAsync(collectionName, filter).get(); - - span.setAttribute("qdrant.status", result.getStatus().name()); - span.setStatus(StatusCode.OK); - return result; + return deleteAsync(collectionName, filter).get(); + } - } catch (Exception e) { - tracer.setError(span, e); - throw e; - } finally { - span.end(); - } + public ListenableFuture deleteAsync(String collectionName, Filter filter) { + return traceAsync("Delete", FISpanKind.VECTOR_DB, collectionName, + span -> span.setAttribute("qdrant.has_filter", true), + () -> client.deleteAsync(collectionName, filter), this::recordUpdate); } - /** - * Gets points by IDs with tracing. - * - * @param collectionName the collection name - * @param pointIds the point IDs to retrieve - * @param withPayload whether to include payload - * @param withVectors whether to include vectors - * @return list of retrieved points - * @throws ExecutionException if retrieval fails - * @throws InterruptedException if interrupted - */ public List get(String collectionName, List pointIds, - boolean withPayload, boolean withVectors) + boolean withPayload, boolean withVectors) throws ExecutionException, InterruptedException { - Span span = tracer.startSpan("Qdrant Get", FISpanKind.VECTOR_DB); + return getAsync(collectionName, pointIds, withPayload, withVectors).get(); + } - try (Scope scope = span.makeCurrent()) { - // Set attributes - span.setAttribute(SemanticConventions.DB_SYSTEM, "qdrant"); - span.setAttribute(SemanticConventions.DB_VECTOR_COLLECTION_NAME, collectionName); - span.setAttribute("qdrant.requested_count", (long) pointIds.size()); - - // Execute get - List results = client.retrieveAsync( - collectionName, - pointIds, - withPayload, - withVectors, - null // readConsistency - ).get(); - - span.setAttribute("qdrant.retrieved_count", (long) results.size()); - span.setStatus(StatusCode.OK); - return results; - - } catch (Exception e) { - tracer.setError(span, e); - throw e; - } finally { - span.end(); - } + public ListenableFuture> getAsync(String collectionName, List pointIds, + boolean withPayload, boolean withVectors) { + return traceAsync("Get", FISpanKind.VECTOR_DB, collectionName, + span -> span.setAttribute("qdrant.requested_count", (long) pointIds.size()), + () -> client.retrieveAsync(collectionName, pointIds, withPayload, withVectors, null), + (span, results) -> span.setAttribute("qdrant.retrieved_count", (long) results.size())); } - /** - * Creates a collection with tracing. - * - * @param collectionName the collection name - * @param vectorSize the vector dimensions - * @param distance the distance metric - * @throws ExecutionException if creation fails - * @throws InterruptedException if interrupted - */ public void createCollection(String collectionName, int vectorSize, Distance distance) throws ExecutionException, InterruptedException { - Span span = tracer.startSpan("Qdrant Create Collection", FISpanKind.VECTOR_DB); + createCollectionAsync(collectionName, vectorSize, distance).get(); + } - try (Scope scope = span.makeCurrent()) { - // Set attributes - span.setAttribute(SemanticConventions.DB_SYSTEM, "qdrant"); - span.setAttribute(SemanticConventions.DB_VECTOR_COLLECTION_NAME, collectionName); + public ListenableFuture createCollectionAsync( + String collectionName, int vectorSize, Distance distance) { + return traceAsync("Create Collection", FISpanKind.VECTOR_DB, collectionName, span -> { span.setAttribute("qdrant.vector_size", (long) vectorSize); span.setAttribute("qdrant.distance", distance.name()); + }, () -> client.createCollectionAsync(collectionName, + VectorParams.newBuilder().setSize(vectorSize).setDistance(distance).build()), + (span, result) -> { }); + } + + public List listCollections() throws ExecutionException, InterruptedException { + return listCollectionsAsync().get(); + } - // Execute create - client.createCollectionAsync( - collectionName, - VectorParams.newBuilder() - .setSize(vectorSize) - .setDistance(distance) - .build() - ).get(); - - span.setStatus(StatusCode.OK); - - } catch (Exception e) { - tracer.setError(span, e); - throw e; - } finally { - span.end(); + public ListenableFuture> listCollectionsAsync() { + return traceAsync("List Collections", FISpanKind.VECTOR_DB, null, span -> { }, + client::listCollectionsAsync, + (span, results) -> span.setAttribute("qdrant.collections_count", (long) results.size())); + } + + private void recordScoredPoints(Span span, List results) { + span.setAttribute(SemanticConventions.DB_VECTOR_RESULTS_COUNT, (long) results.size()); + if (!results.isEmpty()) { + span.setAttribute("qdrant.top_score", results.get(0).getScore()); } } - /** - * Lists collections with tracing. - * - * @return list of collection names - * @throws ExecutionException if listing fails - * @throws InterruptedException if interrupted - */ - public List listCollections() throws ExecutionException, InterruptedException { - Span span = tracer.startSpan("Qdrant List Collections", FISpanKind.VECTOR_DB); + private void recordUpdate(Span span, UpdateResult result) { + span.setAttribute("qdrant.status", result.getStatus().name()); + } - try (Scope scope = span.makeCurrent()) { + private ListenableFuture traceAsync(String operation, FISpanKind kind, String collection, + Consumer attributes, Supplier> call, BiConsumer resultAttributes) { + Span span = tracer.startSpan("Qdrant " + operation, kind); + Context context = Context.current().with(span); + ListenableFuture future; + try (Scope scope = context.makeCurrent()) { span.setAttribute(SemanticConventions.DB_SYSTEM, "qdrant"); + if (collection != null) { + span.setAttribute(SemanticConventions.DB_VECTOR_COLLECTION_NAME, collection); + } + attributes.accept(span); + future = call.get(); + } catch (RuntimeException | Error failure) { + try { + tracer.setError(span, failure); + } finally { + span.end(); + } + throw failure; + } + // Publish the outcome only after ending the span. Returning the SDK future + // directly lets get() race its completion callback and an immediate tracer shutdown. + SettableFuture completion = SettableFuture.create(); + Futures.addCallback(future, new FutureCallback() { + @Override + public void onSuccess(T result) { + finish(span, context, () -> { + resultAttributes.accept(span, result); + span.setStatus(StatusCode.OK); + }); + completion.set(result); + } - List collections = client.listCollectionsAsync().get(); - - span.setAttribute("qdrant.collections_count", (long) collections.size()); - span.setStatus(StatusCode.OK); - return collections; + @Override + public void onFailure(Throwable failure) { + finish(span, context, () -> tracer.setError(span, failure)); + if (future.isCancelled()) { + completion.cancel(false); + } else { + completion.setException(failure); + } + } + }, MoreExecutors.directExecutor()); + return new ForwardingListenableFuture.SimpleForwardingListenableFuture(completion) { + @Override + public boolean cancel(boolean mayInterruptIfRunning) { + // Preserve whether the SDK accepts cancellation, including the interrupt + // flag. Its completion callback transfers cancellation after ending the span. + return future.cancel(mayInterruptIfRunning); + } + }; + } - } catch (Exception e) { - tracer.setError(span, e); - throw e; - } finally { - span.end(); + private void finish(Span span, Context context, Runnable attributes) { + try { + try (Scope scope = context.makeCurrent()) { + attributes.run(); + } finally { + span.end(); + } + } catch (RuntimeException ignored) { + // Optional telemetry must not change or prevent delivery of the SDK outcome. } } - /** - * Gets the underlying QdrantClient. - * - * @return the wrapped QdrantClient - */ + /** Returns the original client; operations on it bypass this wrapper. */ public QdrantClient unwrap() { return client; } diff --git a/java/traceai-java-qdrant/src/test/java/ai/traceai/qdrant/TracedQdrantClientTest.java b/java/traceai-java-qdrant/src/test/java/ai/traceai/qdrant/TracedQdrantClientTest.java new file mode 100644 index 000000000..6eb73a701 --- /dev/null +++ b/java/traceai-java-qdrant/src/test/java/ai/traceai/qdrant/TracedQdrantClientTest.java @@ -0,0 +1,350 @@ +package ai.traceai.qdrant; + +import ai.traceai.FITracer; +import ai.traceai.SemanticConventions; +import ai.traceai.TraceConfig; +import com.google.common.util.concurrent.Futures; +import com.google.common.util.concurrent.ListenableFuture; +import com.google.common.util.concurrent.SettableFuture; +import io.opentelemetry.api.common.AttributeKey; +import io.opentelemetry.api.trace.Span; +import io.opentelemetry.api.trace.StatusCode; +import io.opentelemetry.context.Scope; +import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter; +import io.opentelemetry.sdk.trace.SdkTracerProvider; +import io.opentelemetry.sdk.trace.data.SpanData; +import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor; +import io.qdrant.client.QdrantClient; +import io.qdrant.client.grpc.Collections.CollectionOperationResponse; +import io.qdrant.client.grpc.Collections.Distance; +import io.qdrant.client.grpc.Collections.VectorParams; +import io.qdrant.client.grpc.Common.Filter; +import io.qdrant.client.grpc.Common.PointId; +import io.qdrant.client.grpc.Points.*; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.EnumSource; + +import java.time.Duration; +import java.util.List; +import java.util.concurrent.CancellationException; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; + +import static org.assertj.core.api.Assertions.*; +import static org.mockito.ArgumentMatchers.*; +import static org.mockito.Mockito.*; + +class TracedQdrantClientTest { + private InMemorySpanExporter exporter; + private SdkTracerProvider provider; + private FITracer tracer; + private QdrantClient client; + private TracedQdrantClient traced; + + private static final QueryPoints QUERY = QueryPoints.newBuilder().setCollectionName("documents") + .setLimit(3).addPrefetch(PrefetchQuery.newBuilder().setLimit(20)).build(); + private static final SearchPoints SEARCH = SearchPoints.newBuilder().setCollectionName("documents") + .setLimit(3).addAllVector(List.of(0.1f, 0.2f)).setFilter(Filter.getDefaultInstance()).build(); + private static final QueryPointGroups GROUPS = QueryPointGroups.newBuilder() + .setCollectionName("documents").setGroupBy("category").setGroupSize(2).setLimit(3).build(); + private static final ScoredPoint POINT = ScoredPoint.newBuilder().setScore(0.9f).build(); + private static final UpdateResult UPDATE = UpdateResult.newBuilder().setStatus(UpdateStatus.Completed).build(); + private static final List IDS = List.of(PointId.newBuilder().setNum(42).build()); + + enum Operation { SEARCH, QUERY, BATCH, GROUPS, UPSERT, DELETE, GET, CREATE, LIST } + + @BeforeEach + void setUp() { + exporter = InMemorySpanExporter.create(); + provider = SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(exporter)).build(); + tracer = new FITracer(provider.get("qdrant-test"), config()); + client = mock(QdrantClient.class); + traced = new TracedQdrantClient(client, tracer); + } + + static TraceConfig config() { + return TraceConfig.builder().apiKey("synthetic").secretKey("synthetic") + .baseUrl("http://localhost").projectName("qdrant-test").hideErrorDetails(true).build(); + } + + @AfterEach + void tearDown() { + provider.close(); + } + + @Test + void exposesNonBlockingUniversalQuery() throws Exception { + assertThat(TracedQdrantClient.class.getMethod("queryAsync", QueryPoints.class) + .getReturnType()).isEqualTo(ListenableFuture.class); + } + + @ParameterizedTest + @EnumSource(Operation.class) + void asyncOperationsRemainOpenUntilCompletionAndPreserveResult(Operation operation) throws Exception { + SettableFuture pending = SettableFuture.create(); + AtomicReference sdkSpan = new AtomicReference<>(); + client = mock(QdrantClient.class, invocation -> { + sdkSpan.set(Span.current()); + return pending; + }); + traced = new TracedQdrantClient(client, tracer); + Span parent = provider.get("test").spanBuilder("parent").startSpan(); + ListenableFuture returned; + try (Scope ignored = parent.makeCurrent()) { + returned = invoke(operation); + assertThat(Span.current()).isSameAs(parent); + } + assertThat(returned.isDone()).isFalse(); + assertThat(exporter.getFinishedSpanItems()).isEmpty(); + assertThat(sdkSpan.get().getSpanContext().isValid()).isTrue(); + assertThat(sdkSpan.get().getSpanContext()).isNotEqualTo(parent.getSpanContext()); + + Object response = result(operation); + // Complete on another thread, with an unrelated current span. Neither the + // caller's scope nor the operation scope may leak onto this thread. + var executor = Executors.newSingleThreadExecutor(); + try { + executor.submit(() -> { + Span unrelated = provider.get("test").spanBuilder("unrelated").startSpan(); + try (Scope ignored = unrelated.makeCurrent()) { + pending.set(response); + assertThat(Span.current()).isSameAs(unrelated); + } finally { + unrelated.end(); + } + }).get(5, TimeUnit.SECONDS); + } finally { + executor.shutdownNow(); + } + assertThat(returned.get()).isSameAs(response); + List spans = exporter.getFinishedSpanItems().stream() + .filter(span -> span.getName().startsWith("Qdrant ")).toList(); + assertThat(spans).hasSize(1); + SpanData span = spans.get(0); + assertThat(span.getParentSpanId()).isEqualTo(parent.getSpanContext().getSpanId()); + assertThat(span.getSpanId()).isEqualTo(sdkSpan.get().getSpanContext().getSpanId()); + assertThat(span.getStatus().getStatusCode()).isEqualTo(StatusCode.OK); + assertThat(span.getAttributes().get(AttributeKey.stringKey(SemanticConventions.DB_SYSTEM))) + .isEqualTo("qdrant"); + assertThat(span.getAttributes().get(AttributeKey.stringKey(SemanticConventions.FI_SPAN_KIND))) + .isEqualTo(switch (operation) { + case SEARCH, QUERY, BATCH, GROUPS -> "RETRIEVER"; + default -> "VECTOR_DB"; + }); + parent.end(); + } + + @ParameterizedTest + @EnumSource(Operation.class) + void failurePreservesOriginalCauseAndRespectsErrorPrivacy(Operation operation) { + SettableFuture pending = SettableFuture.create(); + client = mock(QdrantClient.class, invocation -> pending); + traced = new TracedQdrantClient(client, tracer); + ListenableFuture future = invoke(operation); + RuntimeException failure = new IllegalStateException("private-payload-sentinel"); + pending.setException(failure); + assertThatThrownBy(future::get).isInstanceOf(ExecutionException.class).hasCause(failure); + SpanData span = onlySpan(); + assertThat(span.getStatus().getStatusCode()).isEqualTo(StatusCode.ERROR); + assertThat(span.getStatus().getDescription()).isEmpty(); + assertThat(span.getAttributes().get(AttributeKey.stringKey(SemanticConventions.ERROR_TYPE))) + .isEqualTo(IllegalStateException.class.getName()); + assertThat(span.getEvents()).hasSize(1); + assertThat(span.toString()).doesNotContain("private-payload-sentinel"); + } + + @ParameterizedTest + @EnumSource(Operation.class) + void cancellationFinishesOneSpanAndCancelsSdkFuture(Operation operation) { + SettableFuture pending = SettableFuture.create(); + client = mock(QdrantClient.class, invocation -> pending); + traced = new TracedQdrantClient(client, tracer); + ListenableFuture future = invoke(operation); + assertThat(future.cancel(true)).isTrue(); + assertThat(pending.isCancelled()).isTrue(); + assertThatThrownBy(future::get).isInstanceOf(CancellationException.class); + assertThat(onlySpan().getStatus().getStatusCode()).isEqualTo(StatusCode.ERROR); + assertThat(pending.set(result(operation))).isFalse(); + assertThat(exporter.getFinishedSpanItems()).hasSize(1); + } + + @ParameterizedTest + @EnumSource(Operation.class) + void synchronousSdkFailureFinishesSpanAndRestoresContext(Operation operation) { + IllegalArgumentException failure = new IllegalArgumentException("invalid-request"); + client = mock(QdrantClient.class, invocation -> { throw failure; }); + traced = new TracedQdrantClient(client, tracer); + Span before = Span.current(); + assertThatThrownBy(() -> invoke(operation)).isSameAs(failure); + assertThat(Span.current()).isSameAs(before); + assertThat(onlySpan().getStatus().getStatusCode()).isEqualTo(StatusCode.ERROR); + } + + @Test + void forwardsUniversalRequestTimeoutConsistencyAndCountsWithoutChangingPayloads() throws Exception { + Duration timeout = Duration.ofSeconds(7); + ReadConsistency consistency = ReadConsistency.newBuilder().setFactor(2).build(); + var queries = List.of(QUERY); + var queryResult = List.of(POINT); + var batchResult = List.of(BatchResult.newBuilder().addResult(POINT).addResult(POINT).build()); + var groupResult = List.of(PointGroup.newBuilder().addHits(POINT).addHits(POINT).build()); + when(client.queryAsync(same(QUERY), same(timeout))).thenReturn(Futures.immediateFuture(queryResult)); + when(client.queryBatchAsync(eq("documents"), same(queries), same(consistency), same(timeout))) + .thenReturn(Futures.immediateFuture(batchResult)); + when(client.queryGroupsAsync(same(GROUPS), same(timeout))).thenReturn(Futures.immediateFuture(groupResult)); + assertThat(traced.queryAsync(QUERY, timeout).get()).isSameAs(queryResult); + assertThat(traced.queryBatchAsync("documents", queries, consistency, timeout).get()).isSameAs(batchResult); + assertThat(traced.queryGroupsAsync(GROUPS, timeout).get()).isSameAs(groupResult); + verify(client).queryAsync(same(QUERY), same(timeout)); + verify(client).queryBatchAsync(eq("documents"), same(queries), same(consistency), same(timeout)); + verify(client).queryGroupsAsync(same(GROUPS), same(timeout)); + assertThat(exporter.getFinishedSpanItems()).extracting(span -> span.getAttributes() + .get(AttributeKey.longKey(SemanticConventions.DB_VECTOR_RESULTS_COUNT))) + .containsExactly(1L, 2L, 2L); + assertThat(exporter.getFinishedSpanItems().get(0).getAttributes() + .get(AttributeKey.longKey("qdrant.prefetch_count"))).isEqualTo(1L); + } + + @Test + void blockingEntryPointsStillReturnOriginalResultsWithOneSpanEach() throws Exception { + when(client.searchAsync(any(SearchPoints.class), isNull())) + .thenReturn(Futures.immediateFuture(List.of(POINT))); + when(client.queryAsync(same(QUERY), isNull())).thenReturn(Futures.immediateFuture(List.of(POINT))); + when(client.queryBatchAsync(eq("documents"), anyList(), isNull(), isNull())) + .thenReturn(Futures.immediateFuture(List.of(BatchResult.getDefaultInstance()))); + when(client.queryGroupsAsync(same(GROUPS), isNull())) + .thenReturn(Futures.immediateFuture(List.of(PointGroup.getDefaultInstance()))); + when(client.upsertAsync(eq("documents"), anyList())).thenReturn(Futures.immediateFuture(UPDATE)); + when(client.deleteAsync(eq("documents"), any(Filter.class))).thenReturn(Futures.immediateFuture(UPDATE)); + when(client.retrieveAsync(eq("documents"), same(IDS), eq(true), eq(false), isNull())) + .thenReturn(Futures.immediateFuture(List.of(RetrievedPoint.getDefaultInstance()))); + when(client.createCollectionAsync(eq("documents"), any(VectorParams.class))) + .thenReturn(Futures.immediateFuture(CollectionOperationResponse.getDefaultInstance())); + when(client.listCollectionsAsync()).thenReturn(Futures.immediateFuture(List.of("documents"))); + assertThat(traced.search("documents", List.of(0.1f, 0.2f), 3)).containsExactly(POINT); + assertThat(traced.search(SEARCH)).containsExactly(POINT); + assertThat(traced.query(QUERY)).containsExactly(POINT); + assertThat(traced.queryBatch("documents", List.of(QUERY))).hasSize(1); + assertThat(traced.queryGroups(GROUPS)).hasSize(1); + assertThat(traced.upsert("documents", List.of())).isSameAs(UPDATE); + assertThat(traced.delete("documents", Filter.getDefaultInstance())).isSameAs(UPDATE); + assertThat(traced.get("documents", IDS, true, false)).hasSize(1); + traced.createCollection("documents", 2, Distance.Cosine); + assertThat(traced.listCollections()).containsExactly("documents"); + assertThat(traced.unwrap()).isSameAs(client); + assertThat(exporter.getFinishedSpanItems()).hasSize(10); + assertThat(exporter.getFinishedSpanItems()).allMatch(span -> span.getStatus().getStatusCode() == StatusCode.OK); + } + + @Test + void preservesRejectedCancellationAndListenerExecutor() throws Exception { + SettableFuture> pending = SettableFuture.create(); + var source = new com.google.common.util.concurrent.ForwardingListenableFuture + .SimpleForwardingListenableFuture>(pending) { + @Override + public boolean cancel(boolean interrupt) { return false; } + }; + when(client.queryAsync(same(QUERY), isNull())).thenReturn(source); + var returned = traced.queryAsync(QUERY); + assertThat(returned.cancel(true)).isFalse(); + assertThat(returned.isCancelled()).isFalse(); + assertThat(returned.isDone()).isFalse(); + var listener = new AtomicReference(); + var called = new java.util.concurrent.atomic.AtomicBoolean(); + returned.addListener(() -> called.set(true), listener::set); + pending.set(List.of(POINT)); + assertThat(returned.get()).containsExactly(POINT); + assertThat(called).isFalse(); + assertThat(listener.get()).isNotNull(); + listener.get().run(); + assertThat(called).isTrue(); + assertThat(onlySpan().getStatus().getStatusCode()).isEqualTo(StatusCode.OK); + } + + @Test + void completedResultIsNotVisibleBeforeSpanEnds() throws Exception { + var ending = new java.util.concurrent.CountDownLatch(1); + var release = new java.util.concurrent.CountDownLatch(1); + var processor = new io.opentelemetry.sdk.trace.SpanProcessor() { + public boolean isStartRequired() { return false; } + public boolean isEndRequired() { return true; } + public void onStart(io.opentelemetry.context.Context parent, + io.opentelemetry.sdk.trace.ReadWriteSpan span) { } + public void onEnd(io.opentelemetry.sdk.trace.ReadableSpan span) { + ending.countDown(); + try { + assertThat(release.await(5, TimeUnit.SECONDS)).isTrue(); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + throw new AssertionError(interrupted); + } + } + }; + SettableFuture> pending = SettableFuture.create(); + when(client.queryAsync(same(QUERY), isNull())).thenReturn(pending); + var executor = Executors.newSingleThreadExecutor(); + try (var delayedProvider = SdkTracerProvider.builder().addSpanProcessor(processor).build()) { + var delayed = new TracedQdrantClient(client, new FITracer(delayedProvider.get("test"), config())); + var returned = delayed.queryAsync(QUERY); + var completion = executor.submit(() -> pending.set(List.of(POINT))); + try { + assertThat(ending.await(5, TimeUnit.SECONDS)).isTrue(); + assertThat(pending.isDone()).isTrue(); + // A blocking caller may shut down its provider immediately after get(). + // Do not expose success until the operation span has been ended. + assertThat(returned.isDone()).isFalse(); + } finally { + release.countDown(); + } + completion.get(5, TimeUnit.SECONDS); + assertThat(returned.get()).containsExactly(POINT); + } finally { + release.countDown(); + executor.shutdownNow(); + } + } + + @Test + void blockingFailureKeepsExecutionExceptionContract() { + RuntimeException failure = new IllegalStateException("offline failure"); + when(client.searchAsync(any(SearchPoints.class), isNull())).thenReturn(Futures.immediateFailedFuture(failure)); + assertThatThrownBy(() -> traced.search(SEARCH)).isInstanceOf(ExecutionException.class).hasCause(failure); + assertThat(onlySpan().getStatus().getStatusCode()).isEqualTo(StatusCode.ERROR); + } + + private SpanData onlySpan() { + assertThat(exporter.getFinishedSpanItems()).hasSize(1); + return exporter.getFinishedSpanItems().get(0); + } + + private ListenableFuture invoke(Operation operation) { + return switch (operation) { + case SEARCH -> traced.searchAsync(SEARCH); + case QUERY -> traced.queryAsync(QUERY); + case BATCH -> traced.queryBatchAsync("documents", List.of(QUERY)); + case GROUPS -> traced.queryGroupsAsync(GROUPS); + case UPSERT -> traced.upsertAsync("documents", List.of(PointStruct.getDefaultInstance())); + case DELETE -> traced.deleteAsync("documents", Filter.getDefaultInstance()); + case GET -> traced.getAsync("documents", IDS, true, false); + case CREATE -> traced.createCollectionAsync("documents", 2, Distance.Cosine); + case LIST -> traced.listCollectionsAsync(); + }; + } + + private Object result(Operation operation) { + return switch (operation) { + case SEARCH, QUERY -> List.of(POINT); + case BATCH -> List.of(BatchResult.newBuilder().addResult(POINT).build()); + case GROUPS -> List.of(PointGroup.newBuilder().addHits(POINT).build()); + case UPSERT, DELETE -> UPDATE; + case GET -> List.of(RetrievedPoint.getDefaultInstance()); + case CREATE -> CollectionOperationResponse.getDefaultInstance(); + case LIST -> List.of("documents"); + }; + } +} diff --git a/java/traceai-java-qdrant/src/test/java/ai/traceai/qdrant/TracedQdrantWireTest.java b/java/traceai-java-qdrant/src/test/java/ai/traceai/qdrant/TracedQdrantWireTest.java new file mode 100644 index 000000000..189bac438 --- /dev/null +++ b/java/traceai-java-qdrant/src/test/java/ai/traceai/qdrant/TracedQdrantWireTest.java @@ -0,0 +1,122 @@ +package ai.traceai.qdrant; + +import ai.traceai.FITracer; +import com.sun.net.httpserver.HttpServer; +import io.grpc.Server; +import io.grpc.ServerBuilder; +import io.grpc.stub.StreamObserver; +import io.opentelemetry.api.trace.Span; +import io.opentelemetry.context.Scope; +import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter; +import io.opentelemetry.proto.collector.trace.v1.ExportTraceServiceRequest; +import io.opentelemetry.proto.trace.v1.Status; +import io.opentelemetry.sdk.trace.SdkTracerProvider; +import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor; +import io.qdrant.client.QdrantClient; +import io.qdrant.client.QdrantGrpcClient; +import io.qdrant.client.grpc.Points.*; +import io.qdrant.client.grpc.PointsGrpc; +import org.junit.jupiter.api.Test; + +import java.net.InetSocketAddress; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; + +import static io.qdrant.client.ValueFactory.value; +import static org.assertj.core.api.Assertions.*; + +/** Real SDK gRPC and decoded OTLP over loopback only; no backend or API keys. */ +class TracedQdrantWireTest { + @Test + void realSdkExportsCompletedQueryAndPrivateFailureOverOtlp() throws Exception { + LinkedBlockingQueue exports = new LinkedBlockingQueue<>(); + LinkedBlockingQueue requests = new LinkedBlockingQueue<>(); + LinkedBlockingQueue> replies = new LinkedBlockingQueue<>(); + HttpServer collector = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0); + collector.createContext("/v1/traces", exchange -> { + exports.add(exchange.getRequestBody().readAllBytes()); + exchange.getResponseHeaders().add("Content-Type", "application/x-protobuf"); + exchange.sendResponseHeaders(200, -1); + exchange.close(); + }); + collector.start(); + Server server = ServerBuilder.forPort(0).addService(new PointsGrpc.PointsImplBase() { + @Override + public void query(QueryPoints request, StreamObserver responseObserver) { + requests.add(request); + replies.add(responseObserver); + } + }).build().start(); + try (var exporter = OtlpHttpSpanExporter.builder() + .setEndpoint("http://127.0.0.1:" + collector.getAddress().getPort() + "/v1/traces").build(); + var provider = SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(exporter)).build(); + var client = new QdrantClient(QdrantGrpcClient + .newBuilder("127.0.0.1", server.getPort(), false, false).build())) { + var traced = new TracedQdrantClient(client, + new FITracer(provider.get("qdrant-wire"), TracedQdrantClientTest.config())); + QueryPoints request = QueryPoints.newBuilder().setCollectionName("documents").setLimit(3) + .addPrefetch(PrefetchQuery.newBuilder().setLimit(10)).build(); + Span parent = provider.get("test").spanBuilder("parent").startSpan(); + try { + com.google.common.util.concurrent.ListenableFuture> future; + try (Scope ignored = parent.makeCurrent()) { + future = traced.queryAsync(request); + assertThat(Span.current()).isSameAs(parent); + } + assertThat(requests.poll(5, TimeUnit.SECONDS)).isEqualTo(request); + StreamObserver reply = replies.poll(5, TimeUnit.SECONDS); + assertThat(reply).isNotNull(); + assertThat(future.isDone()).isFalse(); + assertThat(exports).isEmpty(); + ScoredPoint point = ScoredPoint.newBuilder().setScore(0.9f) + .putPayload("text", value("private-response-sentinel")).build(); + reply.onNext(QueryResponse.newBuilder().addResult(point).build()); + reply.onCompleted(); + assertThat(future.get(5, TimeUnit.SECONDS)).containsExactly(point); + byte[] payload = exports.poll(5, TimeUnit.SECONDS); + assertThat(payload).isNotNull(); + var span = onlySpan(payload); + assertThat(span.getName()).isEqualTo("Qdrant Query"); + assertThat(span.getTraceId().toByteArray()).isEqualTo(parent.getSpanContext().getTraceIdBytes()); + assertThat(span.getParentSpanId().toByteArray()).isEqualTo(parent.getSpanContext().getSpanIdBytes()); + assertThat(span.getEndTimeUnixNano()).isGreaterThan(span.getStartTimeUnixNano()); + assertThat(span.getStatus().getCode()).isEqualTo(Status.StatusCode.STATUS_CODE_OK); + assertThat(span.getAttributesList()).anySatisfy(attribute -> { + assertThat(attribute.getKey()).isEqualTo("db.vector.results.count"); + assertThat(attribute.getValue().getIntValue()).isEqualTo(1); + }); + assertThat(new String(payload, StandardCharsets.ISO_8859_1)).doesNotContain("private-response-sentinel"); + + var failed = traced.queryAsync(request); + assertThat(requests.poll(5, TimeUnit.SECONDS)).isEqualTo(request); + var failureReply = replies.poll(5, TimeUnit.SECONDS); + assertThat(failureReply).isNotNull(); + failureReply.onError(io.grpc.Status.INTERNAL.withDescription("private-error-sentinel").asRuntimeException()); + assertThatThrownBy(() -> failed.get(5, TimeUnit.SECONDS)).hasMessageContaining("private-error-sentinel"); + byte[] failedPayload = exports.poll(5, TimeUnit.SECONDS); + assertThat(failedPayload).isNotNull(); + var failedSpan = onlySpan(failedPayload); + assertThat(failedSpan.getStatus().getCode()).isEqualTo(Status.StatusCode.STATUS_CODE_ERROR); + assertThat(failedSpan.getStatus().getMessage()).isEmpty(); + assertThat(failedSpan.getEventsCount()).isEqualTo(1); + assertThat(new String(failedPayload, StandardCharsets.ISO_8859_1)).doesNotContain("private-error-sentinel"); + assertThat(exports).isEmpty(); + } finally { + parent.end(); + } + } finally { + server.shutdownNow().awaitTermination(5, TimeUnit.SECONDS); + collector.stop(0); + } + } + + private io.opentelemetry.proto.trace.v1.Span onlySpan(byte[] payload) throws Exception { + var request = ExportTraceServiceRequest.parseFrom(payload); + assertThat(request.getResourceSpansCount()).isEqualTo(1); + var resource = request.getResourceSpans(0); + assertThat(resource.getScopeSpansCount()).isEqualTo(1); + assertThat(resource.getScopeSpans(0).getSpansCount()).isEqualTo(1); + return resource.getScopeSpans(0).getSpans(0); + } +}