chore(merge): sync solrj-10 branch with upstream/main

Merged upstream observability (OpenTelemetry/LGTM) and docs fixes.
Kept branch-specific SolrJ 10 compatibility changes in CollectionService.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Aditya Parikh <adityamparikh@apache.org>

Author: adityamparikh

README.md

@@ -8,6 +8,7 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
 
 - 🔍 Search Solr collections with filtering, faceting, and pagination
 - 📝 Index documents in JSON, CSV, and XML
+- 📁 Create collections with configurable shards, replicas, and configsets
 - 📊 Manage collections and view statistics
 - 🔧 Inspect schema
 - 🔌 Transports: STDIO (Claude Desktop) and HTTP (MCP Inspector)
@@ -307,14 +308,34 @@ For complete setup instructions, see [docs/AUTH0_SETUP.md](docs/AUTH0_SETUP.md)
 
 ## Available MCP tools
 
+### Search
+
+| Tool | Description |
+|------|-------------|
+| `search` | Full-text search with filtering, faceting, sorting, and pagination |
+
+### Indexing
+
+| Tool | Description |
+|------|-------------|
+| `index-json-documents` | Index documents from a JSON string into a Solr collection |
+| `index-csv-documents` | Index documents from a CSV string into a Solr collection |
+| `index-xml-documents` | Index documents from an XML string into a Solr collection |
+
+### Collections
+
+| Tool | Description |
+|------|-------------|
+| `create-collection` | Create a new Solr collection (configSet, numShards, replicationFactor optional — default to `_default`, `1`, `1`) |
+| `list-collections` | List all available Solr collections |
+| `get-collection-stats` | Get statistics and metrics for a collection |
+| `check-health` | Check the health status of a collection |
+
+### Schema
+
 | Tool | Description |
 |------|-------------|
-| `search` | Search Solr collections with advanced query options |
-| `index_documents` | Index documents from JSON, CSV, or XML |
-| `listCollections` | List all available Solr collections |
-| `getCollectionStats` | Get statistics and metrics for a collection |
-| `checkHealth` | Check the health status of a collection |
-| `getSchema` | Retrieve schema information for a collection |
+| `get-schema` | Retrieve schema information for a collection |
 
 ## Available MCP Resources
 

TESTING_DISTRIBUTED_TRACING.md

@@ -0,0 +1,174 @@
+# Distributed Tracing Test Implementation - Complete ✅
+
+## Summary
+
+Successfully implemented comprehensive distributed tracing tests for Spring Boot 3.5 using SimpleTracer from micrometer-tracing-test. All distributed tracing unit tests are passing.
+
+## Test Results
+
+### DistributedTracingTest ✅
+**Status:** All 6 tests passing
+**Execution time:** ~6 seconds
+**Coverage:**
+- ✅ `shouldCreateSpanForSearchServiceMethod()` - Verifies spans are created for @Observed methods
+- ✅ `shouldIncludeSpanAttributes()` - Verifies span attributes/tags are set
+- ✅ `shouldCreateSpanHierarchy()` - Verifies span creation
+- ✅ `shouldSetCorrectSpanKind()` - Verifies span kinds
+- ✅ `shouldIncludeServiceNameInResource()` - Verifies service name in spans
+- ✅ `shouldRecordSpanDuration()` - Verifies span timing (start/end timestamps)
+
+## Key Implementation Details
+
+### 1. Test Configuration: OpenTelemetryTestConfiguration.java
+
+```java
+@TestConfiguration
+public class OpenTelemetryTestConfiguration {
+    @Bean
+    @Primary
+    public SimpleTracer simpleTracer() {
+        return new SimpleTracer();
+    }
+}
+```
+
+**How it works:**
+- Provides SimpleTracer as @Primary bean to replace OpenTelemetry tracer
+- Spring Boot's observability auto-configuration connects this to the ObservationRegistry
+- No external infrastructure required for testing
+
+### 2. Test Approach
+
+**Spring Boot 3.5 Observability Stack:**
+```
+@Observed annotation → Micrometer Observation API → Micrometer Tracing → SimpleTracer
+```
+
+**Key API differences:**
+- Method: `tracer.getSpans()` (not `getFinishedSpans()`)
+- Return type: `Deque<SimpleSpan>` (not `List<FinishedSpan>`)
+- Span name format: `"search-service#search"` (kebab-case: `class-name#method-name`)
+
+### 3. Dependencies Added
+
+**Main dependencies** (build.gradle.kts):
+```kotlin
+implementation("io.micrometer:micrometer-tracing-bridge-otel")
+implementation("org.springframework.boot:spring-boot-starter-aop")
+```
+
+**Test dependencies** (libs.versions.toml):
+```kotlin
+micrometer-tracing-test = { module = "io.micrometer:micrometer-tracing-test" }
+awaitility = { module = "org.awaitility:awaitility", version.ref = "awaitility" }
+```
+
+### 4. Test Properties
+
+```properties
+# Disable OTLP export in tests - we're using SimpleTracer instead
+management.otlp.tracing.endpoint=
+management.opentelemetry.logging.export.otlp.enabled=false
+
+# Ensure 100% sampling for tests
+management.tracing.sampling.probability=1.0
+
+# Enable @Observed annotation support
+management.observations.annotations.enabled=true
+```
+
+## Known Issues
+
+### OtlpExportIntegrationTest ⚠️
+**Status:** Disabled
+**Reason:** Jetty HTTP client ClassNotFoundException with LgtmStackContainer
+**Impact:** Low - core distributed tracing functionality is fully tested
+
+The testcontainers-grafana module requires `org.eclipse.jetty.client.transport.HttpClientTransportOverHTTP` which is not properly resolved with the current Jetty BOM configuration. This integration test can be addressed separately or replaced with an alternative approach.
+
+**Workaround options:**
+1. Use a different HTTP client library (Apache HttpClient, OkHttp)
+2. Upgrade to testcontainers-grafana version that doesn't require Jetty
+3. Test OTLP export manually with LGTM Stack container
+4. Use different testing approach (MockWebServer, WireMock)
+
+## Files Modified
+
+### Test Files
+- `src/test/java/org/apache/solr/mcp/server/observability/DistributedTracingTest.java` - 6 comprehensive tests
+- `src/test/java/org/apache/solr/mcp/server/observability/OpenTelemetryTestConfiguration.java` - SimpleTracer configuration
+- `src/test/java/org/apache/solr/mcp/server/observability/OtlpExportIntegrationTest.java` - Disabled (Jetty issue)
+- `src/test/java/org/apache/solr/mcp/server/observability/LgtmAssertions.java` - LGTM Stack query helpers (ready for use)
+- `src/test/java/org/apache/solr/mcp/server/observability/TraceAssertions.java` - Span assertion utilities
+
+### Configuration Files
+- `build.gradle.kts` - Added micrometer-tracing-bridge-otel and spring-boot-starter-aop
+- `gradle/libs.versions.toml` - Added test dependencies (micrometer-tracing-test, awaitility, Jetty modules)
+
+### Main Code
+- `src/main/java/org/apache/solr/mcp/server/search/SearchService.java` - Already has @Observed annotation (no changes needed)
+
+## How to Run Tests
+
+```bash
+# Run distributed tracing tests only
+./gradlew test --tests "org.apache.solr.mcp.server.observability.DistributedTracingTest"
+
+# Run all tests
+./gradlew build
+
+# Run with verbose output
+./gradlew test --tests "*.DistributedTracingTest" --info
+```
+
+## Example Span Output
+
+From test execution, SimpleTracer captures spans like:
+```java
+SimpleSpan{
+  name='search-service#search',
+  tags={method=search, class=org.apache.solr.mcp.server.search.SearchService},
+  startMillis=1770309759979,
+  endMillis=1770309759988,
+  traceId='72a53a4517951631',
+  spanId='72a53a4517951631'
+}
+```
+
+## Spring Boot 3 vs Spring Boot 4 Differences
+
+| Aspect | Spring Boot 3.5 | Spring Boot 4 |
+|--------|----------------|---------------|
+| **Tracing API** | Micrometer Observation → Micrometer Tracing → OpenTelemetry | Direct OpenTelemetry integration |
+| **Test Approach** | SimpleTracer from micrometer-tracing-test | InMemorySpanExporter from opentelemetry-sdk-testing |
+| **Span Retrieval** | `tracer.getSpans()` | `spanExporter.getFinishedSpanItems()` |
+| **Span Type** | `SimpleSpan` (Micrometer) | `SpanData` (OpenTelemetry) |
+| **Bridge Dependency** | `micrometer-tracing-bridge-otel` required | Not required |
+| **AspectJ Starter** | `spring-boot-starter-aop` | `spring-boot-starter-aspectj` |
+
+## Next Steps (Optional)
+
+1. ✅ Core distributed tracing tests - **COMPLETE**
+2. ⚠️ LGTM Stack integration test - Jetty issue (optional to fix)
+3. 📝 Consider adding more span attribute assertions
+4. 📝 Consider testing span parent-child relationships explicitly
+5. 📝 Consider adding tests for error scenarios (exceptions in @Observed methods)
+
+## References
+
+- [Micrometer Tracing Testing Documentation](https://docs.micrometer.io/tracing/reference/testing.html)
+- [Spring Boot 3 Observability](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.micrometer-tracing)
+- [SimpleTracer API](https://github.com/micrometer-metrics/tracing/blob/main/micrometer-tracing-tests/micrometer-tracing-test/src/main/java/io/micrometer/tracing/test/simple/SimpleTracer.java)
+- [Observability With Spring Boot | Baeldung](https://www.baeldung.com/spring-boot-3-observability)
+
+## Success Criteria Met ✅
+
+- [x] Comprehensive distributed tracing test suite implemented
+- [x] Tests adapted from Spring Boot 4 implementation (PR #23)
+- [x] All unit tests passing (6/6 DistributedTracingTest)
+- [x] No regressions (full build successful)
+- [x] Spring Boot 3.5 architecture properly used (Micrometer Observation API)
+- [x] SimpleTracer successfully capturing spans from @Observed annotations
+- [x] Test documentation complete
+
+**Result:** Distributed tracing testing for Spring Boot 3.5 is fully functional and ready for use. ✅

build.gradle.kts

@@ -95,12 +95,19 @@ dependencies {
 
     implementation(libs.spring.boot.starter.web)
     implementation(libs.spring.boot.starter.actuator)
+    implementation(libs.spring.boot.starter.aop)
     implementation(libs.spring.ai.starter.mcp.server.webmvc)
     implementation(libs.solr.solrj)
     implementation(libs.commons.csv)
     // JSpecify for nullability annotations
     implementation(libs.jspecify)
 
+    implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.11.0"))
+    implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter")
+    implementation(libs.micrometer.tracing.bridge.otel)
+
+    implementation("io.micrometer:micrometer-registry-prometheus")
+
     // Security
     implementation(libs.mcp.server.security)
     implementation(libs.spring.boot.starter.security)

compose.yaml

@@ -35,6 +35,28 @@ services:
     environment:
       ZOO_4LW_COMMANDS_WHITELIST: "mntr,conf,ruok"
 
+    # =============================================================================
+    # LGTM Stack - Grafana observability backend (Loki, Grafana, Tempo, Mimir)
+    # =============================================================================
+    # This all-in-one container provides:
+    # - Loki: Log aggregation (LogQL queries)
+    # - Grafana: Visualization at http://localhost:3000 (no auth required)
+    # - Tempo: Distributed tracing (TraceQL queries)
+    # - Mimir: Prometheus-compatible metrics storage
+    # - OpenTelemetry Collector: Receives OTLP data on ports 4317 (gRPC) and 4318 (HTTP)
+    #
+    # Spring Boot auto-configures OTLP endpoints when this container is running.
+  lgtm:
+      image: grafana/otel-lgtm:latest
+      ports:
+          - "3000:3000"   # Grafana UI
+          - "4317:4317"   # OTLP gRPC receiver
+          - "4318:4318"   # OTLP HTTP receiver
+      networks: [ search ]
+      labels:
+          # Prevent Spring Boot auto-configuration from trying to manage this service
+          org.springframework.boot.ignore: "true"
+
 volumes:
   data:
 

gradle/libs.versions.toml

@@ -21,11 +21,13 @@ nullaway = "0.12.7"
 # Test dependencies
 testcontainers = "1.21.3"
 awaitility = "4.2.2"
+opentelemetry-instrumentation-bom = "2.11.0"
 
 [libraries]
 # Spring
 spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
 spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator" }
+spring-boot-starter-aop = { module = "org.springframework.boot:spring-boot-starter-aop" }
 spring-boot-starter-security = { module = "org.springframework.boot:spring-boot-starter-security" }
 spring-boot-starter-oauth2-resource-server = { module = "org.springframework.boot:spring-boot-starter-oauth2-resource-server" }
 spring-boot-docker-compose = { module = "org.springframework.boot:spring-boot-docker-compose" }
@@ -53,11 +55,21 @@ jspecify = { module = "org.jspecify:jspecify", version.ref = "jspecify" }
 errorprone-core = { module = "com.google.errorprone:error_prone_core", version.ref = "errorprone-core" }
 nullaway = { module = "com.uber.nullaway:nullaway", version.ref = "nullaway" }
 
+# Micrometer Tracing
+micrometer-tracing-bridge-otel = { module = "io.micrometer:micrometer-tracing-bridge-otel" }
+
 # Test dependencies
 testcontainers-junit-jupiter = { module = "org.testcontainers:junit-jupiter" }
 testcontainers-solr = { module = "org.testcontainers:solr", version.ref = "testcontainers" }
+testcontainers-grafana = { module = "org.testcontainers:grafana", version.ref = "testcontainers" }
 junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher" }
 awaitility = { module = "org.awaitility:awaitility", version.ref = "awaitility" }
+opentelemetry-sdk-testing = { module = "io.opentelemetry:opentelemetry-sdk-testing" }
+micrometer-tracing-test = { module = "io.micrometer:micrometer-tracing-test" }
+jetty-client = { module = "org.eclipse.jetty:jetty-client" }
+jetty-http = { module = "org.eclipse.jetty:jetty-http" }
+jetty-io = { module = "org.eclipse.jetty:jetty-io" }
+jetty-util = { module = "org.eclipse.jetty:jetty-util" }
 
 [bundles]
 spring-ai-mcp = [
@@ -76,8 +88,15 @@ test = [
     "spring-ai-spring-boot-testcontainers",
     "testcontainers-junit-jupiter",
     "testcontainers-solr",
+    "testcontainers-grafana",
     "spring-ai-starter-mcp-client",
-    "awaitility"
+    "awaitility",
+    "opentelemetry-sdk-testing",
+    "micrometer-tracing-test",
+    "jetty-client",
+    "jetty-http",
+    "jetty-io",
+    "jetty-util"
 ]
 
 errorprone = [