日志服务 Langfuse SDK Trace 字段说明

注意：说明：

注意：通过 Langfuse SDK 接入时，你无需修改埋点代码的字段命名，只需调整 Exporter 配置将数据上报至 AgentObs，详情请参见 使用 Langfuse SDK 上报 Trace 数据。各接入方式的对比请参见 选择接入方式。

一、数据模型

Langfuse SDK 基于 OpenTelemetry SDK 实现，每条 Trace 数据底层都是一个 OTel Span，写入 AgentObs 应用关联的 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 标准结构，位于日志根层级，无需添加前缀。

三、Resource 字段

Resource 字段由 OpenTelemetry SDK 自动注入，与 Langfuse 解耦，子节点遵循 OpenTelemetry Resource 语义约定，检索时需添加 resource. 前缀。

四、Trace 级字段

以下字段为 Langfuse SDK 在根 Span 上记录的会话级信息，检索时需添加 attribute. 前缀。

此外，Langfuse SDK 提供以下后备字段名。未上报上述 Trace 级字段时，AgentObs 从后备字段中读取对应内容。

五、会话与用户字段

以下字段用于按会话和用户维度聚合分析。attribute.session.id 和 attribute.user.id 为推荐使用的字段名，attribute.langfuse.* 为兼容旧版命名的映射字段。

注意：attribute.user.id 的数据类型为 text。请勿上报纯数字并按数值类型检索，否则非纯数字的用户 ID 将检索失败。

六、Observation 级字段

一个 Observation 对应一个子 Span，类型包括 generation、span 和 event 三类。以下字段记录单次模型调用或操作的详情，检索时需添加 attribute. 前缀。

七、LLM 消息字段

以下字段为 attribute.langfuse.observation.input 的子字段，记录 LLM 调用的消息与工具信息。检索时需书写完整路径。

注意：Trace 与 Observation 的输入输出内容、LLM 消息内容可能包含用户数据，请在上报前确认数据合规。

八、metadata 集成约定字段

以下字段为 OpenAI、LangChain 和 Vercel AI SDK 等集成框架自动写入 metadata 容器的固定键，属于 Langfuse SDK 集成约定而非业务自定义字段。未上报会话与用户字段时，AgentObs 从以下字段中提取会话 ID、用户 ID 和标签。

九、业务自定义字段

除上述字段外，你可以通过 Langfuse SDK 的 metadata 参数透传业务自定义键值，字段名由业务侧决定。透传的键值会落入 attribute.langfuse.trace.metadata 或 attribute.langfuse.observation.metadata 容器，可按完整路径单独检索，例如 attribute.langfuse.trace.metadata.tenant_id。

自定义字段不得覆盖这篇档定义的标准字段，且不应上报密码、密钥、Token 或个人敏感信息。

十、暂不支持的字段

以下 Langfuse SDK 字段当前不参与索引与 SQL 分析。数据中若出现这些字段，仅支持全文检索。

十一、检索与分析示例

以下示例可直接在 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 语义规范仍在演进，后续字段定义可能随版本调整，并在版本说明中同步更新。