docs: Fix misleading claims — outbox auto-config, tracer example, missing properties (#104)

* feat: Implement OpenTelemetry ScimTracer + fix misleading docs (#105)

OpenTelemetryScimTracer auto-configures when OpenTelemetry is on the
classpath and a Tracer bean is available:
- Wraps SCIM operations in spans with attributes
- Records exceptions with StatusCode.ERROR
- Returns trace ID as correlation ID for MDC and events
- Backs off when custom ScimTracer bean provided
- Disabled via scim.tracing.enabled=false

Devil's Advocate fixes:
- HIGH: Nested @configuration for double classpath safety
- MEDIUM: scope.close() before span.end() (correct OTel ordering)
- MEDIUM: Fixed docs reference to non-existent Spring Boot starter
- MEDIUM: Added auto-configuration tests (bean creation + property gate)

Also fixes:
- outbox-pattern.md: Removed false auto-config claim
- README.md: Added scim.idp.claims.* and scim.tracing.enabled properties
- observability.md: Real feature docs replacing pseudocode

Tests: 6 unit + 2 auto-config tests

Closes #105

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: Add OpenTelemetry tracing to fullstack Spring sample

- Add opentelemetry-api, opentelemetry-sdk, opentelemetry-exporter-otlp deps
- Add TracingConfig.java creating OTel Tracer bean with OTLP/gRPC exporter
- Add Jaeger service to docker-compose.yml (observability profile)
- Add OTEL_EXPORTER_OTLP_ENDPOINT env var to backend service
- Update services table with Prometheus, Grafana, and Jaeger rows

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: marcosbarbero

README.md

@@ -16,7 +16,7 @@ A modern, Kotlin-first SCIM 2.0 (RFC 7643/7644) SDK for the JVM with full Java i
 - **Spring Boot starter**: Auto-configuration with sensible defaults
 - **Works without Spring**: Use with any JVM HTTP framework
 - **OOTB persistence**: JPA adapter with reference schemas for PostgreSQL, MySQL, Oracle, MSSQL, H2
-- **Observability**: Metrics (Micrometer), tracing, structured logging, event system
+- **Observability**: Metrics (Micrometer), tracing (OpenTelemetry), structured logging (MDC), event system
 - **Type-safe client**: Fluent API with Kotlin DSLs for filters, patches, searches
 - **RFC 9457 ProblemDetail**: Content-negotiated error responses
 - **Extensible**: SPI for serialization, HTTP transport, identity, authorization, events
@@ -215,13 +215,16 @@ var publisher = new CompositeEventPublisher(outboundPublisher, auditPublisher);
 
 ## Observability
 
-The SDK provides built-in observability via [Micrometer](https://micrometer.io/) metrics, structured logging, and event correlation.
+The SDK provides built-in observability:
 
-See the [Observability Guide](docs/observability.md) for details.
+- **Metrics** — [Micrometer](https://micrometer.io/) auto-configured with Prometheus, Grafana dashboard included
+- **Tracing** — [OpenTelemetry](https://opentelemetry.io/) auto-configured when on classpath (spans, trace IDs, exception recording)
+- **Structured logging** — SLF4J MDC with `scim.correlationId`, `scim.operation`, `scim.resourceType`
+- **Event correlation** — all events carry the tracer's correlation ID
 
-### Quick Start (Spring Boot)
+See the [Observability Guide](docs/observability.md) for configuration, metrics reference, and custom implementation examples.
 
-Add Micrometer and actuator:
+### Quick Start (Spring Boot)
 
 ```yaml
 management:
@@ -231,7 +234,7 @@ management:
         include: health,prometheus,metrics
 ```
 
-Metrics are automatically recorded for all SCIM operations. See the [Spring Boot full-stack sample](scim2-sdk-samples/sample-fullstack-spring/) for a complete example with Prometheus + Grafana.
+Metrics and tracing are automatically recorded for all SCIM operations. See the [Spring Boot full-stack sample](scim2-sdk-samples/sample-fullstack-spring/) for a complete example with Prometheus + Grafana.
 
 ## Sample Applications
 
@@ -278,12 +281,19 @@ All properties are optional with sensible defaults:
 | `scim.persistence.table-name` | `scim_resources` | Database table name for SCIM resource storage |
 | `scim.persistence.schema-name` | *(none)* | Database schema name (e.g., `scim`) — if set, the table is qualified as `schema.table` |
 | `scim.persistence.auto-migrate` | `false` | Run [Flyway](https://flywaydb.org/) migration on startup to create the `scim_resources` table automatically |
+| `scim.tracing.enabled` | `true` | Enable OpenTelemetry tracing auto-configuration. Set to `false` to disable even when OpenTelemetry is on the classpath |
 | `scim.client.base-url` | *(none)* | Base URL of the remote SCIM Service Provider — when set, auto-configures a `ScimClient` bean |
 | `scim.client.connect-timeout` | `10s` | TCP connection timeout for the SCIM client |
 | `scim.client.read-timeout` | `30s` | Read timeout for the SCIM client |
 | `scim.idp.provider` | *(none)* | Identity Provider type: `keycloak`, `okta`, `azure-ad`, `ping-federate`, `auth0` — auto-configures the corresponding `IdentityResolver` |
 | `scim.idp.client-id` | *(none)* | Client ID for Keycloak client-role extraction |
 | `scim.idp.namespace` | *(none)* | Auth0 custom namespace for role claims |
+| `scim.idp.claims.subject` | `sub` | JWT claim for subject |
+| `scim.idp.claims.email` | `email` | JWT claim for email |
+| `scim.idp.claims.name` | `name` | JWT claim for name |
+| `scim.idp.claims.roles` | `roles` | JWT claim for roles |
+| `scim.idp.claims.groups` | `groups` | JWT claim for groups |
+| `scim.idp.claims.custom` | `{}` | Additional custom claim mappings (key-value pairs) |
 
 ## Database Support
 

docs/observability.md

@@ -200,30 +200,52 @@ With Spring Boot, register it as a bean and the auto-configuration will use it i
 fun scimMetrics(): ScimMetrics = DatadogScimMetrics(statsdClient)
 ```
 
+### OpenTelemetry Tracing
+
+The SDK includes `OpenTelemetryScimTracer`, which auto-configures when OpenTelemetry is on the classpath. Add the dependency:
+
+```xml
+<dependency>
+    <groupId>io.opentelemetry</groupId>
+    <artifactId>opentelemetry-api</artifactId>
+</dependency>
+```
+
+When an `io.opentelemetry.api.trace.Tracer` bean is available (e.g., via OpenTelemetry's Spring Boot instrumentation or a custom `Tracer` bean), the auto-configuration registers an `OpenTelemetryScimTracer` that:
+
+- Wraps every SCIM operation in an OpenTelemetry span with attributes
+- Records exceptions with `StatusCode.ERROR` and `recordException`
+- Provides the current trace ID as the correlation ID for MDC and events
+
+No additional configuration is needed. To disable tracing while keeping OpenTelemetry on the classpath:
+
+```yaml
+scim:
+  tracing:
+    enabled: false
+```
+
+The `@ConditionalOnMissingBean` guard means you can still provide your own `ScimTracer` bean to override it.
+
 ### Custom ScimTracer
 
-To provide your own tracer (e.g., for OpenTelemetry spans), implement `ScimTracer`:
+To provide a custom tracer implementation, implement the `ScimTracer` interface:
 
 ```kotlin
-class OpenTelemetryScimTracer(private val tracer: Tracer) : ScimTracer {
+class MyCustomTracer : ScimTracer {
     override fun <T> trace(operationName: String, attributes: Map<String, String>, block: () -> T): T {
-        val span = tracer.spanBuilder(operationName).startSpan()
-        attributes.forEach { (k, v) -> span.setAttribute(k, v) }
-        return span.makeCurrent().use {
-            try {
-                block()
-            } finally {
-                span.end()
-            }
-        }
+        // your tracing logic
+        return block()
     }
 
-    override fun currentCorrelationId(): String? =
-        Span.current().spanContext.traceId.takeIf { it != TraceId.getInvalid() }
+    override fun currentCorrelationId(): String? {
+        // return your correlation ID
+        return null
+    }
 }
 ```
 
-Register it as a Spring bean or pass it directly to `ScimEndpointDispatcher`.
+Register it as a Spring bean and the auto-configuration will use it instead of `OpenTelemetryScimTracer` (thanks to `@ConditionalOnMissingBean`).
 
 ### Disabling Metrics
 

docs/outbox-pattern.md

@@ -127,9 +127,11 @@ sequenceDiagram
 
 ## Using the Outbox Pattern
 
-### Option 1: namastack-outbox (Recommended)
+### Option 1: namastack-outbox (Recommended Pattern)
 
-[namastack-outbox](https://github.com/namastack/namastack-outbox) provides transactional outbox support and is available in Maven Central. It integrates with Spring Modulith's event externalization, meaning events stored via the outbox can be automatically forwarded to Kafka, AMQP, or any other supported broker through Spring Modulith's `EventExternalizationConfiguration`.
+> **Note:** This is a documented integration pattern, not a built-in SDK feature.
+
+[namastack-outbox](https://github.com/namastack/namastack-outbox) provides transactional outbox support and is available in Maven Central. It integrates with Spring Modulith's event externalization, meaning events stored via the outbox can be forwarded to Kafka, AMQP, or any other supported broker through Spring Modulith's `EventExternalizationConfiguration`.
 
 Add the dependency:
 
@@ -141,15 +143,29 @@ Add the dependency:
 </dependency>
 ```
 
-Configure in `application.yml`:
+Implement `ScimEventPublisher` as a Spring `@Component`. The SDK auto-detects it and uses it instead of the default `SpringScimEventPublisher`:
 
-```yaml
-scim:
-  outbox:
-    enabled: true
+```kotlin
+@Component
+class NamastackOutboxAdapter(
+    private val outboxService: OutboxService, // from namastack-outbox
+    private val objectMapper: ObjectMapper,
+) : ScimEventPublisher {
+    override fun publish(event: ScimEvent) {
+        outboxService.store(
+            OutboxEvent(
+                id = event.eventId,
+                type = event::class.simpleName!!,
+                payload = objectMapper.writeValueAsString(event),
+            )
+        )
+    }
+}
 ```
 
-The SDK auto-configures a `NamastackOutboxAdapter` that delegates to namastack-outbox's event publishing. Events are stored transactionally alongside your resource changes and published asynchronously.
+That's it — Spring auto-configuration picks up your `@Component` automatically via `@ConditionalOnMissingBean(ScimEventPublisher::class)`. Events are then stored transactionally alongside your resource changes and published asynchronously by namastack-outbox's poller.
+
+For plain Java (without Spring), wire the publisher manually into `ScimEndpointDispatcher`.
 
 ### Option 2: Custom Implementation
 

scim2-sdk-samples/sample-fullstack-spring/README.md

@@ -78,7 +78,7 @@ curl -s http://localhost:8081/scim/v2/Users | python3 -c "import sys,json; [prin
 
 ## Observability
 
-The sample includes an optional observability stack (Prometheus + Grafana) for monitoring SCIM operations.
+The sample includes an optional observability stack for monitoring and tracing SCIM operations.
 
 ### Start with observability
 
@@ -87,8 +87,9 @@ docker compose --profile observability up -d
 ```
 
 This starts all services plus:
-- **Prometheus** at http://localhost:9091 -- scrapes `/actuator/prometheus` from both SCIM servers
-- **Grafana** at http://localhost:3000 (login: admin / admin) -- pre-built SCIM dashboard
+- **Prometheus** at http://localhost:9091 — scrapes `/actuator/prometheus` from both SCIM servers
+- **Grafana** at http://localhost:3000 (login: admin / admin) — pre-built SCIM dashboard
+- **Jaeger** at http://localhost:16686 — distributed tracing UI (traces from OpenTelemetry)
 
 ### SCIM Dashboard
 
@@ -176,11 +177,14 @@ cd ../shared-frontend && npm install && npm run dev
 
 ## Services
 
-| Service          | URL                        | Description                    |
-|------------------|----------------------------|--------------------------------|
-| Frontend         | http://localhost:5173       | React UI                       |
-| Primary Backend  | http://localhost:8080       | SCIM server + REST API         |
-| Target Backend   | http://localhost:8081       | Outbound provisioning target   |
-| Keycloak         | http://localhost:9090       | Identity provider (admin/admin)|
-| PostgreSQL       | localhost:5432              | Primary database               |
-| PostgreSQL Target| localhost:5433              | Target database                |
+| Service          | URL                        | Description                        |
+|------------------|----------------------------|------------------------------------|
+| Frontend         | http://localhost:5173       | React UI                           |
+| Primary Backend  | http://localhost:8080       | SCIM server + REST API             |
+| Target Backend   | http://localhost:8081       | Outbound provisioning target       |
+| Keycloak         | http://localhost:9090       | Identity provider (admin/admin)    |
+| PostgreSQL       | localhost:5432              | Primary database                   |
+| PostgreSQL Target| localhost:5433              | Target database                    |
+| Prometheus       | http://localhost:9091       | Metrics (observability profile)    |
+| Grafana          | http://localhost:3000       | Dashboards (admin/admin)           |
+| Jaeger           | http://localhost:16686      | Distributed tracing UI             |

scim2-sdk-samples/sample-fullstack-spring/docker-compose.yml

@@ -71,6 +71,8 @@ services:
       SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI: http://keycloak:9090/realms/scim-sample/protocol/openid-connect/certs
       # Outbound provisioning — push changes to the target SCIM server
       SCIM_CLIENT_BASE_URL: http://backend-target:8080/scim/v2
+      # OpenTelemetry — export traces to Jaeger
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4317
     ports:
       - "8080:8080"
     depends_on:
@@ -181,6 +183,15 @@ services:
     depends_on:
       - prometheus
 
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    profiles: ["observability"]
+    ports:
+      - "16686:16686"
+      - "4317:4317"
+    environment:
+      COLLECTOR_OTLP_ENABLED: true
+
 volumes:
   pgdata:
   pgdata-target:

scim2-sdk-samples/sample-fullstack-spring/pom.xml

@@ -57,6 +57,18 @@
             <groupId>io.micrometer</groupId>
             <artifactId>micrometer-registry-prometheus</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-exporter-otlp</artifactId>
+        </dependency>
 
         <!-- Database -->
         <dependency>

scim2-sdk-samples/sample-fullstack-spring/src/main/java/com/example/scim/config/TracingConfig.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2026 Marcos Barbero
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.example.scim.config;
+
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.resources.Resource;
+import io.opentelemetry.sdk.trace.SdkTracerProvider;
+import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class TracingConfig {
+
+    @Bean
+    public OpenTelemetry openTelemetry(
+            @Value("${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4317}") String otlpEndpoint) {
+        var exporter = OtlpGrpcSpanExporter.builder()
+                .setEndpoint(otlpEndpoint)
+                .build();
+
+        var tracerProvider = SdkTracerProvider.builder()
+                .addSpanProcessor(BatchSpanProcessor.builder(exporter).build())
+                .setResource(Resource.builder()
+                        .put("service.name", "scim-sample")
+                        .build())
+                .build();
+
+        return OpenTelemetrySdk.builder()
+                .setTracerProvider(tracerProvider)
+                .buildAndRegisterGlobal();
+    }
+
+    @Bean
+    public Tracer tracer(OpenTelemetry openTelemetry) {
+        return openTelemetry.getTracer("scim-sample");
+    }
+}

scim2-sdk-spring-boot-autoconfigure/pom.xml

@@ -91,6 +91,11 @@
             <artifactId>micrometer-core</artifactId>
             <optional>true</optional>
         </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-api</artifactId>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>org.springframework.security</groupId>
             <artifactId>spring-security-oauth2-jose</artifactId>
@@ -144,6 +149,11 @@
             <artifactId>kotlin-faker</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk-testing</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>io.kotest</groupId>
             <artifactId>kotest-assertions-core-jvm</artifactId>

scim2-sdk-spring-boot-autoconfigure/src/main/kotlin/com/marcosbarbero/scim2/spring/autoconfigure/ScimTracerAutoConfiguration.kt

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2026 Marcos Barbero
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.marcosbarbero.scim2.spring.autoconfigure
+
+import com.marcosbarbero.scim2.core.observability.ScimTracer
+import com.marcosbarbero.scim2.spring.observability.OpenTelemetryScimTracer
+import io.opentelemetry.api.trace.Tracer
+import org.springframework.beans.factory.ObjectProvider
+import org.springframework.boot.autoconfigure.AutoConfiguration
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+
+@AutoConfiguration(before = [ScimServerAutoConfiguration::class])
+@ConditionalOnClass(name = ["io.opentelemetry.api.trace.Tracer"])
+@ConditionalOnProperty(prefix = "scim.tracing", name = ["enabled"], havingValue = "true", matchIfMissing = true)
+class ScimTracerAutoConfiguration {
+
+    @Configuration
+    @ConditionalOnClass(Tracer::class)
+    class OpenTelemetryTracerConfiguration {
+
+        @Bean
+        @ConditionalOnMissingBean(ScimTracer::class)
+        fun openTelemetryScimTracer(tracer: ObjectProvider<Tracer>): ScimTracer? = tracer.ifAvailable?.let { OpenTelemetryScimTracer(it) }
+    }
+}