maple-agent-tracing-spring-ai

用途：让 Spring AI 应用的每次对话在 Maple Agent Sessions 中呈现为一个会话，每次 ChatClient 调用为一轮，包含转录、模型调用、工具调用（失败会标记）、子智能体通道与 token。

机制：Spring AI 的 Micrometer Observations → micrometer-tracing-bridge-otel → OpenTelemetry SDK → OTLP/HTTP 发送到 Maple，全部由 spring-boot-starter-opentelemetry 提供。默认采样为 10%，提示与回复不会进入 span，工具抛错时 span 仍为 OK；技能中的步骤用于修正这三点。

主要步骤：

1. 检测版本与现有配置：读取 pom.xml / build.gradle(.kts)，目标 Spring AI 2.0.x（已验证 2.0.1）配 Boot 4.x（已验证 4.1.1）、Java 17+；Spring AI 1.1.x 配 Boot 3.5 见步骤 2d。
2. 密钥与区域：美国 https://ingest.maple.dev，欧盟 https://ingest.eu.maple.dev；请求头 Authorization=Bearer <key>，协议为 OTLP/HTTP protobuf。
3. 安装与导出：添加 spring-boot-starter-opentelemetry 依赖，配置 application.properties（endpoint 需含完整 /v1/traces，采样概率必须设为 1.0，否则 90% 轮次会静默丢失），并在 main 中当密钥缺失时关闭导出。
4. 添加配置类 MapleAiObservationConfig：为 ChatClient、工具调用、ChatModel 观察上下文补充 gen_ai.* 属性，并替换 ToolExecutionExceptionProcessor 以标记失败的工具 span。
5. 会话 id：Maple 读取 spring.ai.chat.client.conversation.id，需在每次顶层调用通过 advisors 传入应用已有的会话/线程 id。
6. 工具、错误与子智能体：工具 span 为 execute_tool <name>，失败会标记 ERROR 并把消息返回模型；子智能体调用无需单独 id。

限制：内容捕获开启时每个 chat span 携带完整对话，长对话会使 span 变大；关闭 maple.ai.capture-content 后除失败工具的异常信息与堆栈外不发送内容。不要设置 max-attribute-value-length，截断的 JSON 会被 Maple 丢弃。若已挂载 OTel Java agent，需按步骤 2c 处理，否则每个 Spring AI span 会成为独立 trace。Kotlin 项目需逐条翻译。