Add ResponseMetadataListener for dataplane operation observability

[rohanshah18]

Problem

Users need visibility into the performance characteristics of Pinecone data plane operations (upsert, query, fetch, update, delete) to:

• Monitor latency in production environments
• Distinguish between server-side processing time vs network overhead
• Integrate with observability platforms (OpenTelemetry, Prometheus, Datadog, etc.)
• Debug performance issues by understanding where time is spent

Currently, the SDK provides no built-in mechanism to capture operation-level metrics or access the x-pinecone-response-duration-ms response header that Pinecone returns.

Solution

Introduce a ResponseMetadataListener callback interface that users can register via Pinecone.Builder.withResponseMetadataListener(). After each data plane operation completes, the SDK invokes the listener with a ResponseMetadata object containing:

1. Client duration - Total round-trip time measured by the SDK
2. Server duration - Processing time from x-pinecone-response-duration-ms header
3. Network overhead - Computed difference (client - server)
4. Operation details - Operation name, index, namespace, server address
5. Status info - Success/error, gRPC status code, error type

Note: This supports data plane operations via both Index.java and AsyncIndex.java.

Basic Usage

Pinecone pinecone = new Pinecone.Builder("API_KEY")
    .withResponseMetadataListener(metadata -> {
        System.out.printf("Operation: %s | Client: %dms | Server: %dms | Network: %dms%n",
            metadata.getOperationName(),
            metadata.getClientDurationMs(),
            metadata.getServerDurationMs(),
            metadata.getNetworkOverheadMs());
    })
    .build();

Index index = pinecone.getIndexConnection("my-index");
index.query(5, Arrays.asList(1.0f, 2.0f, 3.0f));
// Output: Operation: query | Client: 45ms | Server: 32ms | Network: 13ms

Example Project

Added examples/java-otel-metrics/ demonstrating full OpenTelemetry integration with:

• Prometheus for metrics storage
• Grafana for visualization
• Docker Compose for local setup

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• Infrastructure change (CI configs, etc)
• Non-code change (docs, etc)
• None of the above: (explain here)

Test Plan

1. Added unit test - ResponseMetadataTest.java
2. Added integration tests - ResponseMetadataListenerIntegrationTest.java and ResponseMetadataAsyncListenerIntegrationTest.java
3. Manual validation by running the OpenTelemetry example in examples folder