docs: Add JDBC dependency conflict warning for Spring AI integration

[muxiaoming]

Summary

Add a warning note about OpenTelemetry dependency conflict when using JDBC datasource with Spring AI integration.

Problem

The current documentation doesn't mention that adding JDBC dependencies will cause a version conflict between micrometer-tracing-bridge-otel and opentelemetry-jdbc, leading to application startup failure.

Changes

1. Added a "⚠️ Important: JDBC Dependency Conflict" section before Step 2
2. Documented the root cause of the conflict
3. Provided the workaround solution with XML configuration
4. Added links to the related PR and bug report

Why This Matters

Many Spring AI applications require database access for:

• Storing conversation history
• Managing user data
• Persisting AI-generated content

Without this documentation update, users will encounter cryptic errors and waste time debugging dependency issues.

Related PRs & Issues

• Code fix PR: fix: resolve OpenTelemetry version conflict in Spring AI demo when JDBC datasource is present langfuse-examples#34 (already merged)
• Bug report: bug: OpenTelemetry version conflict when using JDBC with Spring AI langfuse#14312 (already closed)
• Documentation tracking: docs: Add JDBC dependency conflict warning for Spring AI integration #3116 (already closed)

Test Plan

• Review the added warning section for clarity
• Verify the XML configuration snippet is correct
• Check that the links to related PR and issue work

Greptile Summary

This PR adds a new "⚠️ Important: JDBC Dependency Conflict" warning section to the Spring AI integration guide, documenting a known opentelemetry-instrumentation-api-incubator version conflict that causes application startup failure when JDBC dependencies are added alongside the OpenTelemetry stack.

• The workaround XML snippet hardcodes opentelemetry-instrumentation-api-incubator:2.17.0-alpha, but the guide's own <dependencyManagement> block already imports opentelemetry-instrumentation-bom:2.28.1, which manages a newer 2.28.x-alpha version of that artifact — applying the fix as written would downgrade the artifact and likely reproduce the conflict under a different form.
• Specific Spring Boot and OTel version numbers in the explanation (1.4.4, 2.9.0-alpha) are tied to Spring Boot 3.4.x and will silently become misleading as users upgrade.
• No Gradle equivalent of the Maven exclusion snippet is provided, despite the guide explicitly supporting Gradle users.

Confidence Score: 3/5

The documented workaround contradicts the BOM version already prescribed in the same guide and should be corrected before merging.

The core fix in the XML snippet pins opentelemetry-instrumentation-api-incubator to 2.17.0-alpha, but the same guide's dependencyManagement imports opentelemetry-instrumentation-bom:2.28.1, which already manages that artifact at a 2.28.x-alpha version. A user following the guide end-to-end would apply this snippet and silently downgrade the incubator artifact below what the BOM expects, likely causing a different runtime failure. The intent of the section is good and the underlying conflict is real, but the prescribed version needs to be reconciled with the BOM already in use.

content/integrations/frameworks/spring-ai.mdx — specifically the explicit version pin in the workaround snippet and its relationship to the BOM declared earlier in the same file.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User adds spring-boot-starter-jdbc] --> B[Maven dependency resolution]
    B --> C{Version conflict?}
    C -- micrometer-tracing pulls in opentelemetry-instrumentation-api-incubator:2.9.0-alpha --> D[opentelemetry-jdbc:2.17.0-alpha needs 2.17.0-alpha]
    D --> E[Maven picks older 2.9.0-alpha nearest-wins strategy]
    E --> F[setCaptureQueryParameters method missing - Application fails to start]
    C -- No JDBC dep --> G[Application starts normally]
    F --> H{Apply fix from docs}
    H --> I[Exclude opentelemetry-instrumentation-api-incubator from micrometer-tracing-bridge-otel]
    I --> J[Explicitly declare version 2.17.0-alpha]
    J --> K{BOM already imports opentelemetry-instrumentation-bom:2.28.1?}
    K -- Yes --> L[2.17.0-alpha overrides BOM - Downgrade conflict]
    K -- No --> M[Correct version used - Application starts]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User adds spring-boot-starter-jdbc] --> B[Maven dependency resolution]
    B --> C{Version conflict?}
    C -- micrometer-tracing pulls in opentelemetry-instrumentation-api-incubator:2.9.0-alpha --> D[opentelemetry-jdbc:2.17.0-alpha needs 2.17.0-alpha]
    D --> E[Maven picks older 2.9.0-alpha nearest-wins strategy]
    E --> F[setCaptureQueryParameters method missing - Application fails to start]
    C -- No JDBC dep --> G[Application starts normally]
    F --> H{Apply fix from docs}
    H --> I[Exclude opentelemetry-instrumentation-api-incubator from micrometer-tracing-bridge-otel]
    I --> J[Explicitly declare version 2.17.0-alpha]
    J --> K{BOM already imports opentelemetry-instrumentation-bom:2.28.1?}
    K -- Yes --> L[2.17.0-alpha overrides BOM - Downgrade conflict]
    K -- No --> M[Correct version used - Application starts]

Loading

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
content/integrations/frameworks/spring-ai.mdx:239
**Hardcoded version likely conflicts with the BOM already in the guide**

The fix explicitly pins `opentelemetry-instrumentation-api-incubator` to `2.17.0-alpha`, but the main pom.xml example already imports `opentelemetry-instrumentation-bom:2.28.1` in `<dependencyManagement>`. That BOM manages `opentelemetry-instrumentation-api-incubator` at a `2.28.x-alpha` version, so the hardcoded `2.17.0-alpha` would actually *override* the BOM and downgrade the artifact — trading one version conflict for another. The safer fix is to omit `<version>` entirely (letting the BOM resolve it) and add a comment explaining why, or pin to the version that matches the BOM in use.

### Issue 2 of 3
content/integrations/frameworks/spring-ai.mdx:198
**No Gradle equivalent provided for the workaround**

The Step 1 preamble explicitly says "Gradle users can include equivalent coordinates in Gradle," but the JDBC conflict workaround only shows Maven XML. Users who followed the guide with Gradle will have no guidance on how to apply the exclusion and explicit version declaration in their `build.gradle` or `build.gradle.kts`.

### Issue 3 of 3
content/integrations/frameworks/spring-ai.mdx:217-218
**Version numbers are tied to specific Spring Boot 3.4.x and will silently age**

The explanation hardcodes `1.4.4`, `2.9.0-alpha`, and `2.17.0-alpha` as concrete version numbers without a note that these will change as users upgrade Spring Boot or the OTel BOM. A reader on Spring Boot 3.5.x will see different version numbers in their error message and may not recognise that this section applies to them. Adding a brief "actual versions may differ — look for the same `setCaptureQueryParameters` error" qualifier would keep the doc useful across upgrades.

_{Reviews (1): Last reviewed commit: "docs: Add JDBC dependency conflict warni..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[vercel]

@muxiaoming is attempting to deploy a commit to the langfuse Team on Vercel.

A member of the Team first needs to authorize it.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[muxiaoming]

✅ Issues Fixed

I've addressed all 3 code review issues from Greptile:

1. Removed hardcoded version

• Removed <version>2.17.0-alpha</version> from the XML snippet
• Added note explaining that the BOM manages the version automatically

2. Added Gradle equivalent

• Added Gradle configuration snippet for excluding the dependency

3. Made version numbers generic

• Changed specific version numbers (1.4.4, 2.9.0-alpha, 2.17.0-alpha) to generic descriptions
• Added note that exact versions may vary

The fix now works correctly with the BOM defined earlier in the guide. No version conflicts!

---

Commit: b3ecefe (latest)
Previous review was on: 8a8c891 (before fixes)

[muxiaoming]

✅ Code Review Issues Fixed

I've addressed all 3 code review issues from Greptile in the latest commit (b3ecefe4):

1. Removed hardcoded version

• Removed <version>2.17.0-alpha</version> from the XML snippet
• Added note explaining that the BOM manages the version automatically

2. Added Gradle equivalent

• Added Gradle configuration snippet for excluding the dependency

3. Made version numbers generic

• Changed specific version numbers (1.4.4, 2.9.0-alpha, 2.17.0-alpha) to generic descriptions
• Added note that exact versions may vary

---

Please re-trigger Greptile review on the latest commit.

The fix now works correctly with the BOM defined earlier in the guide. No version conflicts!

Commit: b3ecefe (latest)
Previous review was on: 8a8c891 (before fixes)