4. 属性映射（OTel → Langfuse）

---

1. 映射入口

Span 结束时，_LangfuseBatchSpanProcessor.on_end()（或 Simple 版本）调用：

1. _should_skip_span() — 过滤无关 Span
2. _transform_span_for_langfuse() — 重命名 + 属性映射
3. 交给底层 OTLP Exporter 发送

映射逻辑在 _LangfuseMixin._map_attributes_to_langfuse()，按 gen_ai.operation.name 分支。

---

2. 操作类型 → Langfuse Observation 类型

gen_ai.operation.name	Langfuse 语义	langfuse.observation.type
run_runner	Trace 容器 + 根 Observation	span
run_runner_cancelled	取消的 Trace	span
run_agent	Agent 执行 Span	span
call_llm	LLM 调用	generation
execute_tool	Tool 调用	span
其他	通用 Span	span

---

3. Trace 级映射（run_runner）

源属性前缀：trpc.python.agent（下文简称 {p}）

源属性	Langfuse 属性
{p}.runner.name	langfuse.trace.name
{p}.runner.user_id	langfuse.user.id
{p}.runner.session_id	langfuse.session.id
{p}.runner.input	langfuse.trace.input + langfuse.observation.input
{p}.runner.output	langfuse.trace.output + langfuse.observation.output
{p}.runner.* 其余字段	聚合进 langfuse.trace.metadata JSON
{p}.state.begin/end/partial	metadata 中的 state_begin 等
{p}.cancellation.*	metadata 中的 cancellation_reason 等

Span 重命名：名为 invocation 的 Span 会被改名为 {p}.runner.name 的值（如 [trpc-agent]: demo/weather_agent）。

---

4. Generation 映射（call_llm）

源属性	Langfuse 属性
{p}.llm_request	langfuse.observation.input
{p}.llm_response	langfuse.observation.output
llm_request.config	langfuse.observation.model.parameters（JSON）
gen_ai.request.model	gen_ai.request.model（保留）
gen_ai.usage.input_tokens	gen_ai.usage.input_tokens
gen_ai.usage.output_tokens	gen_ai.usage.output_tokens
{p}.instruction.name	langfuse.observation.prompt.name
{p}.instruction.version	langfuse.observation.prompt.version
其他 {p}.*	langfuse.observation.metadata JSON

Langfuse 根据 langfuse.observation.prompt.name/version 自动关联 Instruction 与 Generation。

---

5. Tool Span 映射（execute_tool）

源属性	Langfuse 属性
{p}.tool_call_args	langfuse.observation.input
{p}.tool_response	langfuse.observation.output
gen_ai.tool.name 等	langfuse.observation.metadata 中的 tool_name 等
{p}.state.begin/end	metadata 中的 state_begin / state_end

---

6. Agent Span 映射（run_agent）

源属性	Langfuse 属性
{p}.agent.input	langfuse.observation.input
{p}.agent.output	langfuse.observation.output

---

7. AgentTool 嵌套 Runner 特殊处理

当 {p}.runner.app_name 包含 AGENT_TOOL_APP_NAME_SUFFIX（Agent 作为 Tool 被调用）时：

• 移除 langfuse.trace.name
• 避免子 Runner 的 Span 覆盖根 Trace 名称（Langfuse 只记录第一个 trace.name）

---

8. 旧版 Langfuse 兼容（compatibility_old_version=True）

新版属性	旧版属性
langfuse.user.id	user.id
langfuse.session.id	session.id
langfuse.trace.input	input.value
langfuse.trace.output	output.value
langfuse.trace.metadata	langfuse.metadata
Generation input/output	gen_ai.prompt / gen_ai.completion

适用于 Langfuse v3.90.0 之前的自托管实例。

---

9. 映射流程图

ReadableSpan (OTel 原始)
    │
    ├─ gen_ai.operation.name == "run_runner"?
    │       └─ _map_trace_level_attributes()
    │
    ├─ == "run_agent"?
    │       └─ _map_agent_observation_attributes()
    │
    ├─ == "call_llm"?
    │       └─ _map_generation_attributes()
    │
    ├─ == "execute_tool"?
    │       └─ _map_tool_observation_attributes()
    │
    └─ else
            └─ _map_span_observation_attributes()  # 透传 + type=span
    │
    ▼
Transformed ReadableSpan → OTLP Export → Langfuse

---

10. 与 cc_to_langfuse 映射对比

cc_to_langfuse	trpc-agent
langfuse.trace(...) SDK 调用	langfuse.trace.* Span attributes
container.generation(...)	langfuse.observation.type=generation + input/output attributes
container.span(...)	langfuse.observation.type=span
代码显式构造 Trace 树	OTel Span 父子关系 + Langfuse OTel 解析
usage_details={"input":N,"output":M}	gen_ai.usage.input_tokens / output_tokens

tRPC-Agent 不需要 在业务代码里调用 Langfuse SDK；所有语义通过 OTel attributes 表达。