用途：把 Haystack 3 的智能体与 Pipeline 运行追踪到 Maple，实现一次会话对应一个 Maple Agent Session，包含对话记录、模型调用、工具调用（失败标记）、Token 用量，OpenRouter 上还含成本。
前置检测：用 python -c "import haystack; print(haystack.version)" 确认 haystack-ai >=3.0（该指南在 3.2 验证）；2.x 不支持此技能。定位 Agent(、Pipeline(、.run(、AgentTool(、PipelineTool() 运行点与每次请求可用的 chat/thread id。若已有 OTel Provider 则复用，只加 Maple exporter 与 enable_tracing；移除 HaystackInstrumentor().instrument()、OpenLLMetry 的 Haystack instrumentor 及既有 OpenTelemetryTracer/OpenTelemetryConnector，避免模型调用重复。
密钥与区域：美国端点 https://ingest.maple.dev，欧盟端点 https://ingest.eu.maple.dev；头部 Authorization=Bearer <key>，协议 http/protobuf。未提供密钥时可用字面量 MAPLE_TEST（会被接收并丢弃），并提示用户替换为 Settings → Ingestion 中的密钥。私钥 maple_sk_ 不得放入浏览器代码。密钥未设置时应记录一条警告并跳过 Maple exporter，保证应用正常运行，不得抛错或使用 Bearer None。
安装：pip install "haystack-ai>=3.2" "opentelemetry-haystack>=1.0" "opentelemetry-sdk>=1.45" "opentelemetry-exporter-otlp-proto-http>=1.45"，并按仓库包管理器（uv add、poetry add 等）处理。
初始化：在首次 pipeline.run()/agent.run() 前，用 TracerProvider、BatchSpanProcessor、OTLPSpanExporter 与 tracing.enable_tracing(MapleHaystackTracer(trace.get_tracer("haystack"))) 初始化；tracer 名必须为 haystack，service.name 需为真实值。环境变量 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_PROTOCOL。
会话与内容：Haystack 无会话概念，需用 conversation(<稳定 chat id>) 包裹每次运行，写入 gen_ai.conversation.id；不得用每请求 UUID 或全局常量。content=True 写入消息、系统指令、工具参数与结果；content=False 保留模型、Token、成本、停止原因、工具名与失败，丢弃消息与内容标签。
验证与限制：跑一次真实对话（≥2 轮、至少一次工具调用），确认 scope 为 haystack、LLM span 具备 chat 与 Token 属性、工具 span 名称真实、失败工具 status Error、同一会话 conversation.id 一致、无重复模型调用、无密钥泄漏。已知缺口：无 gen_ai.provider.name、无 gen_ai.response.id、工具 span 无 tool call id，成本仅 OpenRouter 提供。