日志服务 Langfuse SDK Trace 字段说明

本文档定义通过 Langfuse SDK 上报的 Trace 数据字段，包括每个字段的含义、数据类型和取值示例。Agent 可观测支持 Langfuse SDK 通过 OpenTelemetry 协议直接上报数据。此时 SDK 保留自身的字段语义，数据会自动按本文档规范上报，您可以根据此规范查阅字段含义，用于日志检索分析、自定义仪表盘等。
说明：
通过 Langfuse SDK 接入时，您无需修改埋点代码的字段命名，只需调整 Exporter 配置将数据上报至 Agent 可观测，详情请参见 使用 Langfuse SDK 上报 Trace 数据。各接入方式的对比请参见 选择接入方式。
数据模型
Langfuse SDK 基于 OpenTelemetry SDK 实现，每条 Trace 数据底层都是一个 OTel Span，写入 Agent 可观测应用关联的 Trace 日志主题后，每条日志对应一个 Span，由以下三部分组成：
Trace 顶层字段：OTel Span 标准结构，位于日志根层级，例如 traceID、spanID、duration。
Resource 字段：服务与运行环境信息，存储于 JSON 字段 resource 之下。
Attribute 字段：Langfuse 业务语义字段，存储于 JSON 字段 attribute 之下。
在 Trace 日志主题的原始记录中，attribute 和 resource 以 JSON 编码字符串存储，以下示例为解析后的结构。
{
  "traceID": "<32 位十六进制 Trace ID>",
  "spanID": "<16 位十六进制 Span ID>",
  "parentSpanID": "<父 Span ID>",
  "name": "<Span 名称>",
  "kind": "CLIENT",
  "start": "<Unix 纳秒时间戳>",
  "end": "<Unix 纳秒时间戳>",
  "duration": "<纳秒>",
  "statusCode": "OK",
  "resource": {
    "service.name": "<服务名称>",
    "telemetry.sdk.language": "python"
  },
  "attribute": {
    "langfuse.trace.name": "<Trace 名称>",
    "langfuse.environment": "production",
    "session.id": "<会话 ID>",
    "user.id": "<用户 ID>",
    "langfuse.observation.type": "generation",
    "langfuse.observation.model.name": "<模型名称>",
    "langfuse.observation.usage_details": {
      "input": 1000,
      "output": 200,
      "total": 1200
    }
  }
}
查阅字段时，请先确认所需维度，再参阅对应章节：
链路与环境信息：Trace 顶层字段、Resource 字段。
会话级信息：Trace 级字段、会话与用户字段。
单次模型或操作调用：Observation 级字段、LLM 消息字段。
集成框架自动写入的信息：metadata 集成约定字段。
Trace 顶层字段
以下字段为 OpenTelemetry Span 标准结构，位于日志根层级，无需添加前缀。
字段名
类型
说明
示例
traceID
text
Trace 的唯一标识，用于关联同一请求链路中的多个 Span。
17b5f957568ecb90b5b5b58d6bb56cbe
spanID
text
当前 Span 的唯一标识。
b5b5b58d6bb56cbe
parentSpanID
text
当前 Span 的父 Span 标识，用于构建调用链树；根 Span 通常为空。
568ecb90b5b5b58d
name
text
Span 名称，通常等价于操作名。
OpenAI.chat
kind
text
Span 类型，取值为 INTERNAL、CLIENT、SERVER、PRODUCER 或 CONSUMER。
CLIENT
start
long
Span 开始时间，单位为纳秒。
1760000000000000000
end
long
Span 结束时间，单位为纳秒。
1760000001200000000
duration
long
Span 持续时间，单位为纳秒，通常为 end - start。
1200000000
statusCode
text
Span 状态码，取值为 OK、ERROR 或 UNSET。
OK
statusMessage
text
Span 状态信息，仅在状态异常时填充。
request timeout
traceState
text
W3C TraceContext 规范中的 tracestate 内容。
rojo=00f067aa0ba902b7
links
text
当前 Span 关联的其他 Span 链接列表。
[]
logs
text
Span Events，即 Span 上记录的日志事件。
[]
host
text
上报数据的主机。
10.0.0.12
service
text
上报数据的服务名称。
my-agent-app
otlp.name
text
OTLP Exporter 或 SDK 名称。
OpenTelemetry
otlp.version
text
OTLP Exporter 或 SDK 版本。
1.27.0
Resource 字段
Resource 字段由 OpenTelemetry SDK 自动注入，与 Langfuse 解耦，子节点遵循 OpenTelemetry Resource 语义约定，检索时需添加 resource. 前缀。
字段名
类型
说明
示例
resource.service.name
text
产生 Trace 数据的服务名称。
my-agent-app
resource.service.version
text
产生 Trace 数据的服务版本。
1.2.0
resource.deployment.environment
text
部署环境，例如 dev、test 或 prod。
prod
resource.host.arch
text
主机架构，例如 amd64 或 arm64。
arm64
resource.host.id
text
主机标识。
i-0a1b2c3d
resource.telemetry.sdk.language
text
OpenTelemetry SDK 语言，例如 python 或 nodejs。
python
resource.telemetry.sdk.name
text
OpenTelemetry SDK 名称。
opentelemetry
resource.telemetry.sdk.version
text
OpenTelemetry SDK 版本。
1.27.0
resource.process.pid
long
进程 PID。
38215
resource.process.command
text
进程启动命令。
/usr/bin/python3
resource.process.command_args
text
进程启动参数。
["app.py"]
resource.process.executable.name
text
可执行文件名。
python3
resource.process.executable.path
text
可执行文件路径。
/usr/bin/python3
resource.process.owner
text
进程归属用户。
root
resource.process.runtime.name
text
运行时名称，例如 cpython 或 nodejs。
cpython
resource.process.runtime.version
text
运行时版本。
3.11.6
resource.process.runtime.description
text
运行时描述。
CPython 3.11.6
Trace 级字段
以下字段为 Langfuse SDK 在根 Span 上记录的会话级信息，检索时需添加 attribute. 前缀。
字段名
类型
说明
示例
attribute.langfuse.trace.name
text
Trace 名称，由业务定义。
chat-completion
attribute.langfuse.trace.input
text
Trace 的入参，即根 Span 的输入。
用户的原始提问内容
attribute.langfuse.trace.output
text
Trace 的输出，即根 Span 的最终结果。
模型返回的最终答复
attribute.langfuse.trace.tags
text
Trace 标签数组。
["prod","chat"]
attribute.langfuse.trace.public
text
Trace 公开标记。
false
attribute.langfuse.trace.metadata
json
Trace 元数据对象，用于透传业务自定义键值；子字段可单独检索。
{"source":"web","tenant":"t-01"}
attribute.langfuse.environment
text
Langfuse 环境标识，与 OTel deployment.environment 对应。
production
attribute.langfuse.release
text
应用版本或 Release 标识。
v1.2.0
attribute.langfuse.version
text
Langfuse SDK 版本号。
3.0.1
attribute.langfuse.internal.is_app_root
text
是否为应用根 Span。
true
attribute.langfuse.internal.as_root
text
内部根 Span 标记，与 is_app_root 并列使用。
true
此外，Langfuse SDK 提供以下后备字段名。未上报上述 Trace 级字段时，Agent 可观测从后备字段中读取对应内容。
字段名
类型
说明
attribute.langfuse.public
text
attribute.langfuse.trace.public 的后备字段名。
attribute.langfuse.tags
text
attribute.langfuse.trace.tags 的后备字段名。
attribute.langfuse.metadata
json
attribute.langfuse.trace.metadata 和 attribute.langfuse.observation.metadata 的通用后备字段名。
会话与用户字段
以下字段用于按会话和用户维度聚合分析。attribute.session.id 和 attribute.user.id 为推荐使用的字段名，attribute.langfuse.* 为兼容旧版命名的映射字段。
字段名
类型
说明
示例
attribute.session.id
text
会话 ID，用于多轮对话维度的聚合分析。
session-abc
attribute.user.id
text
用户 ID，用于按用户维度的聚合分析。
user-123
attribute.langfuse.session.id
text
兼容旧版命名的会话 ID 映射字段。
session-abc
attribute.langfuse.user.id
text
兼容旧版命名的用户 ID 映射字段。
user-123
注意：
attribute.user.id 的数据类型为 text。请勿上报纯数字并按数值类型检索，否则非纯数字的用户 ID 将检索失败。
Observation 级字段
一个 Observation 对应一个子 Span，类型包括 generation、span 和 event 三类。以下字段记录单次模型调用或操作的详情，检索时需添加 attribute. 前缀。
字段名
类型
说明
示例
attribute.langfuse.observation.type
text
Observation 类型，取值为 generation、span 或 event。
generation
attribute.langfuse.observation.input
json
调用入参，可包含提示词、消息列表和工具描述等。
见 LLM 消息字段
attribute.langfuse.observation.output
text
模型输出或操作结果。
模型返回的文本内容
attribute.langfuse.observation.level
text
日志等级，取值为 DEBUG、DEFAULT、WARNING 或 ERROR。
ERROR
attribute.langfuse.observation.status_message
text
状态信息，与 Span 顶层字段 statusMessage 对齐。
rate limit exceeded
attribute.langfuse.observation.model.name
text
模型名称，generation 类型必填。
gpt-4o
attribute.langfuse.observation.model.parameters
text
模型参数，例如 temperature、top_p 和 max_tokens。
{"temperature":0.7}
attribute.langfuse.observation.usage_details
json
Token 用量对象。
{"input":1000,"output":200}
attribute.langfuse.observation.usage_details.input
long
输入 Token 数。
1000
attribute.langfuse.observation.usage_details.output
long
输出 Token 数。
200
attribute.langfuse.observation.usage_details.total
long
总 Token 数。
1200
attribute.langfuse.observation.cost_details
text
成本详情，按 input、output 和 total 分项记录。
{"total":0.012}
attribute.langfuse.observation.completion_start_time
text
首个 Token 返回时间，用于计算首 Token 时延。
2026-10-23T10:00:01.200Z
attribute.langfuse.observation.metadata
json
Observation 元数据对象，用于透传业务自定义键值；子字段可单独检索。
{"tool_name":"search"}
LLM 消息字段
以下字段为 attribute.langfuse.observation.input 的子字段，记录 LLM 调用的消息与工具信息。检索时需书写完整路径。
字段名
类型
说明
示例
attribute.langfuse.observation.input.messages
text
LLM 消息数组，遵循 OpenAI 标准 messages 格式。
[{"role":"user","content":"..."}]
attribute.langfuse.observation.input.tools
text
LLM 可用工具的描述信息。
[{"name":"search"}]
attribute.langfuse.observation.input.toolCalls
text
工具调用结果。
[{"name":"search","result":"..."}]
注意：
Trace 与 Observation 的输入输出内容、LLM 消息内容可能包含用户数据，请在上报前确认数据合规。
metadata 集成约定字段
以下字段为 OpenAI、LangChain 和 Vercel AI SDK 等集成框架自动写入 metadata 容器的固定键，属于 Langfuse SDK 集成约定而非业务自定义字段。未上报会话与用户字段时，Agent 可观测从以下字段中提取会话 ID、用户 ID 和标签。
字段名
类型
说明
attribute.langfuse.trace.metadata.langfuse_user_id
text
集成框架写入的用户 ID，作为用户 ID 的后备提取来源。
attribute.langfuse.trace.metadata.langfuse_session_id
text
集成框架写入的会话 ID，作为会话 ID 的后备提取来源。
attribute.langfuse.trace.metadata.langfuse_tags
text
集成框架写入的标签，作为标签的后备提取来源。
attribute.langfuse.observation.metadata.langfuse_user_id
text
同上，记录在 Observation 级别。
attribute.langfuse.observation.metadata.langfuse_session_id
text
同上，记录在 Observation 级别。
attribute.langfuse.observation.metadata.langfuse_tags
text
同上，记录在 Observation 级别。
业务自定义字段
除上述字段外，您可以通过 Langfuse SDK 的 metadata 参数透传业务自定义键值，字段名由业务侧决定。透传的键值会落入 attribute.langfuse.trace.metadata 或 attribute.langfuse.observation.metadata 容器，可按完整路径单独检索，例如 attribute.langfuse.trace.metadata.tenant_id。
自定义字段不得覆盖本文档定义的标准字段，且不应上报密码、密钥、Token 或个人敏感信息。
暂不支持的字段
以下 Langfuse SDK 字段当前不参与索引与 SQL 分析。数据中若出现这些字段，仅支持全文检索。
字段名
类型
说明
attribute.langfuse.observation.prompt.name
1个字段
对应 Langfuse 的 Prompt 管理能力，Agent 可观测当前暂不支持。
attribute.langfuse.observation.prompt.version
1个字段
同上。
attribute.langfuse.experiment.*
10个字段
对应 Langfuse 的 Evaluation 与 Experiment 能力，Agent 可观测当前暂不支持。
检索与分析示例
以下示例可直接在 Trace 日志主题的检索分析页使用。
查询近期所有 ERROR 等级的 Observation：
"attribute.langfuse.observation.level":"ERROR"
按模型统计 Token 用量 Top 10：
* | SELECT "attribute.langfuse.observation.model.name" AS model,
           SUM("attribute.langfuse.observation.usage_details.total") AS total_tokens,
           SUM("attribute.langfuse.observation.usage_details.input") AS input_tokens,
           SUM("attribute.langfuse.observation.usage_details.output") AS output_tokens,
           COUNT(*) AS calls
    GROUP BY model
    ORDER BY total_tokens DESC
    LIMIT 10
按用户统计调用次数：
* | SELECT "attribute.user.id" AS uid, COUNT(*) AS cnt
    GROUP BY uid
    ORDER BY cnt DESC
查询单条 Trace 的完整调用链：
traceID:"<Trace ID>"
  | SELECT spanID, parentSpanID, name,
           "attribute.langfuse.observation.type" AS obs_type,
           duration
    ORDER BY start ASC
按模型统计 generation 类型的平均时延：
"attribute.langfuse.observation.type":"generation"
  | SELECT AVG(duration)/1000000 AS avg_ms,
           "attribute.langfuse.observation.model.name" AS model
    GROUP BY model
    ORDER BY avg_ms DESC
按部署环境过滤异常调用：
"resource.deployment.environment":"prod" AND "attribute.langfuse.observation.level":"ERROR"
整包取出 Trace 元数据对象：
* | SELECT "attribute.langfuse.trace.metadata" AS metadata LIMIT 10
按 SDK 语言统计上报版本分布：
"resource.telemetry.sdk.language":"python"
  | SELECT "attribute.langfuse.version" AS sdk_version, COUNT(*) AS cnt
    GROUP BY sdk_version
    ORDER BY cnt DESC
兼容性说明
本文档定义的是 Langfuse SDK 上报路径下的字段语义。不同集成框架和 Observation 类型可能只适用其中一部分字段，具体适用范围请以对应字段章节的说明为准。由于 Langfuse SDK 与 OpenTelemetry 语义规范仍在演进，后续字段定义可能随版本调整，并在版本说明中同步更新。 
字段名	类型	说明	示例
traceID	text	Trace 的唯一标识，用于关联同一请求链路中的多个 Span。	17b5f957568ecb90b5b5b58d6bb56cbe
spanID	text	当前 Span 的唯一标识。	b5b5b58d6bb56cbe
parentSpanID	text	当前 Span 的父 Span 标识，用于构建调用链树；根 Span 通常为空。	568ecb90b5b5b58d
name	text	Span 名称，通常等价于操作名。	OpenAI.chat
kind	text	Span 类型，取值为 INTERNAL、CLIENT、SERVER、PRODUCER 或 CONSUMER。	CLIENT
start	long	Span 开始时间，单位为纳秒。	1760000000000000000
end	long	Span 结束时间，单位为纳秒。	1760000001200000000
duration	long	Span 持续时间，单位为纳秒，通常为 end - start。	1200000000
statusCode	text	Span 状态码，取值为 OK、ERROR 或 UNSET。	OK
statusMessage	text	Span 状态信息，仅在状态异常时填充。	request timeout
traceState	text	W3C TraceContext 规范中的 tracestate 内容。	rojo=00f067aa0ba902b7
links	text	当前 Span 关联的其他 Span 链接列表。	[]
logs	text	Span Events，即 Span 上记录的日志事件。	[]
host	text	上报数据的主机。	10.0.0.12
service	text	上报数据的服务名称。	my-agent-app
otlp.name	text	OTLP Exporter 或 SDK 名称。	OpenTelemetry
otlp.version	text	OTLP Exporter 或 SDK 版本。	1.27.0
Langfuse SDK Trace 字段说明

本页目录：

数据模型

Trace 顶层字段

Resource 字段

Trace 级字段

会话与用户字段

Observation 级字段

LLM 消息字段

metadata 集成约定字段

业务自定义字段

暂不支持的字段

检索与分析示例

兼容性说明
