Repository navigation
Agent Logs OTLP and Langfuse CN
Langfuse 通过公开官方运行时插件提供，源码在 @taichuy/langfuse。它支持把 Agent Flow 原生聊天日志和 Agent Logs 采集日志发送到 Langfuse，也支持将 Langfuse Trace 导入明确选择的 Agent Logs 应用。
底座负责来源适配、会话/任务/事件事实、标准 OTLP 和调用权限；插件负责 Langfuse API、转换、分页、连接设置。两种日志使用统一交换语义，保留各自存储职责。导入生成历史事实，不创建可执行的 Agent Flow run。
- 获取公开官方 Langfuse 运行时
.1flowbasepkg包，在扩展中心通过上传包完成安装并激活，授予操作所需贡献权限及用户操作权限。宿主需要支持配套的ApplicationLogsV1、HttpEgressV1回调；升级时先部署配套宿主。本轮验证的是 CI 包上传安装；正式目录发布另行处理，不能据此认为插件已上架。 - 打开 设置 → Langfuse（
/settings/langfuse），点击共享表格的 添加实例。一个保存的连接占一行，表格支持分页、列偏好和移动端行布局。页面中英文跟随宿主全局语言设置。 - 在实例抽屉填写名称、Langfuse 部署根地址，以及目标项目的 Public key、Secret key。地址可以是 Langfuse Cloud 或自托管地址，支持路径前缀；不要填写 Trace 页面、OTLP endpoint 或包含密钥的 URL。
- 点击 保存、重新加载，核对该行名称、地址和凭据状态，再用该行的 测试连接 访问实际项目 API。行内还提供编辑、删除、导出和导入。名称和地址可以重复，稳定
instance_id区分连接及凭据。
地址保存在插件自有配置中，密钥由宿主凭据服务管理。读取配置只返回地址与凭据是否已配置，不返回密钥。编辑时密钥框为空；两个都留空只保留此实例的现有凭据，替换时成对提供。重命名保留身份与凭据，删除只移除此实例及其凭据。旧连接以 default 实例显示。1flowbase 服务端需要能够访问 Langfuse，出站路由由宿主网络中心的受管插件消费者管理。
- 点击目标 Langfuse 实例行的 导出，在 导出应用日志抽屉选择来源应用：支持 Agent Flow 和 Agent Logs。
- 填写记录开始时间范围，使用含时区的 RFC3339，例如
2026-10-01T00:00:00+08:00到2026-10-16T00:00:00+08:00。下界包含，上界不包含；范围选择记录，不截取记录内部事件。 - 点击 导出完整记录。插件遍历全部选择页，逐条读取完整事实并发送到 Langfuse。
- 核对实际回执
exported_records、exported_spans、trace_ids，到同一 Langfuse 项目按 Trace ID 检查输入、输出、Span 及 metadata。
记录数、会话数、Trace 数和事件/Span 数不是同一单位。同一个来源会话可以包含多个任务。原生导出读取完整归档、规范消息及实际关联调用，不用页面摘要代替正文；不根据文本或缺失时间猜测成功与任务结束。
- 点击来源 Langfuse 实例行的 导入，在 导入到 AgentLogs抽屉选择目标 Agent Logs 应用，并确保该应用已启用日志接收。
- 输入多个 Trace ID（逗号、空白或换行分隔），或启用 按日期选择 Trace并填写含时区的日期范围。
- 点击 导入完整 Trace。每个 Trace 的 observation 分页完整读取后再转换、导入。日期选择按 Trace 开始时间，采用下界包含、上界不包含的范围；选中后导入整条 Trace。Langfuse v4
events_only部署使用受支持的 observations v2 接口。 - 查看
accepted_events、duplicate_events、record_ids，进入目标应用日志检查对话和原始轨迹。重复导入相同来源事实会去重；相同身份、不同内容会报冲突。
宿主每次按真实调用者重新验证应用权限、工作区、操作授权和接收状态。插件在系统作用域激活不代表用户能读取其他工作区。应用 API Key 用于采集上报；插件设置使用登录 session、CSRF 和独立操作授权。
Langfuse 提供 OpenAPI。插件从所选实例地址下的 generated/api/openapi.yml 读取规范，复用保存的项目凭据。聊天交换需要的语义转换由前述导入/导出接口承担；其他 API 保持薄封装，由 AI 根据实际规范填写参数。
以下均为 /api/console/managed-services/langfuse 下的 POST：
| 路径 | JSON 请求 | 结果 |
|---|---|---|
/openapi/discover |
{"instance_id":"<id>","search":"observations"}；search、tag 可选 |
完整匹配的 operationId、method、path、摘要及 tags |
/openapi/get |
{"instance_id":"<id>","operationId":"<discover 返回的 ID>"} |
操作原结构、继承/覆盖后的参数和本地 $ref 依赖组件；省略 operationId 返回完整规范 |
/openapi/execute |
{"instance_id":"<id>","operationId":"<实际 ID>","query":{"limit":1}} |
实际上游 response.status、headers、body_base64 和可解析的 JSON body
|
按需提供 path、query、body，字段名与上游规范一致。支持 simple 标量路径参数及 form 查询标量/数组；不支持的编码或缺失路径参数明确失败。凭据仅由插件注入，调用方不能覆盖认证、任意 header 或 URL。规范中的 servers 不会改写所选实例目标。
宿主外层 HTTP 200 表示调用已返回；上游是否成功须检查 data.response.status。上游 403、404、429、500 等状态及错误正文保留，body_base64 是响应原始字节。规范每次读取，不探测接口可用性，不自动切换端点、替换操作或重试。由 AI 读取错误后自行决定下一步。
MCP 协议入口为 /api/mcp/{instance_id}，复用宿主受管服务投影，工具目录为 /plugins/langfuse，固定注册四个工具：plugin.langfuse.instances.list、plugin.langfuse.openapi.discover、plugin.langfuse.openapi.get、plugin.langfuse.openapi.execute。先 mcp_list 找到工具，再 mcp_get 读取参数契约并 mcp_call 执行；如果结果提供 continuation，按返回说明用 mcp_result 读取，勿重复执行原操作。权限继续由宿主统一管理，不为每个上游 API 生成工具。
执行前可按 mcp_get.call_parameters 使用宿主已有返回控制，在 mcp_call 外层选择结构化字段，例如：
{
"tool_id": "plugin.langfuse.openapi.execute",
"arguments": {"instance_id": "<id>", "operationId": "<discover 返回的 ID>"},
"response_fields": ["/success", "/response/status", "/response/headers", "/response/body"],
"max_inline_chars": 16000
}max_inline_chars 是调用方选择的返回预算，不是插件的记录数量上限。HTTP 保留完整 body_base64；MCP 可选择状态、响应头和完整 JSON 正文，避免将原始 base64 带入默认详情视图。选中结果按宿主 JSON Pointer entries 返回；如有 continuation，按返回指引读取。outcome: succeeded 且 detail_unavailable 表示操作已执行而详情不可用，不应重复执行原操作。
自身导出将中立 OTLP 属性 1flowbase.agent_log.source_fact 转成 Langfuse metadata 的 1flowbase_agent_log 字符串，保留带版本的 base64 原始事件；导入时恢复。它保留来源身份、顺序、正文、工具、用量、关系及嵌套 raw。缺失或冲突事实明确暴露；损坏、有歧义的自身 capsule 不会静默按恢复成功处理。外部 Trace 只转换实际存在的标准消息、工具、用量及关系，不根据 endTime 推断任务成功。
多来源导入按来源批次原子提交，整体操作可能部分完成。失败时查看错误码、已确认进度和当前步骤详情；未返回的记录 ID 不会伪造。使用未改变的来源事实重试，已提交事件会去重。远端导出有拒绝或警告时也不能视为完整成功。部分 Langfuse 部署通过队列异步处理；导出回执确认接收，实际入库结果应在 Langfuse 中核对。
插件不设置业务条数或正文大小上限。操作受宿主已有 deadline、取消和传输安全预算约束；超过预算明确失败，不静默截断。可以缩小日期范围后重试。
应用日志页保留 日志交换 → 导出/导入 OTLP JSON；原生 ZIP 归档独立保留。标准 OTLP 导出既支持原生来源，也支持采集来源；导入目标为 Agent Logs。
| 接口 | 输入与结果 |
|---|---|
POST /api/console/applications/{id}/logs/otlp/export |
非空 record_ids 或 log_conversation_ids 二选一；返回标准 OTLP JSON 对象 |
POST /api/console/applications/{id}/logs/otlp/import |
{ "otlp": { "resourceSpans": [...] } }；回执含接收数、重复数和记录 ID |
插件 API 前缀为 /api/console/managed-services/langfuse。实例提供 GET/POST /instances、PUT/DELETE /instances/{instance_id} 和 POST /instances/{instance_id}/test；列表返回 items、page、page_size、total，默认页码 1、每页 50，不限制实例总数。GET /applications、POST /records/query、POST /export、POST /import 保留完整交换能力，导出/导入提交所选行的 instance_id。旧 GET/PUT /config、POST /test 只操作 default；旧交换调用省略实例时也只选 default，不会选择任意第一行。插件业务结果位于 data，应核对 success；失败含 error.code、可选 error.status、error.details。仅 HTTP 2xx 不代表交换完整成功。
旧内置 /logs/langfuse/export、/logs/langfuse/import 已由插件设置页和上述插件接口替代。调用方须迁移到插件 API，不再随每次交换提交远端凭据。标准 OTLP Console 接口仍采用既有 HTTP 错误语义，包括部分导入的 409 agent_logs_partial_import；公开 SDK 接收端采用标准 OTLP acknowledgement。
移动端实测
2026-10-15 在 Langfuse v4.44.0 OSS 完成插件 0.2.0 的实际桌面（1440×1000）与移动（390×844）浏览器验收，共 20 张真实截图：插件 CI / 安装包产物、宿主运行态 CI。从插件 CI artifact 获取 .1flowbasepkg，在扩展中心上传；该验收包未签名，上传时按页面提示核对并确认已知风险。
插件源码 1c37a68b；宿主运行二进制源码 f8a41c1af，API 源码树与验收候选 a29c39e79 和当时 dev 23404a0cc 一致。插件 SDK 的 Git pin 为 a72190c9b，与运行态是不同提交，相关日志、出站、受管设置、MCP 和共享表格契约已核对兼容；没有把不同版本冒充为同一构建。
桌面和移动端均完成双实例新增、重命名、凭据留空保留、重新加载、认证隔离、删除及宿主中英文切换。实际导出覆盖采集日志 21 个事件（3 个任务、2 个会话）和原生日志 5 个事件，Langfuse 完整回读共 26 个唯一事实；指定目标首次导入接收 26，重复导入接收 0 / 重复 26，日期选择导入 2 条 Trace、接收 0 / 重复 21。完整原始事件相等、稳定身份、顺序及历史导入无可执行 run 均通过。
实际 OpenAPI 发现与完整规范的 117 个操作一致，Schema 引用、项目 200、observations 200 和非法参数的原始 400 正文及字节均通过。四个固定 MCP 工具完成真实 PAT 的发现、获取和调用；execute 使用上述已声明返回控制，完整 JSON 正文与实际 HTTP 结果逐字段一致。插件精确候选 CI 43 项 Rust 测试通过；既有标准 OTLP、授权及前端证据只在已核对未变化的范围内复用。
包 SHA-256：9856b649e09f2f91604eaea39edb34d40415a8cab81bfd7757a260fb5d39936e。临时实例、凭据、PAT、会话和语言均完成独立清理，原有连接及候选节点状态恢复。本轮仅使用独立候选端口，未重启现有 7600 / 7800 服务；正式目录发布及运行中热重装不在已验证范围内。
接收端只支持 HTTP Trace：POST /api/logs/otlp/v1/traces，JSON 或 protobuf，可使用 gzip。本轮不提供 gRPC、Metrics 或 Logs receiver。使用应用 API Key：Authorization: Bearer <APPLICATION_KEY>。
下面配置对应 OpenLIT TypeScript 1.15.0 与 Python 1.45.0。在需要观测的 SDK 调用前初始化，并遵守框架要求的初始化和 import 顺序。OpenLIT 提供被观测 SDK 中可获得的事实，不自动采集所有真人消息、Agent 工具或任务终态。
import OpenLIT from 'openlit';
OpenLIT.init({
otlpEndpoint: 'https://YOUR_HOST/api/logs/otlp',
otlpHeaders: { Authorization: 'Bearer <APPLICATION_KEY>' },
disableMetrics: true,
disableEvents: true,
});该 SDK 使用 HTTP JSON Trace exporter，并在 otlpEndpoint 后追加 /v1/traces。不要在根地址中重复填写这一后缀。
import os
# 在 import OpenLIT 前设置，确保选择 HTTP exporter。
os.environ['OTEL_EXPORTER_OTLP_PROTOCOL'] = 'http/protobuf'
os.environ['OTEL_EXPORTER_OTLP_TRACES_ENDPOINT'] = (
'https://YOUR_HOST/api/logs/otlp/v1/traces'
)
import openlit
openlit.init(
otlp_headers={'Authorization': 'Bearer <APPLICATION_KEY>'},
disable_metrics=True,
disable_events=True,
)Python 未配置 gRPC 时默认使用 HTTP protobuf exporter。上面的 Trace 专属端点是完整 URL。执行真实的被观测调用后，在进程退出前等待 SDK batch exporter 完成 flush，再到应用日志查看记录与轨迹。
OpenLIT CLI 可同时发送 Metrics 和 Trace。其他信号应分别配置到支持的后端；将 CLI 通用 endpoint 指向这里，不能证明 CLI 全部遥测能力可用。
插件是独立 Rust 项目，显式声明下列直接依赖；版本由已提交的 Cargo.lock 固定。前端复用宿主 React、Ant Design、@1flowbase/plugin-settings 和公开 @1flowbase/data-table，没有新增 npm 包。
| 包与锁定版本 | 用途 |
|---|---|
runtime-extension-sdk 0.5.6（配套宿主精确 Git revision） |
统一回调、凭据、插件数据、日志与出站客户端 |
tokio 1.53.3 |
异步受管 worker |
serde 1.0.229、serde_json 1.0.154 |
协议与日志 JSON |
base64 0.22.1、sha2 0.10.9 |
capsule、Basic 认证编码与稳定标识 |
url 2.5.8、time 0.3.55 |
服务地址和 RFC3339 范围 |
prost 0.14.1 |
解码标准 OTLP protobuf acknowledgement |
uuid 1.28.0 |
已有间接依赖改为直接声明并启用 v4，生成稳定实例 ID |
serde_yaml 0.9.34+deprecated |
本轮直接声明，解析所选实例 OpenAPI YAML 为 JSON；保留上游 deprecated 标记 |
YAML 解析闭包包含 ryu 1.0.23、unsafe-libyaml 0.2.11，复用宿主/缓存已有版本。插件锁定总包数由 225 变为 228；已有共同外部包的版本、校验和与依赖边未升级。本地未新增安装依赖。