跳转至

Langfuse 追踪插件

by-framework-trace-langfuse 是针对 Langfuse 的官方插件，支持对 Agent 的执行链路进行深度追踪和可视化。

安装

你可以通过 pip 安装此插件：

pip install by-framework-trace-langfuse

配置

插件通过环境变量进行配置。当所有必要的环境变量都设置好后，插件会自动激活。

环境变量 说明 示例
LANGFUSE_PUBLIC_KEY Langfuse 项目公钥 pk-lf-...
LANGFUSE_SECRET_KEY Langfuse 项目秘钥 sk-lf-...
LANGFUSE_BASE_URL Langfuse API 地址 https://cloud.langfuse.com
BYAI_LANGFUSE_ENABLED (可选) 是否强制开关 true 或 false

功能特性

  • 自动追踪：自动记录任务的开始时间、结束时间、输入参数、输出结果以及执行状态。
  • 异步上报：数据在后台线程异步发送，不影响 Worker 执行主流程。
  • 错误记录：任务失败时会自动捕获并上传堆栈信息。
  • 用户属性关联：自动关联 user_code 和 user_name 到 Trace。

LangGraph 深度集成

本插件可以自动捕获 LangGraph 内部的组件调用。

开启方式

在 Worker 初始化 LangGraphAdapter 时，只需在该 Worker 环境中配置好上述环境变量，即可自动激活追踪。

# 无需修改代码，插件会自动在后台工作
adapter = LangGraphAdapter(graph=my_graph, context=context)
await adapter.run(command)

验证

  1. 启动 Worker 并运行一次任务。
  2. 登录 Langfuse 控制台。
  3. 在 "Traces" 列表下，你将看到以 agent_id 命名的 Trace 记录。
  4. 点击进入，可以看到详细的时间轴和嵌套调用结构。