bug: LiteLLM gateway prompt to traces linking

快速结论：当通过 LiteLLM 代理接入 Langfuse 的 OTEL 链路跟踪后，在请求体 metadata 里添加 prompt 相关字段却无法把 trace 与提示词管理中的 Prompt 关联时，优先确认这是当前不支持的能力，而不是字段写错。核心报错关键词为：bug: LiteLLM gateway prompt to traces linking。

适用环境：Issue 已确认使用 Langfuse Cloud、LiteLLM 1.80.11，通过 OTEL 将 LiteLLM 作为 LLM Gateway 接入 Langfuse；操作系统、Python、CUDA、显卡未在 Issue 中说明。

最快修复方案：暂无确认的一步修复方案。Issue 明确说明 OTEL 方式暂不支持 Prompt 与 Trace 关联，唯一官方支持的方式是改用 LiteLLM 原生集成（基于 Langfuse SDK）。

注意事项：在请求体 metadata 中加 prompt_id、prompt_version、observation_prompt_name、prompt 对象等写法不会被识别。自行映射 OTEL 属性属于实验性做法，需要修改 LiteLLM 代理发出 span 的方式，未经验证，可能随版本变化失效。

问题场景

用户将 LiteLLM 作为 LLM Gateway 部署，并按官方指南通过 OTEL 接入 Langfuse，普通链路跟踪工作正常。用户在 Langfuse 提示词管理中创建了 Prompt，然后通过 LiteLLM 的 /chat/completions 接口发请求，在请求体 metadata 里尝试了多种 prompt 字段（prompt_id/prompt_version、observation_prompt_name/observation_prompt_version、嵌套 prompt 对象等），希望 Trace 与提示词管理中的 Prompt 建立关联，但 Langfuse 界面上始终看不到关联结果。

报错原文

bug: LiteLLM gateway prompt to traces linking

原因分析

根据 Issue 讨论，Langfuse 通过 OTEL 建立 Prompt 与 Trace 关联时，期望的是特定 span 属性，例如 observation.prompt.name、langfuse.prompt.name，或 ai.telemetry.metadata.langfusePrompt 中的 JSON 字符串；而不是请求体 metadata 里的嵌套 prompt 对象或通用元数据字段。LiteLLM 代理默认不会输出这些属性，因此即使请求中携带了 prompt 信息，OTEL 摄入后也不会在 Langfuse UI 中形成 Prompt 关联。可能原因还包括用户对“请求 metadata”与“OTEL span 属性”两层机制的理解存在偏差。

环境排查

确认 Langfuse 是否为 Cloud 或自托管，以及具体版本。
确认 LiteLLM 版本（Issue 中为 1.80.11）。
确认接入方式是 LiteLLM 代理 + OTEL，而非原生 LiteLLM 集成（Langfuse SDK）。
检查 LiteLLM 实际发出的 OTEL span 中是否包含 observation.prompt.name、langfuse.prompt.name 或 ai.telemetry.metadata.langfusePrompt 等属性。
确认 Langfuse 中 Prompt 名称与请求中使用的名称完全一致，且版本存在。

解决步骤

先确认问题性质：当前通过 LiteLLM 代理 + OTEL 的方式，Langfuse 不原生支持 Prompt 到 Trace 的关联，仅修改请求体 metadata 无法解决。
如需 Prompt 关联，改用 LiteLLM 的原生 Langfuse 集成（基于 Langfuse SDK），这是 Issue 中说明的唯一官方支持方式。
如必须继续使用 OTEL，可优先尝试在 LiteLLM 代理侧将 prompt 信息映射为 Langfuse 期望的 OTEL span 属性，例如 observation.prompt.name、langfuse.prompt.name，或以 JSON 字符串形式写入 ai.telemetry.metadata.langfusePrompt。这需要自定义修改 LiteLLM 代理的 span 输出逻辑，属于实验性方案。
若该能力对工作流关键，可在 LiteLLM 仓库提交功能请求，推动代理侧直接输出兼容 Langfuse 的 prompt 属性。
排查完成后，移除请求体中无效的 prompt、prompt_id 等字段，避免误以为配置已生效。

验证方法

在 Langfuse 中重新发起一次请求后，打开对应 Trace，查看是否出现 Prompt 关联信息（Prompt 名称与版本）。如使用自定义 span 属性方案，可先检查 LiteLLM 发出的 span 属性是否包含 Langfuse 期望的键名，再确认 Trace 详情页是否显示关联的 Prompt。