文档 / 核心概念

核心概念

本页深入讲解 Langfuse 如何组织和捕获数据的底层概念。理解这些概念会让调试和使用 traces 更加得心应手。

准备开始?查看入门指南来接入你的第一个 trace。

Observations、Traces 与 Sessions

Langfuse 将应用的数据组织为三个核心概念:observations、traces 和 sessions。

Observations 与 Traces

Observations(观测)是应用中的各个独立步骤:LLM 调用、工具调用、检索步骤等等。它们可以嵌套,以反映应用的结构。Langfuse 支持若干 LLM 专属的 observation 类型,例如 generations(生成)和 events(事件)。

trace(追踪)代表单次请求或操作,例如一次聊天机器人交互——从用户提问到最终响应。它是共享同一 trace_id 的所有 observations 的逻辑分组。

Trace 级属性(如 user_id、session_id、tags 和 metadata)存在于该 trace 内的每个 observation 上;SDK 会自动传播它们。从概念上讲,Langfuse 存储一张 observations 表,每一行保存 observation 级数据以及 trace 级属性的副本。这让查询和聚合保持高效。

关于在 observations 表中的日常工作(过滤方法、保存的视图、root-observations 默认值),请参阅使用 observations 表。

Sessions

trace 可以可选地分组为 sessions。 Sessions 用于将属于同一用户交互的多个 traces 归为一组。一个常见的例子是聊天界面中的一个对话线程。

可选地,sessions 可以对 traces 进行聚合:

mermaid

classDiagram
    Session "1" o-- "n" Trace

Langfuse UI 中的 session 示例:

Session 视图

对于具有多轮对话或工作流的应用,推荐使用 sessions。请参阅 Sessions 文档,为你的 traces 添加 sessions。

添加属性

将数据结构化为 traces 和 observations 之后,你可以为它们补充额外的属性。这些属性就像标签,帮助你针对特定用例对 traces 进行过滤、分组和分析。

你可以添加不同类型的属性:

属性	描述
Environments(环境)	隔离来自不同部署上下文的数据,如 `production`、`staging` 或 `development`
Tags(标签)	灵活的标签,按功能、API 端点或工作流对 traces 分类
User(用户)	追踪每个 trace 是由哪个终端用户触发的
Metadata(元数据)	灵活的键值存储,用于自定义信息
Releases & Versions(发布与版本)	追踪应用版本和组件变更

Langfuse 如何捕获数据

理解了数据模型之后,接下来看看 Langfuse 实际是如何捕获和处理 traces 的。

基于 OpenTelemetry 构建

Langfuse 基于 OpenTelemetry 构建——这是一个从应用收集遥测数据的开放标准。

这意味着你不会被锁定只能使用 Langfuse 专属的 SDK。你还可以同时将 traces 发送到多个目的地,比如用 Langfuse 做 LLM 可观测性,用 Datadog 做基础设施监控。

请参阅 OpenTelemetry 集成指南,了解将 OpenTelemetry 与 Langfuse 集成的详细文档。

埋点(Instrumentation)

埋点是向应用添加代码以记录其行为的过程。一旦开启这种记录,Langfuse(通过 OpenTelemetry)就能自动捕获这些事件,并将它们组织成 traces 和 observations。

入门指南将带你完成为应用中的函数添加埋点的完整流程。

后台处理

为了避免拖慢你的应用,Langfuse 不会在 trace 创建的瞬间同步发送它。相反,Langfuse 会在本地将 traces 批量打包,并在后台发送,让你的应用保持快速响应。

mermaid

sequenceDiagram
    autonumber
    participant User as End user
    participant App as Application
    participant SDK as Langfuse SDK
    participant Exporter as Background exporter
    participant Langfuse as Langfuse backend

    loop Incoming requests over time
        User->>App: send request
        App->>SDK: createTrace() / log events
        SDK->>Exporter: enqueue(trace/events)
        Note over App,SDK: Tracing is non-blocking<br/>App continues handling request
        App-->>User: response
    end

    loop In the background
        Note over Exporter: Runs on a timer / batch size
        Exporter->>Langfuse: send(batched traces)
        Langfuse-->>Exporter: ack
    end

长时间运行的应用

上述方式对长时间运行的应用(如 Web 服务器或 API)非常有效,因为后台导出器持续运行,有充足的时间自行刷新批次。

短生命周期的应用

对于启动、执行、然后快速退出的应用(短生命周期应用),存在应用退出时队列中仍有未发送 traces 的风险。

为避免丢失数据,短生命周期的应用必须在退出前显式调用 flush()。这会强制导出器立即发送所有缓冲的 traces,确保进程结束时不会丢失任何数据。

mermaid

sequenceDiagram
    autonumber
    participant User as End user
    participant App as Application
    participant SDK as Langfuse SDK
    participant Exporter as Background exporter
    participant Langfuse as Langfuse backend

    User->>App: start script / job
    App->>SDK: createTrace()
    SDK->>Exporter: enqueue(trace)
    Note over Exporter: Trace buffered in memory

    alt No flush() used
        Note over Exporter: Exporter waits for next<br/>background send
        App-->>User: job finished
        App-->>App: process exits
        Note over App,Exporter: Process terminates before<br/>buffer is sent → traces lost
    else flush() used
        App->>SDK: flush() before exit
        SDK->>Exporter: flush()
        Exporter->>Langfuse: send(all buffered traces)
        Langfuse-->>Exporter: ack
        Note over Exporter: Buffer is now empty
        App-->>User: job finished
        App-->>App: process exits
    end