Claude/code quality fixes

.gitignore

@@ -40,3 +40,6 @@ out/
 .env
 .auth-token
 *.token
+
+### Git worktrees ###
+.worktrees/

README.md

@@ -13,6 +13,7 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
 - 🔧 Inspect schema
 - 🔌 Transports: STDIO (Claude Desktop) and HTTP (MCP Inspector)
 - 🔐 OAuth2 security with Auth0 (HTTP mode only)
+- 📈 OpenTelemetry observability: metrics, traces, logs (HTTP mode only)
 - 🐳 Docker images built with Jib
 
 ## Get started (users)
@@ -379,6 +380,7 @@ The `solr://{collection}/schema` resource supports autocompletion for the `{coll
 ## Documentation
 
 - [Auth0 Setup (OAuth2 configuration)](docs/AUTH0_SETUP.md)
+- [Observability Guide (metrics, traces, logs)](dev-docs/Observability.md)
 
 ## Contributing
 

build.gradle.kts

@@ -87,22 +87,25 @@ configurations {
 
 repositories {
     mavenCentral()
+    maven { url = uri("https://repo.spring.io/milestone") }
 }
 
 dependencies {
 
-    developmentOnly(libs.bundles.spring.boot.dev)
+    developmentOnly(libs.spring.boot.docker.compose)
+    developmentOnly(libs.spring.ai.spring.boot.docker.compose) {
+        exclude(group = "org.springframework.boot", module = "spring-boot-starter-mongodb")
+    }
 
-    implementation(libs.spring.boot.starter.web)
+    implementation(libs.spring.boot.starter.webmvc)
+    implementation(libs.spring.boot.starter.json)
     implementation(libs.spring.boot.starter.actuator)
     implementation(libs.spring.boot.starter.aop)
     implementation(libs.spring.ai.starter.mcp.server.webmvc)
     implementation(libs.solr.solrj) {
         exclude(group = "org.apache.httpcomponents")
     }
     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")
@@ -115,6 +118,15 @@ dependencies {
     implementation(libs.spring.boot.starter.security)
     implementation(libs.spring.boot.starter.oauth2.resource.server)
 
+    // OpenTelemetry (HTTP mode only - for metrics, tracing, and log export)
+    implementation(libs.spring.boot.starter.opentelemetry)
+    implementation(libs.opentelemetry.logback.appender)
+    implementation("io.micrometer:micrometer-tracing-bridge-otel")
+    runtimeOnly(libs.micrometer.registry.otlp)
+
+    // AspectJ (required for @Observed annotation support in Spring Boot 4)
+    implementation(libs.spring.boot.starter.aspectj)
+
     // Error Prone and NullAway for null safety analysis
     errorprone(libs.errorprone.core)
     errorprone(libs.nullaway)
@@ -126,8 +138,18 @@ dependencies {
 dependencyManagement {
     imports {
         mavenBom("org.springframework.ai:spring-ai-bom:${libs.versions.spring.ai.get()}")
-        // Align Jetty family to 10.x compatible with SolrJ 9.x
-        mavenBom("org.eclipse.jetty:jetty-bom:${libs.versions.jetty.get()}")
+    }
+}
+
+// Force opentelemetry-proto to a version compiled with protobuf 3.x
+// This resolves NoSuchMethodError with protobuf 4.x
+// See: https://github.com/micrometer-metrics/micrometer/issues/5658
+configurations.all {
+    resolutionStrategy.eachDependency {
+        if (requested.group == "io.opentelemetry.proto" && requested.name == "opentelemetry-proto") {
+            useVersion("1.3.2-alpha")
+            because("Version 1.8.0-alpha has protobuf 4.x incompatibility causing NoSuchMethodError")
+        }
     }
 }
 

compose.yaml

@@ -35,27 +35,33 @@ 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.
+  # =============================================================================
+  # OpenTelemetry LGTM Stack (HTTP mode only)
+  # =============================================================================
+  # Provides a complete observability stack for local development:
+  # - Grafana: Visualization dashboards (http://localhost:3000)
+  # - Loki: Log aggregation
+  # - Tempo: Distributed tracing
+  # - Mimir: Metrics storage (Prometheus-compatible)
+  # - OpenTelemetry Collector: Receives OTLP data on ports 4317 (gRPC) and 4318 (HTTP)
+  #
+  # Usage:
+  #   docker compose up -d lgtm   # Start only the observability stack
+  #   docker compose up -d        # Start everything including Solr
+  #
+  # Access Grafana at http://localhost:3000 (no authentication required)
+  # Pre-configured datasources for Loki, Tempo, and Mimir are available.
   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"
+    image: grafana/otel-lgtm:latest
+    ports:
+      - "3000:3000"   # Grafana UI
+      - "4317:4317"   # OTLP gRPC receiver
+      - "4318:4318"   # OTLP HTTP receiver
+    networks: [ search ]
+    environment:
+      # Disable authentication for local development
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+      GF_AUTH_ANONYMOUS_ORG_ROLE: "Admin"
 
 volumes:
   data: